Overhaul docs/server.md to be a more complete, self-contained server guide#1525
Merged
jonathanhefner merged 7 commits intomodelcontextprotocol:mainfrom Feb 13, 2026
Merged
Conversation
|
@modelcontextprotocol/client
@modelcontextprotocol/server
@modelcontextprotocol/express
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
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) <noreply@anthropic.com>
`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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
jonathanhefner
force-pushed
the
revise-docs-server-md
branch
from
6c9dbfe to
fd01ec3
Compare
felixweinberger
approved these changes
Feb 13, 2026
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
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.