Skip to content

Commit e9a6a34

Browse files
jonathanhefnerclaude
jonathanhefner
and
claude
committed
Dissolve capabilities.md into server.md and client.md
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>
1 parent dc896e1 commit e9a6a34

9 files changed

Lines changed: 276 additions & 107 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -127,9 +127,8 @@ Next steps:
127127
## Documentation
128128

129129
- Local SDK docs:
130-
- [docs/server.md](docs/server.md) – building MCP servers, transports, tools/resources/prompts, CORS, DNS rebinding, and deployment patterns.
131-
- [docs/client.md](docs/client.md) – using the high-level client, transports, backwards compatibility, and OAuth helpers.
132-
- [docs/capabilities.md](docs/capabilities.md) – sampling, elicitation (form and URL), and experimental task-based execution.
130+
- [docs/server.md](docs/server.md) – building MCP servers, transports, tools/resources/prompts, sampling, elicitation, tasks, and deployment patterns.
131+
- [docs/client.md](docs/client.md) – using the high-level client, transports, OAuth helpers, handling server‑initiated requests, and tasks.
133132
- [docs/faq.md](docs/faq.md) – environment and troubleshooting FAQs (including Node.js Web Crypto support).
134133
- External references:
135134
- [SDK API documentation](https://modelcontextprotocol.github.io/typescript-sdk/)

‎docs/capabilities.md‎

Lines changed: 0 additions & 85 deletions
This file was deleted.

‎docs/client.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Client
33
---
44

5-
## Client overview
5+
# Client overview
66

77
This guide covers SDK usage for building MCP clients in TypeScript. For protocol-level details and message formats, see the [MCP specification](https://modelcontextprotocol.io/specification/latest/).
88

@@ -318,7 +318,7 @@ client.setRequestHandler('elicitation/create', async request => {
318318
```
319319

320320
> [!NOTE]
321-
> For a full form‑based elicitation handler with AJV validation, see [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts). For URL elicitation mode, see [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/elicitationUrlExample.ts) and the [Capabilities guide](capabilities.md#elicitation).
321+
> For a full form‑based elicitation handler with AJV validation, see [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts). For URL elicitation mode (`mode: 'url'`), see [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/elicitationUrlExample.ts).
322322
>
323323
> For protocol details, see [Elicitation](https://modelcontextprotocol.io/specification/latest/client/elicitation) in the MCP specification.
324324
@@ -367,6 +367,19 @@ console.log(result);
367367
> [!NOTE]
368368
> For an end‑to‑end example of server‑initiated SSE disconnection and automatic client reconnection with event replay, see [`ssePollingClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/ssePollingClient.ts).
369369
370+
## Tasks (experimental)
371+
372+
Task-based execution enables "call-now, fetch-later" patterns for long-running operations. Instead of returning a result immediately, a tool creates a task that can be polled or resumed later. To use tasks:
373+
374+
- Call {@linkcode @modelcontextprotocol/client!experimental/tasks/client.ExperimentalClientTasks#callToolStream | client.experimental.tasks.callToolStream(...)} to start a tool call that may create a task and emit status updates over time.
375+
- Call {@linkcode @modelcontextprotocol/client!experimental/tasks/client.ExperimentalClientTasks#getTask | client.experimental.tasks.getTask(...)} and {@linkcode @modelcontextprotocol/client!experimental/tasks/client.ExperimentalClientTasks#getTaskResult | getTaskResult(...)} to check status and fetch results after reconnecting.
376+
377+
> [!NOTE]
378+
> For a full runnable example, see [`simpleTaskInteractiveClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleTaskInteractiveClient.ts).
379+
380+
> [!WARNING]
381+
> The tasks API is experimental and may change without notice.
382+
370383
## More client features
371384

372385
The sections above cover the essentials. The table below links to additional capabilities.
@@ -377,4 +390,3 @@ The sections above cover the essentials. The table below links to additional cap
377390
| SSE disconnect / reconnection | Server‑initiated SSE disconnect with automatic reconnection and event replay | [`ssePollingClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/ssePollingClient.ts) |
378391
| Multiple clients | Independent client lifecycles to the same server | [`multipleClientsParallel.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/multipleClientsParallel.ts) |
379392
| URL elicitation | Handle sensitive data collection via browser | [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/elicitationUrlExample.ts) |
380-
| Tasks (experimental) | Long‑running tool calls with status streaming | [`simpleTaskInteractiveClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleTaskInteractiveClient.ts), [Capabilities guide](capabilities.md#task-based-execution-experimental) |

‎docs/documents.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,11 @@ title: Documents
33
children:
44
- ./server.md
55
- ./client.md
6-
- ./capabilities.md
76
- ./faq.md
87
---
98

109
# Documents
1110

12-
- [Server](./server.md) – building MCP servers, transports, tools/resources/prompts, and deployment patterns
13-
- [Client](./client.md) – using the high-level client, transports, backwards compatibility, and OAuth helpers
14-
- [Capabilities](./capabilities.md) – sampling, elicitation, and experimental task-based execution
11+
- [Server](./server.md) – building MCP servers, transports, tools/resources/prompts, sampling, elicitation, tasks, and deployment patterns
12+
- [Client](./client.md) – using the high-level client, transports, OAuth helpers, handling server‑initiated requests, and tasks
1513
- [FAQ](./faq.md) – frequently asked questions and troubleshooting

‎docs/server.md‎

Lines changed: 116 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Server
33
---
44

5-
## Server overview
5+
# Server overview
66

77
This guide covers SDK usage for building MCP servers in TypeScript. For protocol-level details and message formats, see the [MCP specification](https://modelcontextprotocol.io/specification/latest/).
88

@@ -339,9 +339,123 @@ server.registerPrompt(
339339

340340
For client-side completion usage, see the [Client guide](client.md).
341341

342+
## Server‑initiated requests
343+
344+
MCP is bidirectional — servers can also send requests *to* the client during tool execution, as long as the client declares matching capabilities.
345+
346+
### Sampling
347+
348+
Use `ctx.mcpReq.requestSampling(params)` (from {@linkcode @modelcontextprotocol/server!index.ServerContext | ServerContext}) inside a tool handler to request an LLM completion from the connected client:
349+
350+
```ts source="../examples/server/src/serverGuide.examples.ts#registerTool_sampling"
351+
server.registerTool(
352+
'summarize',
353+
{
354+
description: 'Summarize text using the client LLM',
355+
inputSchema: z.object({ text: z.string() })
356+
},
357+
async ({ text }, ctx): Promise<CallToolResult> => {
358+
const response = await ctx.mcpReq.requestSampling({
359+
messages: [
360+
{
361+
role: 'user',
362+
content: {
363+
type: 'text',
364+
text: `Please summarize:\n\n${text}`
365+
}
366+
}
367+
],
368+
maxTokens: 500
369+
});
370+
return {
371+
content: [
372+
{
373+
type: 'text',
374+
text: `Model (${response.model}): ${JSON.stringify(response.content)}`
375+
}
376+
]
377+
};
378+
}
379+
);
380+
```
381+
382+
> [!NOTE]
383+
> For a full runnable example, see [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/toolWithSampleServer.ts).
384+
>
385+
> For protocol details, see [Sampling](https://modelcontextprotocol.io/specification/latest/client/sampling) in the MCP specification.
386+
387+
### Elicitation
388+
389+
Use `ctx.mcpReq.elicitInput(params)` (from {@linkcode @modelcontextprotocol/server!index.ServerContext | ServerContext}) inside a tool handler to request user input. Elicitation supports two modes:
390+
391+
- **Form** (`mode: 'form'`) — collects **non‑sensitive** data via a schema‑driven form.
392+
- **URL** (`mode: 'url'`) — for sensitive data or secure web‑based flows (API keys, payments, OAuth). The client opens a URL in the browser.
393+
394+
> [!IMPORTANT]
395+
> Sensitive information **must not** be collected via form elicitation; always use URL elicitation or out‑of‑band flows for secrets.
396+
397+
```ts source="../examples/server/src/serverGuide.examples.ts#registerTool_elicitation"
398+
server.registerTool(
399+
'collect-feedback',
400+
{
401+
description: 'Collect user feedback via a form',
402+
inputSchema: z.object({})
403+
},
404+
async (_args, ctx): Promise<CallToolResult> => {
405+
const result = await ctx.mcpReq.elicitInput({
406+
mode: 'form',
407+
message: 'Please share your feedback:',
408+
requestedSchema: {
409+
type: 'object',
410+
properties: {
411+
rating: {
412+
type: 'number',
413+
title: 'Rating (1\u20135)',
414+
minimum: 1,
415+
maximum: 5
416+
},
417+
comment: { type: 'string', title: 'Comment' }
418+
},
419+
required: ['rating']
420+
}
421+
});
422+
if (result.action === 'accept') {
423+
return {
424+
content: [
425+
{
426+
type: 'text',
427+
text: `Thanks! ${JSON.stringify(result.content)}`
428+
}
429+
]
430+
};
431+
}
432+
return { content: [{ type: 'text', text: 'Feedback declined.' }] };
433+
}
434+
);
435+
```
436+
437+
> [!NOTE]
438+
> For runnable examples, see [`elicitationFormExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationFormExample.ts) (form mode) and [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationUrlExample.ts) (URL mode).
439+
>
440+
> For protocol details, see [Elicitation](https://modelcontextprotocol.io/specification/latest/client/elicitation) in the MCP specification.
441+
442+
## Tasks (experimental)
443+
444+
Task-based execution enables "call-now, fetch-later" patterns for long-running operations. Instead of returning a result immediately, a tool creates a task that can be polled or resumed later. To use tasks:
445+
446+
- Provide a {@linkcode @modelcontextprotocol/server!index.TaskStore | TaskStore} implementation that persists task metadata and results (see {@linkcode @modelcontextprotocol/server!index.InMemoryTaskStore | InMemoryTaskStore} for reference).
447+
- Enable the `tasks` capability when constructing the server.
448+
- Register tools with {@linkcode @modelcontextprotocol/server!experimental/tasks/mcpServer.ExperimentalMcpServerTasks#registerToolTask | server.experimental.tasks.registerToolTask(...)}.
449+
450+
> [!NOTE]
451+
> For a full runnable example, see [`simpleTaskInteractive.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleTaskInteractive.ts).
452+
453+
> [!WARNING]
454+
> The tasks API is experimental and may change without notice.
455+
342456
## More server features
343457

344-
The sections above cover the essentials. The SDK supports several additional capabilities — each is demonstrated in the runnable examples and covered in more detail in the linked references.
458+
The sections above cover the essentials. The table below links to additional capabilities demonstrated in the runnable examples.
345459

346460
| Feature | Description | Reference |
347461
|---------|-------------|-----------|
@@ -350,7 +464,4 @@ The sections above cover the essentials. The SDK supports several additional cap
350464
| Resumability | Replay missed SSE events via an event store | [`inMemoryEventStore.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/inMemoryEventStore.ts) |
351465
| CORS | Expose MCP headers (`mcp-session-id`, etc.) for browser clients | [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts) |
352466
| Tool annotations | Hint whether tools are read-only, destructive, etc. | [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts) |
353-
| Elicitation | Request user input (forms or URLs) during tool execution | [Capabilities guide](capabilities.md#elicitation), [`elicitationFormExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationFormExample.ts) |
354-
| Sampling | Request LLM completions from the connected client | [Capabilities guide](capabilities.md#sampling), [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/toolWithSampleServer.ts) |
355-
| Tasks (experimental) | Long-running operations with polling and resumption | [Capabilities guide](capabilities.md#task-based-execution-experimental), [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts) |
356467
| Multi‑node deployment | Stateless, persistent‑storage, and distributed routing patterns | [`examples/server/README.md`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md#multi-node-deployment-patterns) |

0 commit comments

Comments
 (0)