Overhaul docs/server.md to be a more complete, self-contained server guide
#1525
+1,891
−252
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
JSDoc `@example` code blocks were previously inlined and not type-checked, meaning they could silently drift from the actual API. This adds a `scripts/sync-snippets.ts` script (`pnpm sync:snippets`) that extracts code from co-located `.examples.ts` files — using `//#region` markers — and syncs them into JSDoc `@example` fences and markdown files. The script supports a `--check` mode (wired into `lint:all`) to catch drift in CI. Code fences use a `source="./file.examples.ts#regionName"` attribute to reference their source of truth. Includes `.examples.ts` companion files for: - `packages/core`: `SdkError`, validation providers (`AjvJsonSchemaValidator`, `CfWorkerJsonSchemaValidator`, `jsonSchemaValidator`), and module-level validator examples - `packages/client`: `Client` options, `fetchToken`, auth extensions (`createPrivateKeyJwtAuth`, `ClientCredentialsProvider`, `PrivateKeyJwtProvider`), client middleware (`applyMiddlewares`, `createMiddleware`), and experimental task streaming - `packages/server`: `hostHeaderValidation` response helper - `packages/middleware/express`: `createMcpExpressApp` and host header validation middleware Also removes the duplicate `@example` from `Protocol.requestStream()` (now covered by `ExperimentalClientTasks.requestStream()`), adds ESLint overrides for `.examples.ts` files (`no-unused-vars`, `no-console`), and updates `CLAUDE.md` with snippet conventions. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Use the `sync-snippets` mechanism to inject type-checked code from `serverGuide.examples.ts` into `docs/server.md`. 10 snippet regions covering transports, tools, resources, prompts, `completable()`, `ResourceLink`, `ResourceTemplate`, and DNS rebinding. Fixes three bugs in existing illustrative snippets where `inputSchema`, `outputSchema`, and `argsSchema` used raw objects instead of `z.object()`. Removes four broken links to `simpleSseServer.ts` and `sseAndStreamableHttpCompatibleServer.ts` (deleted in v2 when `SSEServerTransport` was removed). Updates the deprecated SSE section to reflect this. Adds `> [!NOTE]` callouts linking to full runnable examples alongside each inline snippet. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
`docs/server.md` The SSE-only server transport was removed from the SDK, but the server guide still had subtle language implying it existed as an alternative: - "recommended for remote servers" → "for remote servers" (it is the only remote transport, not merely recommended) - "modern, fully featured transport" → "HTTP‑based transport" (no older alternative to contrast against) - Removed the "Deprecated HTTP + SSE" section entirely — this is a client‑side concern already covered in `docs/client.md` - Removed the "Backwards compatibility" section — also a client‑side concern already covered in `docs/client.md` Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
The Completions section included a paragraph about `client.complete()` and a link to a client example — replaced with a brief cross-reference to the Client guide. The "Display names and metadata" subsection only described the client-side `getDisplayName` helper; every inline example already demonstrates the `title` field, so the section was redundant for server authors. Dropped it entirely. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Replace plain backtick code references with TypeDoc `{@linkcode}` links
for `McpServer`, `McpServer#registerTool`, `ResourceTemplate`, and
`completable()`. Also add backtick formatting to the `ResourceLink`
heading. These link to the `@modelcontextprotocol/server` package using
fully-qualified module paths required by TypeDoc's
`entryPointStrategy: "packages"` mode.
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Expand `docs/server.md` with three new inline sections:
- `#### JSON response mode` — `enableJsonResponse: true` transport
option
- `### stdio` — `StdioServerTransport` pattern with `{@linkcode}`
- `#### Logging` — `ctx.mcpReq.log()` in tool handlers, with `logging`
capability snippet
Add a "More server features" table at the end of `docs/server.md`
linking eight additional capabilities (elicitation, sampling, tool
annotations, Web Standard transport, session management, resumability,
CORS, tasks) to runnable examples and `docs/capabilities.md`.
Demote "Stateless vs stateful sessions" and "JSON response mode" from
`h3` to `h4` so they nest under the `### Streamable HTTP` parent.
Add three new synced regions to `serverGuide.examples.ts`:
`logging_capability`, `registerTool_logging`,
`streamableHttp_jsonResponse`, `stdio_basic`.
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
The `Running your server` section sat awkwardly between Transports and DNS rebinding protection, containing no code and significant overlap with the overview (duplicate `simpleStreamableHttp.ts` link, duplicate Transports spec link, a 3-step list that recapped what the Transports section already showed in code). Rework the overview into a concise roadmap: - Replace the bullet-list of transport choices and example links with a 3-step numbered list that names `McpServer`, links to both transport sections, and forward-links to tools/resources/prompts - Fold the "start from `simpleStreamableHttp.ts` and strip what you don't need" advice into the overview's closing paragraph - Tease stateless and JSON-response-mode variants with a sentence pointing to Transports, rather than duplicating the example links - Add section-specific spec links to NOTE callouts (Tools, Resources, Prompts) following the established pattern - Fix the Streamable HTTP spec link to use the standard NOTE callout format instead of a bare URL in body text Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
|
@modelcontextprotocol/client
@modelcontextprotocol/server
@modelcontextprotocol/express
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
ℹ️ This is based on top of #1487
examples/server/src/serverGuide.examples.tsfile via the snippet sync system, so every example in the guide is compiled and stays in sync with the SDK.{@linkcode}cross-references: Key types and methods (McpServer,registerTool,ResourceTemplate,StdioServerTransport,completable,ServerContext) now link to API docs.ResourceLinktool outputs, server-side logging (ctx.mcpReq.log), dynamic resources withResourceTemplate, completable prompt arguments, JSON response mode, and stdio transport — all with type-checked examples.I still want to improve this document more in the future, but I think this is in a mergeable state.