Update README.md and docs/faq.md to link full quickstart guides#1554
Draft
jonathanhefner wants to merge 5 commits intomodelcontextprotocol:mainfrom
Draft
Update README.md and docs/faq.md to link full quickstart guides#1554jonathanhefner wants to merge 5 commits intomodelcontextprotocol:mainfrom
README.md and docs/faq.md to link full quickstart guides#1554jonathanhefner wants to merge 5 commits intomodelcontextprotocol:mainfrom
Conversation
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>
|
@modelcontextprotocol/client
@modelcontextprotocol/server
@modelcontextprotocol/express
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
jonathanhefner
force-pushed
the
rework-readme-quickstart
branch
from
21713f3 to
5e9cc77
Compare
Now that the server and client quickstart tutorials have been imported, update the README and FAQ to funnel newcomers to them. The README "Quick Start" section is replaced with a "Getting Started" section that shows an inline code snippet, links the two quickstart tutorials, and demotes the advanced examples to a secondary mention. The "Documentation" section is flattened into a single list with updated URLs. The FAQ answer for "Where can I find runnable server examples?" now points to `server-quickstart.md` first. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
jonathanhefner
force-pushed
the
rework-readme-quickstart
branch
from
5e9cc77 to
c39f498
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 #1552.
Now that the server and client quickstart tutorials have been imported, update the README and FAQ to funnel newcomers to them. The README "Quick Start" section is replaced with a "Getting Started" section that shows an inline code snippet, links the two quickstart tutorials, and demotes the advanced examples to a secondary mention. The "Documentation" section is flattened into a single list with updated URLs. The FAQ answer for "Where can I find runnable server examples?" now points to
server-quickstart.mdfirst.