You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add API documentation with GitHub Pages deployment
This adds automated generation and deployment of versioned API
documentation using TypeDoc and GitHub Pages. Documentation will be
generated and published when a new release is created.
**Changes:**
1. **Documentation generation script (see
`scripts/generate-gh-pages.sh`)**
Generates TypeDoc documentation for a specific version tag and
commits it to the `gh-pages` branch. The script uses git worktrees to
isolate the documentation generation process from the main workspace.
Documentation for each release is stored in a versioned directory
(e.g., `v1.2.3/`) on the gh-pages branch. The script:
- Parses semantic versions from tag names, ignoring arbitrary
prefixes (e.g., tags `1.2.3`, `v1.2.3`, and `release-1.2.3` all
create `v1.2.3/`)
- Creates the `gh-pages` branch as an orphan branch if it doesn't
exist
- Generates new doc pages while preserving existing versioned
directories
- Determines the latest version via semantic version sorting
- Generates `_data/latest_version.yml` for Jekyll template
- For the latest version only, copies static Jekyll template files
from `.github/pages/` to the `gh-pages` root
2. TypeDoc configuration
- `typedoc.config.mjs` - Root config using `packages` entry point
strategy to document the monorepo (`@modelcontextprotocol/client`
and `@modelcontextprotocol/server` packages)
- `packages/client/typedoc.json` - Per-package config for client
- `packages/server/typedoc.json` - Per-package config for server
- Includes `docs/documents.md` as project documentation, which, in
turn, pulls in other documents via its frontmatter
3. Jekyll template files (see `.github/pages/` directory)
- `.github/pages/_config.yml` - Jekyll configuration
- `.github/pages/index.html` - Landing page that redirects to the
latest version based on the generated `_data/latest_version.yml`
4. GitHub Actions workflow (see `.github/workflows/main.yml`)
Added a `publish-gh-pages` job that runs after the `publish` job on
release events. This ensures documentation is generated and published
only after the npm package is successfully published. The job invokes
the generation script with the release tag name and pushes the
updated gh-pages branch.
5. CI validation (see `packages/*/package.json`)
Updated the `check` script in each package to include TypeDoc
validation with `--emit none`. This ensures TypeDoc can successfully
parse the codebase (without generating output), catching
documentation issues early in CI.
6. Documentation updates
- Updated `docs/*.md` files with absolute GitHub URLs for
compatibility with generated documentation
- Added link to published API docs in `README.md`
**Documentation URL:**
- https://modelcontextprotocol.github.io/typescript-sdk/ (redirects to
latest)
- https://modelcontextprotocol.github.io/typescript-sdk/v1.2.3/
(specific versions)
Copy file name to clipboardExpand all lines: docs/capabilities.md
+11-7Lines changed: 11 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,14 @@
1
+
---
2
+
title: Capabilities
3
+
---
4
+
1
5
## Sampling
2
6
3
7
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.
4
8
5
9
For a runnable server that combines tools, logging and tasks, see:
The `simpleStreamableHttp` server also includes a `collect-user-info` tool that demonstrates how to drive elicitation from a tool and handle the response.
29
33
@@ -33,8 +37,8 @@ URL elicitation is designed for sensitive data and secure web‑based flows (e.g
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.
32
+
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.
29
33
30
34
## Transports and backwards compatibility
31
35
@@ -36,7 +40,7 @@ To support both modern Streamable HTTP and legacy SSE servers, use a client that
- Server-side auth demo: [`demoInMemoryOAuthProvider.ts`](../examples/shared/src/demoInMemoryOAuthProvider.ts) (tests live under `examples/shared/test/demoInMemoryOAuthProvider.test.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`)
Copy file name to clipboardExpand all lines: docs/server.md
+25-21Lines changed: 25 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,7 @@
1
+
---
2
+
title: Server
3
+
---
4
+
1
5
## Server overview
2
6
3
7
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
8
12
9
13
For a complete, runnable example server, see:
10
14
11
-
-[`simpleStreamableHttp.ts`](../examples/server/src/simpleStreamableHttp.ts) – feature‑rich Streamable HTTP server
12
-
-[`jsonResponseStreamableHttp.ts`](../examples/server/src/jsonResponseStreamableHttp.ts) – Streamable HTTP with JSON response mode
13
-
-[`simpleStatelessStreamableHttp.ts`](../examples/server/src/simpleStatelessStreamableHttp.ts) – stateless Streamable HTTP server
14
-
-[`simpleSseServer.ts`](../examples/server/src/simpleSseServer.ts) – deprecated HTTP+SSE transport
15
-
-[`sseAndStreamableHttpCompatibleServer.ts`](../examples/server/src/sseAndStreamableHttpCompatibleServer.ts) – backwards‑compatible server for old and new clients
15
+
-[`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts) – feature‑rich Streamable HTTP server
16
+
-[`jsonResponseStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/jsonResponseStreamableHttp.ts) – Streamable HTTP with JSON response mode
17
+
-[`simpleStatelessStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStatelessStreamableHttp.ts) – stateless Streamable HTTP server
18
+
-[`simpleSseServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleSseServer.ts) – deprecated HTTP+SSE transport
19
+
-[`sseAndStreamableHttpCompatibleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/sseAndStreamableHttpCompatibleServer.ts) – backwards‑compatible server for old and new clients
16
20
17
21
## Transports
18
22
@@ -27,9 +31,9 @@ Streamable HTTP is the modern, fully featured transport. It supports:
-[`jsonResponseStreamableHttp.ts`](../examples/server/src/jsonResponseStreamableHttp.ts) – `enableJsonResponse: true`, no SSE
32
-
-[`standaloneSseWithGetStreamableHttp.ts`](../examples/server/src/standaloneSseWithGetStreamableHttp.ts) – notifications with Streamable HTTP GET + SSE
-[`jsonResponseStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/jsonResponseStreamableHttp.ts) – `enableJsonResponse: true`, no SSE
36
+
-[`standaloneSseWithGetStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/standaloneSseWithGetStreamableHttp.ts) – notifications with Streamable HTTP GET + SSE
33
37
34
38
See the MCP spec for full transport details: `https://modelcontextprotocol.io/specification/2025-11-25/basic/transports`
- Stateful with resumability: [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)
47
51
48
52
### Deprecated HTTP + SSE
49
53
50
54
The older HTTP+SSE transport (protocol version 2024‑11‑05) is supported only for backwards compatibility. New implementations should prefer Streamable HTTP.
1. Start from [`simpleStreamableHttp.ts`](../examples/server/src/simpleStreamableHttp.ts).
66
+
1. Start from [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts).
63
67
2. Remove features you do not need (tasks, advanced logging, OAuth, etc.).
64
68
3. Register your own tools, resources and prompts.
65
69
@@ -125,8 +129,8 @@ server.registerTool(
125
129
126
130
This snippet is illustrative only; for runnable servers that expose tools, see:
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.
197
201
198
-
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.
202
+
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.
199
203
200
204
### Display names and metadata
201
205
@@ -207,15 +211,15 @@ Tools, resources and prompts support a `title` field for human‑readable names.
207
211
208
212
The SDK supports multi‑node deployments using Streamable HTTP. The high‑level patterns and diagrams live with the runnable server examples:
0 commit comments