Skip to content

Commit 419200b

Browse files
cliffhallclaude
andcommitted
docs: show which feature belongs to which protocol era; changesets for #4852
- everything: README and docs mark each feature 2026-07-28, 2025-era or both, describe the per-era transports and factory, the tasks extension, minted resources and the deprecations; the instructions name the era-only tools. - AGENTS.md: the rule for serving both eras without session-keyed state. - Minor changesets for the four TypeScript servers. Part of #4852 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 9ef661c commit 419200b

13 files changed

Lines changed: 254 additions & 121 deletions
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-everything": minor
3+
---
4+
5+
Serve the 2026-07-28 protocol revision alongside the 2025 era (#4852), over stdio (`serveStdio`) and Streamable HTTP (one `/mcp` endpoint: `createMcpHandler` for 2026-07-28 requests, the existing sessionful transport for 2025-era clients). New for 2026-07-28 clients: `server/discover`, multi-round-trip requests (`input_required`) for the elicitation, sampling and roots tools, `subscriptions/listen` change notifications, cache hints (`ttlMs` / `cacheScope`), and the tasks extension (`io.modelcontextprotocol/tasks`, advertised under `capabilities.extensions`), on which `simulate-research-query`, `trigger-sampling-request-async` and `trigger-elicitation-request-async` return. New tools on both eras: `trigger-multi-step-elicitation` (`requestState` across rounds), `trigger-log-messages` (per-request log levels), `trigger-list-changed`, `trigger-resource-update`, and `get-header-params` (`x-mcp-header` and JSON Schema 2020-12 schemas). `toggle-simulated-logging` and `toggle-subscriber-updates` are offered to 2025-era clients only, labelled deprecated with the roots, sampling and logging tools. For 2025-era clients: `get-roots-list` asks the client for its roots on every call; a failed sampling, elicitation or roots request is reported as `Fulfilling input required by 'tools/call' failed: <message>`; a read of a dynamic resource with an invalid id is answered `-32602` with the URI in `data`; and the toggle tools' messages and the subscription acknowledgements no longer name a session id. The HTTP+SSE transport prints a deprecation warning on start.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-filesystem": minor
3+
---
4+
5+
Serve the 2026-07-28 protocol revision alongside the 2025 era on stdio, through the SDK's `serveStdio` entry (#4852). A 2026-07-28 connection has no `initialize` and no server-to-client `roots/list`, and Roots is deprecated as of that revision, so the command-line directories are its whole allow-list; a server started with none answers each tool call on such a connection with an error saying so. 2025-era clients keep the Roots behavior they had. The README now recommends command-line directories over Roots (#4844).

‎.changeset/memory-modern-era.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-memory": minor
3+
---
4+
5+
Serve the 2026-07-28 protocol revision alongside the 2025 era on stdio, through the SDK's `serveStdio` entry (#4852). A 2026-07-28 client gets `notifications/resources/updated` for `memory://knowledge-graph` on a `subscriptions/listen` stream whose `resourceSubscriptions` name it; 2025-era clients still subscribe with `resources/subscribe`.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-sequential-thinking": minor
3+
---
4+
5+
Serve the 2026-07-28 protocol revision alongside the 2025 era on stdio, through the SDK's `serveStdio` entry (#4852). The thought history lasts as long as the client's connection, on either era.

‎AGENTS.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -594,6 +594,14 @@ would not, burns turns, and buries the result under no-op turns.
594594
`https://modelcontextprotocol.io/mcp`). For schema details use the versioned
595595
schemas (JSON and TypeScript) in
596596
[modelcontextprotocol/schema](https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/schema).
597+
- **Protocol eras**: every TypeScript server serves both 2026-07-28 clients
598+
and 2025-era clients from one factory: stdio through the SDK's
599+
`serveStdio`, Streamable HTTP through `createMcpHandler`. Keep no state in
600+
a map keyed by session id, since 2026-07-28 has no sessions: per-connection
601+
state lives on the server instance, and state that must outlive a
602+
2026-07-28 request lives under a handle the server mints. Ask a client for
603+
input (elicitation, sampling, roots) by returning `inputRequired(...)`,
604+
which the SDK's legacy shim also serves to 2025-era clients.
597605
- **Transports**: stdio is the default and every server supports it.
598606
`everything` also serves Streamable HTTP and HTTP+SSE. **HTTP+SSE is
599607
deprecated**: keep what exists working, and never make it the default or the

‎src/everything/AGENTS.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,9 @@ The server factory is `src/everything/server/index.ts` and registers all feature
2929

3030
### High-level
3131

32-
- Tools live under `src/everything/tools/` and are registered via `registerTools(server)`.
33-
- Resources live under `src/everything/resources/` and are registered via `registerResources(server)`.
32+
- The server serves both protocol eras (2026-07-28 and 2025-era); the factory is `createServer({ era })`, and what each era gets is wired in `server/index.ts` and `tools/index.ts`.
33+
- Tools live under `src/everything/tools/` and are registered via `registerTools(server, context)` (both eras), `registerModernTools` (2026-07-28) or `registerLegacyTools` / `registerConditionalTools` (2025 era).
34+
- Resources live under `src/everything/resources/` and are registered via `registerResources(server, context)`.
3435
- Prompts live under `src/everything/prompts/` and are registered via `registerPrompts(server)`.
3536
- Subscriptions and simulated update routines are under `src/everything/resources/subscriptions.ts`.
3637
- Logging helpers are under `src/everything/server/logging.ts`.
@@ -39,7 +40,8 @@ The server factory is `src/everything/server/index.ts` and registers all feature
3940
### When adding a new feature
4041

4142
- Follow the existing file/module pattern in its folder (naming, exports, and registration function).
42-
- Export a `registerX(server)` function that registers new items with the MCP SDK in the same style as existing ones.
43+
- Export a `registerX(server)` function that registers new items with the MCP SDK in the same style as existing ones (taking the per-instance `context` too when it needs the era, the change publisher or per-connection state).
44+
- Keep no state in module-level maps keyed by session id; see [Extension Points](docs/extension.md).
4345
- Wire your new module into the central index (e.g., update `tools/index.ts`, `resources/index.ts`, or `prompts/index.ts`).
4446
- Ensure schemas (for tools) are accurate JSON Schema and include helpful descriptions and examples.
4547
- Keep the docs in `src/everything/docs/` up to date if you add or modify noteworthy features.

‎src/everything/README.md‎

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,14 @@ This MCP server attempts to exercise all the features of the MCP protocol. It is
1313

1414
A complete list of the registered MCP primitives and other protocol features demonstrated can be found in the [Server Features](docs/features.md) document.
1515

16-
The task tools (`simulate-research-query`, `trigger-sampling-request-async` and `trigger-elicitation-request-async`) are not available for now: they were built on the TypeScript SDK's experimental tasks layer, which SDK v2 removed. They return on the MCP tasks extension in [#4852](https://github.com/modelcontextprotocol/servers/issues/4852).
16+
## Protocol versions
17+
18+
The server serves both protocol eras, over stdio and Streamable HTTP, from one process:
19+
20+
- **2026-07-28** clients connect with `server/discover`, send their protocol version, identity and capabilities with each request, and have no session. The server demonstrates the revision's new features for them: multi-round-trip requests (`input_required`) with `requestState`, `subscriptions/listen` change notifications, per-request log levels, cache hints (`ttlMs` / `cacheScope`), the tasks extension (`io.modelcontextprotocol/tasks`) under the `extensions` capability, and `x-mcp-header` with JSON Schema 2020-12 tool schemas.
21+
- **2025-era** clients connect with the `initialize` handshake, as before. Elicitation, sampling and roots are served to them from the same multi-round-trip handlers through the SDK's legacy shim.
22+
23+
Roots, sampling and logging are deprecated as of 2026-07-28 and stay available, labelled deprecated. [Server Features](docs/features.md) marks which era each feature belongs to.
1724

1825
## Requirements
1926

@@ -91,22 +98,26 @@ On Windows, use:
9198
}
9299
```
93100

94-
## Running from source with [HTTP+SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) (deprecated as of [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports))
101+
## Run from source with [Streamable HTTP Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)
95102

96103
```shell
97104
cd src/everything
98105
npm install
99-
npm run start:sse
106+
npm run start:streamableHttp
100107
```
101108

102-
## Run from source with [Streamable HTTP Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)
109+
The endpoint is `http://localhost:3001/mcp` (`PORT` overrides the port). It serves 2026-07-28 clients statelessly and 2025-era clients with sessions, from the same URL.
110+
111+
## Running from source with [HTTP+SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) (deprecated as of [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports))
103112

104113
```shell
105114
cd src/everything
106115
npm install
107-
npm run start:streamableHttp
116+
npm run start:sse
108117
```
109118

119+
The HTTP+SSE transport serves 2025-era clients only, and the server prints a deprecation warning when it starts. Prefer Streamable HTTP.
120+
110121
## Running as an installed package
111122

112123
### Install
@@ -127,16 +138,16 @@ npx @modelcontextprotocol/server-everything
127138
npx @modelcontextprotocol/server-everything stdio
128139
```
129140

130-
### Run the SSE server
141+
### Run the streamable HTTP server
131142

132143
```shell
133-
npx @modelcontextprotocol/server-everything sse
144+
npx @modelcontextprotocol/server-everything streamableHttp
134145
```
135146

136-
### Run the streamable HTTP server
147+
### Run the SSE server (deprecated, 2025-era clients only)
137148

138149
```shell
139-
npx @modelcontextprotocol/server-everything streamableHttp
150+
npx @modelcontextprotocol/server-everything sse
140151
```
141152

142153
## License

‎src/everything/docs/architecture.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,18 +14,19 @@ It explains how the server starts, how transports are wired, where tools, prompt
1414

1515
### Purpose
1616

17-
A minimal, modular MCP server showcasing core Model Context Protocol features. It exposes simple tools, prompts, and resources, and can be run over multiple transports (STDIO, SSE, and Streamable HTTP).
17+
A minimal, modular MCP server showcasing core Model Context Protocol features. It exposes simple tools, prompts, and resources, and can be run over multiple transports (STDIO, Streamable HTTP, and the deprecated HTTP+SSE). It serves both protocol eras: 2026-07-28 clients (`server/discover`, per-request `_meta`, no sessions) and 2025-era clients (`initialize`), from one server factory.
1818

1919
### Design
2020

21-
A small “server factory” constructs the MCP server and registers features.
22-
Transports are separate entry points that create/connect the server and handle network concerns.
21+
A small “server factory” constructs the MCP server for a protocol era and registers features.
22+
Transports are separate entry points that serve the factory and handle network concerns: the SDK's `serveStdio` and `createMcpHandler` entries pick each client's era.
2323
Tools, prompts, and resources are organized in their own submodules.
2424

2525
### Multi‑client
2626

27-
The server supports multiple concurrent clients. Tracking per session data is demonstrated with
28-
resource subscriptions and simulated logging.
27+
The server supports multiple concurrent clients. Per-connection state (resource subscriptions,
28+
simulated logging) lives on the server instance serving the connection, and state that must outlive
29+
a 2026-07-28 request (tasks, minted resources) is stored under handles the server mints.
2930

3031
## Build and Distribution
3132

‎src/everything/docs/extension.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,10 @@
99

1010
## Adding Tools
1111

12-
- Create a new file under `tools/` with your `registerXTool(server)` function that registers the tool via `server.registerTool(...)`.
13-
- Export and call it from `tools/index.ts` inside `registerTools(server)`.
12+
- Create a new file under `tools/` with your `registerXTool(server)` function that registers the tool via `server.registerTool(...)`. Take the `context` (`server/context.ts`) as a second argument if the tool needs the protocol era, the change publisher, or state that lives as long as the connection.
13+
- Export and call it from `tools/index.ts`, in the function for the eras that get it: `registerTools(server, context)` for both, `registerModernTools` for 2026-07-28 only, `registerLegacyTools` or `registerConditionalTools` (capability-gated) for the 2025 era only.
14+
- Never keep state in a module-level map keyed by session id: the 2026-07-28 protocol has no sessions, and its HTTP path builds a fresh server per request. Keep per-connection state in the registration closure, and state that must outlive a request under a handle the server mints (as `server/tasks.ts` and `resources/minted.ts` do).
15+
- For client input (elicitation, sampling, roots), return `inputRequired(...)` from the handler rather than sending a request; the SDK's legacy shim serves the same handler to 2025-era clients.
1416

1517
## Adding Prompts
1618

@@ -20,4 +22,4 @@
2022
## Adding Resources
2123

2224
- Create a new file under `resources/` with your `registerXResources(server)` function using `server.registerResource(...)` (optionally with `ResourceTemplate`).
23-
- Export and call it from `resources/index.ts` inside `registerResources(server)`.
25+
- Export and call it from `resources/index.ts` inside `registerResources(server, context)`.

0 commit comments

Comments
 (0)