Rewrite docs/server.md as a code-heavy, prose-light how-to guide#1552
Draft
jonathanhefner wants to merge 6 commits intomodelcontextprotocol:mainfrom
Draft
Rewrite docs/server.md as a code-heavy, prose-light how-to guide#1552jonathanhefner wants to merge 6 commits intomodelcontextprotocol:mainfrom
docs/server.md as a code-heavy, prose-light how-to guide#1552jonathanhefner wants to merge 6 commits intomodelcontextprotocol:mainfrom
Conversation
Sampling and elicitation are now inline sections in `docs/server.md`
under a new "Server-initiated requests" heading, with type-checked code
snippets (`registerTool_sampling`, `registerTool_elicitation` regions in
`serverGuide.examples.ts`). This fixes the asymmetry where logging got
full inline treatment but structurally identical features (sampling,
elicitation) were exiled to table rows pointing at a separate file.
Tasks get subsections in both guides that name the entry-point APIs
(`registerToolTask`, `callToolStream`, `getTask`, `getTaskResult`) and
link to runnable examples, with progressive disclosure through JSDoc.
JSDoc enhancements for task APIs:
- `ToolTaskHandler`: three-phase description moved to field-level docs,
`@see` linking to `registerToolTask`
- `ResponseMessage`, `TaskStatusMessage`, `TaskCreatedMessage`,
`ResultMessage`, `ErrorMessage`: lifecycle semantics and terminal
behaviour documented; `{@linkcode}` cross-references to streaming APIs
- `takeResult`, `toArrayAsync`: added JSDoc
- `InMemoryTaskStore`: `{@inheritdoc TaskStore.*}` on all public methods
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move DNS rebinding protection and multi-node deployment patterns into a new `## Deployment` umbrella near the end — they were splitting the flow between Transports and core primitives. Promote Logging from a `####` under Tools to a `###` peer of Tools/Resources/Prompts, since `ctx.mcpReq.log()` is available in any handler, not just tools. Add a brief `#### Tool annotations` subsection under Tools (previously only in the catch-all table). Remove the Tool annotations row from the `More server features` table and drop the cross-link to client.md from the Completions section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Import and adapt the server quickstart tutorial from modelcontextprotocol.io and the companion `weather-server-typescript` example from `modelcontextprotocol/quickstart-resources` into this repo. `docs/server-quickstart.md` uses code fences with `source=` attributes so code snippets are type-checked and kept in in sync with the full runnable example in `examples/server-quickstart/`. Supporting changes: - `docs/documents.md`: list the new doc - `typedoc.config.mjs`: add `powershell` syntax highlighting - `.prettierignore`: exclude `examples/server-quickstart/` (2-space indent to match ecosystem conventions) - `scripts/sync-snippets.ts`: fix `dedent()` short-circuit on empty `baseIndent`; move `.trim()` so region extraction sees full file Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Import and adapt the client quickstart tutorial from modelcontextprotocol.io and the companion `mcp-client-typescript` example from `modelcontextprotocol/quickstart-resources` into this repo. `docs/client-quickstart.md` uses code fences with `source=` attributes so code snippets are type-checked and kept in in sync with the full runnable example in `examples/client-quickstart/`. Supporting changes: - `docs/documents.md`: list the new doc - `.prettierignore`: exclude `examples/client-quickstart/` (2-space indent to match ecosystem conventions) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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>
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>
|
@modelcontextprotocol/client
@modelcontextprotocol/server
@modelcontextprotocol/express
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
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()