Add API documentation with GitHub Pages deployment (#1109)
Co-authored-by: Konstantin Konstantinov <konstantin@mach5technology.com>
This commit is contained in:
Jonathan Hefner
GitHub
parent
9fc7e28f48
commit
25f288be1b
5 changed files with 11403 additions and 2391 deletions
|
|
@ -1,10 +1,14 @@
|
|||
---
|
||||
title: Capabilities
|
||||
---
|
||||
|
||||
## Sampling
|
||||
|
||||
MCP servers can request LLM completions from connected clients that support the sampling capability. This lets your tools offload summarisation or generation to the client’s model.
|
||||
|
||||
For a runnable server that combines tools, logging and tasks, see:
|
||||
|
||||
- [`toolWithSampleServer.ts`](../examples/server/src/toolWithSampleServer.ts)
|
||||
- [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/toolWithSampleServer.ts)
|
||||
|
||||
In practice you will:
|
||||
|
||||
|
|
@ -22,8 +26,8 @@ Form elicitation lets a tool ask the user for additional, **non‑sensitive** in
|
|||
|
||||
Runnable example:
|
||||
|
||||
- Server: [`elicitationFormExample.ts`](../examples/server/src/elicitationFormExample.ts)
|
||||
- Client‑side handling: [`simpleStreamableHttp.ts`](../examples/client/src/simpleStreamableHttp.ts)
|
||||
- Server: [`elicitationFormExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationFormExample.ts)
|
||||
- Client‑side handling: [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts)
|
||||
|
||||
The `simpleStreamableHttp` server also includes a `collect-user-info` tool that demonstrates how to drive elicitation from a tool and handle the response.
|
||||
|
||||
|
|
@ -33,8 +37,8 @@ URL elicitation is designed for sensitive data and secure web‑based flows (e.g
|
|||
|
||||
Runnable example:
|
||||
|
||||
- Server: [`elicitationUrlExample.ts`](../examples/server/src/elicitationUrlExample.ts)
|
||||
- Client: [`elicitationUrlExample.ts`](../examples/client/src/elicitationUrlExample.ts)
|
||||
- Server: [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationUrlExample.ts)
|
||||
- Client: [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/elicitationUrlExample.ts)
|
||||
|
||||
Key points:
|
||||
|
||||
|
|
@ -62,7 +66,7 @@ On the server you will:
|
|||
|
||||
For a runnable example that uses the in-memory store shipped with the SDK, see:
|
||||
|
||||
- [`toolWithSampleServer.ts`](../examples/server/src/toolWithSampleServer.ts)
|
||||
- [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/toolWithSampleServer.ts)
|
||||
- `packages/core/src/experimental/tasks/stores/in-memory.ts`
|
||||
|
||||
### Client-side usage
|
||||
|
|
@ -74,7 +78,7 @@ On the client, you use:
|
|||
|
||||
The interactive client in:
|
||||
|
||||
- [`simpleStreamableHttp.ts`](../examples/client/src/simpleStreamableHttp.ts)
|
||||
- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts)
|
||||
|
||||
includes commands to demonstrate calling tools that support tasks and handling their lifecycle.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
title: Client
|
||||
---
|
||||
|
||||
## Client overview
|
||||
|
||||
The SDK provides a high-level `Client` class that connects to MCP servers over different transports:
|
||||
|
|
@ -8,11 +12,11 @@ The SDK provides a high-level `Client` class that connects to MCP servers over d
|
|||
|
||||
Runnable client examples live under:
|
||||
|
||||
- [`simpleStreamableHttp.ts`](../examples/client/src/simpleStreamableHttp.ts)
|
||||
- [`streamableHttpWithSseFallbackClient.ts`](../examples/client/src/streamableHttpWithSseFallbackClient.ts)
|
||||
- [`ssePollingClient.ts`](../examples/client/src/ssePollingClient.ts)
|
||||
- [`multipleClientsParallel.ts`](../examples/client/src/multipleClientsParallel.ts)
|
||||
- [`parallelToolCallsClient.ts`](../examples/client/src/parallelToolCallsClient.ts)
|
||||
- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts)
|
||||
- [`streamableHttpWithSseFallbackClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/streamableHttpWithSseFallbackClient.ts)
|
||||
- [`ssePollingClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/ssePollingClient.ts)
|
||||
- [`multipleClientsParallel.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/multipleClientsParallel.ts)
|
||||
- [`parallelToolCallsClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/parallelToolCallsClient.ts)
|
||||
|
||||
## Connecting and basic operations
|
||||
|
||||
|
|
@ -25,7 +29,7 @@ A typical flow:
|
|||
- `listPrompts`, `getPrompt`
|
||||
- `listResources`, `readResource`
|
||||
|
||||
See [`simpleStreamableHttp.ts`](../examples/client/src/simpleStreamableHttp.ts) for an interactive CLI client that exercises these methods and shows how to handle notifications, elicitation and tasks.
|
||||
See [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts) for an interactive CLI client that exercises these methods and shows how to handle notifications, elicitation and tasks.
|
||||
|
||||
## Transports and backwards compatibility
|
||||
|
||||
|
|
@ -36,7 +40,7 @@ To support both modern Streamable HTTP and legacy SSE servers, use a client that
|
|||
|
||||
Runnable example:
|
||||
|
||||
- [`streamableHttpWithSseFallbackClient.ts`](../examples/client/src/streamableHttpWithSseFallbackClient.ts)
|
||||
- [`streamableHttpWithSseFallbackClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/streamableHttpWithSseFallbackClient.ts)
|
||||
|
||||
## OAuth client authentication helpers
|
||||
|
||||
|
|
@ -48,10 +52,10 @@ For OAuth-secured MCP servers, the client `auth` module exposes:
|
|||
|
||||
Examples:
|
||||
|
||||
- [`simpleOAuthClient.ts`](../examples/client/src/simpleOAuthClient.ts)
|
||||
- [`simpleOAuthClientProvider.ts`](../examples/client/src/simpleOAuthClientProvider.ts)
|
||||
- [`simpleClientCredentials.ts`](../examples/client/src/simpleClientCredentials.ts)
|
||||
- Server-side auth demo: [`demoInMemoryOAuthProvider.ts`](../examples/shared/src/demoInMemoryOAuthProvider.ts) (tests live under `examples/shared/test/demoInMemoryOAuthProvider.test.ts`)
|
||||
- [`simpleOAuthClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleOAuthClient.ts)
|
||||
- [`simpleOAuthClientProvider.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleOAuthClientProvider.ts)
|
||||
- [`simpleClientCredentials.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleClientCredentials.ts)
|
||||
- Server-side auth demo: [`demoInMemoryOAuthProvider.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/shared/src/demoInMemoryOAuthProvider.ts) (tests live under `examples/shared/test/demoInMemoryOAuthProvider.test.ts`)
|
||||
|
||||
These examples show how to:
|
||||
|
||||
|
|
|
|||
15
docs/documents.md
Normal file
15
docs/documents.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
title: Documents
|
||||
children:
|
||||
- ./server.md
|
||||
- ./client.md
|
||||
- ./capabilities.md
|
||||
- ./faq.md
|
||||
---
|
||||
|
||||
# Documents
|
||||
|
||||
- [Server](./server.md) – building MCP servers, transports, tools/resources/prompts, and deployment patterns
|
||||
- [Client](./client.md) – using the high-level client, transports, backwards compatibility, and OAuth helpers
|
||||
- [Capabilities](./capabilities.md) – sampling, elicitation, and experimental task-based execution
|
||||
- [FAQ](./faq.md) – frequently asked questions and troubleshooting
|
||||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
title: FAQ
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
<details>
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
title: Server
|
||||
---
|
||||
|
||||
## Server overview
|
||||
|
||||
This SDK lets you build MCP servers in TypeScript and connect them to different transports. For most use cases you will use `McpServer` from `@modelcontextprotocol/server` and choose one of:
|
||||
|
|
@ -8,11 +12,11 @@ This SDK lets you build MCP servers in TypeScript and connect them to different
|
|||
|
||||
For a complete, runnable example server, see:
|
||||
|
||||
- [`simpleStreamableHttp.ts`](../examples/server/src/simpleStreamableHttp.ts) – feature‑rich Streamable HTTP server
|
||||
- [`jsonResponseStreamableHttp.ts`](../examples/server/src/jsonResponseStreamableHttp.ts) – Streamable HTTP with JSON response mode
|
||||
- [`simpleStatelessStreamableHttp.ts`](../examples/server/src/simpleStatelessStreamableHttp.ts) – stateless Streamable HTTP server
|
||||
- [`simpleSseServer.ts`](../examples/server/src/simpleSseServer.ts) – deprecated HTTP+SSE transport
|
||||
- [`sseAndStreamableHttpCompatibleServer.ts`](../examples/server/src/sseAndStreamableHttpCompatibleServer.ts) – backwards‑compatible server for old and new clients
|
||||
- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts) – feature‑rich Streamable HTTP server
|
||||
- [`jsonResponseStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/jsonResponseStreamableHttp.ts) – Streamable HTTP with JSON response mode
|
||||
- [`simpleStatelessStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStatelessStreamableHttp.ts) – stateless Streamable HTTP server
|
||||
- [`simpleSseServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleSseServer.ts) – deprecated HTTP+SSE transport
|
||||
- [`sseAndStreamableHttpCompatibleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/sseAndStreamableHttpCompatibleServer.ts) – backwards‑compatible server for old and new clients
|
||||
|
||||
## Transports
|
||||
|
||||
|
|
@ -27,9 +31,9 @@ Streamable HTTP is the modern, fully featured transport. It supports:
|
|||
|
||||
Key examples:
|
||||
|
||||
- [`simpleStreamableHttp.ts`](../examples/server/src/simpleStreamableHttp.ts) – sessions, logging, tasks, elicitation, auth hooks
|
||||
- [`jsonResponseStreamableHttp.ts`](../examples/server/src/jsonResponseStreamableHttp.ts) – `enableJsonResponse: true`, no SSE
|
||||
- [`standaloneSseWithGetStreamableHttp.ts`](../examples/server/src/standaloneSseWithGetStreamableHttp.ts) – notifications with Streamable HTTP GET + SSE
|
||||
- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts) – sessions, logging, tasks, elicitation, auth hooks
|
||||
- [`jsonResponseStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/jsonResponseStreamableHttp.ts) – `enableJsonResponse: true`, no SSE
|
||||
- [`standaloneSseWithGetStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/standaloneSseWithGetStreamableHttp.ts) – notifications with Streamable HTTP GET + SSE
|
||||
|
||||
See the MCP spec for full transport details: `https://modelcontextprotocol.io/specification/2025-11-25/basic/transports`
|
||||
|
||||
|
|
@ -42,8 +46,8 @@ Streamable HTTP can run:
|
|||
|
||||
Examples:
|
||||
|
||||
- Stateless Streamable HTTP: [`simpleStatelessStreamableHttp.ts`](../examples/server/src/simpleStatelessStreamableHttp.ts)
|
||||
- Stateful with resumability: [`simpleStreamableHttp.ts`](../examples/server/src/simpleStreamableHttp.ts)
|
||||
- Stateless Streamable HTTP: [`simpleStatelessStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStatelessStreamableHttp.ts)
|
||||
- Stateful with resumability: [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)
|
||||
|
||||
### Deprecated HTTP + SSE
|
||||
|
||||
|
|
@ -51,15 +55,15 @@ The older HTTP+SSE transport (protocol version 2024‑11‑05) is supported only
|
|||
|
||||
Examples:
|
||||
|
||||
- Legacy SSE server: [`simpleSseServer.ts`](../examples/server/src/simpleSseServer.ts)
|
||||
- Legacy SSE server: [`simpleSseServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleSseServer.ts)
|
||||
- Backwards‑compatible server (Streamable HTTP + SSE):
|
||||
[`sseAndStreamableHttpCompatibleServer.ts`](../examples/server/src/sseAndStreamableHttpCompatibleServer.ts)
|
||||
[`sseAndStreamableHttpCompatibleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/sseAndStreamableHttpCompatibleServer.ts)
|
||||
|
||||
## Running your server
|
||||
|
||||
For a minimal “getting started” experience:
|
||||
|
||||
1. Start from [`simpleStreamableHttp.ts`](../examples/server/src/simpleStreamableHttp.ts).
|
||||
1. Start from [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts).
|
||||
2. Remove features you do not need (tasks, advanced logging, OAuth, etc.).
|
||||
3. Register your own tools, resources and prompts.
|
||||
|
||||
|
|
@ -125,8 +129,8 @@ server.registerTool(
|
|||
|
||||
This snippet is illustrative only; for runnable servers that expose tools, see:
|
||||
|
||||
- [`simpleStreamableHttp.ts`](../examples/server/src/simpleStreamableHttp.ts)
|
||||
- [`toolWithSampleServer.ts`](../examples/server/src/toolWithSampleServer.ts)
|
||||
- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)
|
||||
- [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/toolWithSampleServer.ts)
|
||||
|
||||
#### ResourceLink outputs
|
||||
|
||||
|
|
@ -157,7 +161,7 @@ server.registerResource(
|
|||
|
||||
Dynamic resources use `ResourceTemplate` and can support completions on path parameters. For full runnable examples of resources:
|
||||
|
||||
- [`simpleStreamableHttp.ts`](../examples/server/src/simpleStreamableHttp.ts)
|
||||
- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)
|
||||
|
||||
### Prompts
|
||||
|
||||
|
|
@ -189,13 +193,13 @@ server.registerPrompt(
|
|||
|
||||
For prompts integrated into a full server, see:
|
||||
|
||||
- [`simpleStreamableHttp.ts`](../examples/server/src/simpleStreamableHttp.ts)
|
||||
- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)
|
||||
|
||||
### Completions
|
||||
|
||||
Both prompts and resources can support argument completions. On the client side, you use `client.complete()` with a reference to the prompt or resource and the partially‑typed argument.
|
||||
|
||||
See the MCP spec sections on prompts and resources for complete details, and [`simpleStreamableHttp.ts`](../examples/client/src/simpleStreamableHttp.ts) for client‑side usage patterns.
|
||||
See the MCP spec sections on prompts and resources for complete details, and [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts) for client‑side usage patterns.
|
||||
|
||||
### Display names and metadata
|
||||
|
||||
|
|
@ -207,15 +211,15 @@ Tools, resources and prompts support a `title` field for human‑readable names.
|
|||
|
||||
The SDK supports multi‑node deployments using Streamable HTTP. The high‑level patterns and diagrams live with the runnable server examples:
|
||||
|
||||
- [`examples/server/README.md`](../examples/server/README.md#multi-node-deployment-patterns)
|
||||
- [`examples/server/README.md`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md#multi-node-deployment-patterns)
|
||||
|
||||
## Backwards compatibility
|
||||
|
||||
To handle both modern and legacy clients:
|
||||
|
||||
- Run a backwards‑compatible server:
|
||||
- [`sseAndStreamableHttpCompatibleServer.ts`](../examples/server/src/sseAndStreamableHttpCompatibleServer.ts)
|
||||
- [`sseAndStreamableHttpCompatibleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/sseAndStreamableHttpCompatibleServer.ts)
|
||||
- Use a client that falls back from Streamable HTTP to SSE:
|
||||
- [`streamableHttpWithSseFallbackClient.ts`](../examples/client/src/streamableHttpWithSseFallbackClient.ts)
|
||||
- [`streamableHttpWithSseFallbackClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/streamableHttpWithSseFallbackClient.ts)
|
||||
|
||||
For the detailed protocol rules, see the “Backwards compatibility” section of the MCP spec.
|
||||
|
|
|
|||
Loading…
Reference in a new issue