Rewrite docs/server.md as a code-heavy, prose-light how-to guide#1552
Draft
jonathanhefner wants to merge 4 commits intomodelcontextprotocol:mainfrom
Draft
Rewrite docs/server.md as a code-heavy, prose-light how-to guide#1552jonathanhefner wants to merge 4 commits intomodelcontextprotocol:mainfrom
docs/server.md as a code-heavy, prose-light how-to guide#1552jonathanhefner wants to merge 4 commits intomodelcontextprotocol:mainfrom
Conversation
|
@modelcontextprotocol/client
@modelcontextprotocol/server
@modelcontextprotocol/express
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
Restructure the document: action-oriented H1, Imports section, section-opener concept links to the MCP overview docs (not the specification), inline example-file references instead of `> [!NOTE]` callouts, and a trailing "See also" section with cross-links plus an "Additional examples" table. New sections: Imports, Disconnecting (`terminateSession()` + `close()`), Subscribing to resource changes (`subscribeResource`/`unsubscribeResource`), Roots (`roots/list` handler, `sendRootsListChanged()`), Error handling (tool errors vs protocol errors, connection lifecycle callbacks, timeouts), and `setLoggingLevel()` folded into Notifications. All new code examples are type-checked regions in `clientGuide.examples.ts` and synced via `pnpm sync:snippets`. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Expand the client guide with four new topics and their companion `.examples.ts` snippets: - Server instructions: retrieving `getInstructions()` and folding it into a system prompt - Pagination: `listTools()`, `listResources()`, and `listPrompts()` examples now loop on `nextCursor` to collect all pages - Structured tool output: `structuredContent` for machine-readable results alongside LLM-facing `content` - Progress tracking: `onprogress`, `resetTimeoutOnProgress`, and `maxTotalTimeout` options for long-running tool calls Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Repositions the server guide from a mixed how-to/reference/overview
document into a focused how-to guide that leads with type-checked code
snippets and delegates conceptual content to the MCP overview docs on
modelcontextprotocol.io.
Key changes to `docs/server.md`:
- Rename heading to "Building MCP servers" (task framing)
- Add snippet-synced imports block so readers know which packages to
import
- Cross-reference links now point to MCP overview/learn pages
(server-concepts, client-concepts, architecture) instead of the
specification, except for Logging and Tasks which have no dedicated
learn pages
- Replace `> [!NOTE]` callout blocks with inline example links
- Add decision guidance to Resources and Prompts sections ("use a
resource when the client needs to read data; use a tool when it needs
to do something")
- Add tool annotations snippet (`destructiveHint`, `idempotentHint`)
- Add error handling subsection under Tools showing the `isError: true`
pattern, with notes on auto-catch and output schema skip behavior
- Add shutdown section with SIGINT handling for both multi-session HTTP
(including `httpServer.close()`) and stdio servers
- Condense three Streamable HTTP variant subsections into one snippet
plus an Options paragraph
- Promote Tools, Resources, Prompts to top-level sections
- Replace "More server features" table with See Also list and Additional
Examples table
- Update `docs/documents.md` description to match
New example regions in `serverGuide.examples.ts`:
- `imports` — synced into the Imports section
- `registerTool_annotations` — tool with `destructiveHint`
- `registerTool_errorHandling` — try/catch with `isError: true`
- `shutdown_statefulHttp` — SIGINT + `httpServer.close()` + transport
cleanup
- `shutdown_stdio` — SIGINT + `server.close()`
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
`docs/server.md` Three gaps identified in the server how-to guide, each with a type-checked example in `serverGuide.examples.ts`: - **Server instructions** — `McpServer` constructor `instructions` option for cross-tool relationships, workflow patterns, and constraints. Placed between Transports and Tools. - **Progress** — sending `notifications/progress` via `ctx.mcpReq.notify()` during long-running tool execution, guarded by `progressToken`. Placed between Logging and Server-initiated requests. - **Roots** — calling `server.server.listRoots()` to discover the client's workspace directories. Placed under Server-initiated requests alongside Sampling and Elicitation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
jonathanhefner
force-pushed
the
server-how-to
branch
from
d4bc80b to
d4d8c64
Compare
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
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 #1551.
Repositions the server guide from a mixed how-to/reference/overview document into a focused how-to guide that leads with type-checked code snippets and delegates conceptual content to the MCP overview docs on modelcontextprotocol.io.
Key changes to
docs/server.md:> [!NOTE]callout blocks with inline example linksdestructiveHint,idempotentHint)isError: truepattern, with notes on auto-catch and output schema skip behaviorhttpServer.close()) and stdio serversdocs/documents.mddescription to matchNew example regions in
serverGuide.examples.ts:imports— synced into the Imports sectionregisterTool_annotations— tool withdestructiveHintregisterTool_errorHandling— try/catch withisError: trueshutdown_statefulHttp— SIGINT +httpServer.close()+ transport cleanupshutdown_stdio— SIGINT +server.close()