Skip to content

Commit 25f288b

Browse files
Add API documentation with GitHub Pages deployment (modelcontextprotocol#1109)
Co-authored-by: Konstantin Konstantinov <konstantin@mach5technology.com>
1 parent 9fc7e28 commit 25f288b

File tree

23 files changed

+11403
-2391
lines changed

23 files changed

+11403
-2391
lines changed

.github/pages/_config.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
title: '@modelcontextprotocol/sdk'
2+
3+
# Include generated files and directories which may start with underscores
4+
include:
5+
- '_*'

.github/pages/index.html

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
# Jekyll front matter to enable Liquid templating
3+
---
4+
5+
<!doctype html>
6+
<html lang="en">
7+
<head>
8+
<meta charset="utf-8" />
9+
<meta name="viewport" content="width=device-width, initial-scale=1" />
10+
<title>MCP TypeScript SDK - API Documentation</title>
11+
<meta http-equiv="refresh" content="1; url={{ site.data.latest_version }}/" />
12+
<link rel="canonical" href="{{ site.data.latest_version }}/" />
13+
<style>
14+
* {
15+
box-sizing: border-box;
16+
}
17+
body {
18+
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
19+
max-width: 800px;
20+
margin: 0 auto;
21+
padding: 2rem;
22+
line-height: 1.6;
23+
color: #333;
24+
}
25+
h1 {
26+
color: #1a1a1a;
27+
border-bottom: 2px solid #eee;
28+
padding-bottom: 0.5rem;
29+
}
30+
h2 {
31+
color: #444;
32+
margin-top: 2rem;
33+
}
34+
a {
35+
color: #0066cc;
36+
text-decoration: none;
37+
}
38+
a:hover {
39+
text-decoration: underline;
40+
}
41+
.redirect-notice {
42+
background: #f0f7ff;
43+
border: 1px solid #cce0ff;
44+
border-radius: 6px;
45+
padding: 1rem;
46+
margin-bottom: 2rem;
47+
}
48+
.versions-table {
49+
width: 100%;
50+
border-collapse: collapse;
51+
margin: 1rem 0;
52+
}
53+
.versions-table th,
54+
.versions-table td {
55+
text-align: left;
56+
padding: 0.75rem;
57+
border-bottom: 1px solid #eee;
58+
}
59+
.versions-table th {
60+
background: #f5f5f5;
61+
font-weight: 600;
62+
}
63+
.package-versions {
64+
display: none;
65+
background: #fafafa;
66+
border-radius: 6px;
67+
padding: 1rem;
68+
margin-top: 1rem;
69+
}
70+
.package-versions.loaded {
71+
display: block;
72+
}
73+
.package-list {
74+
list-style: none;
75+
padding: 0;
76+
margin: 0;
77+
}
78+
.package-list li {
79+
padding: 0.25rem 0;
80+
font-family: monospace;
81+
font-size: 0.9rem;
82+
}
83+
.package-name {
84+
color: #666;
85+
}
86+
.package-version {
87+
color: #0066cc;
88+
font-weight: 500;
89+
}
90+
@media (prefers-color-scheme: dark) {
91+
body {
92+
background: #1a1a1a;
93+
color: #e0e0e0;
94+
}
95+
h1 {
96+
color: #fff;
97+
border-bottom-color: #333;
98+
}
99+
h2 {
100+
color: #ccc;
101+
}
102+
a {
103+
color: #66b3ff;
104+
}
105+
.redirect-notice {
106+
background: #1a2a3a;
107+
border-color: #2a4a6a;
108+
}
109+
.versions-table th {
110+
background: #2a2a2a;
111+
}
112+
.versions-table td,
113+
.versions-table th {
114+
border-bottom-color: #333;
115+
}
116+
.package-versions {
117+
background: #2a2a2a;
118+
}
119+
.package-name {
120+
color: #999;
121+
}
122+
}
123+
</style>
124+
</head>
125+
<body>
126+
<h1>MCP TypeScript SDK</h1>
127+
128+
<div class="redirect-notice">
129+
<p>Redirecting to <a href="{{ site.data.latest_version }}/">latest documentation ({{ site.data.latest_version }})</a>...</p>
130+
</div>
131+
132+
<h2>Package Versions</h2>
133+
<div id="package-versions" class="package-versions">
134+
<p>Loading package versions...</p>
135+
</div>
136+
137+
<h2>All Documentation Versions</h2>
138+
<p>Select a version to view its API documentation:</p>
139+
<ul id="versions-list">
140+
<li><a href="{{ site.data.latest_version }}/">{{ site.data.latest_version }}</a> (latest)</li>
141+
</ul>
142+
143+
<script>
144+
// Redirect to latest version
145+
setTimeout(function() {
146+
window.location.href = '{{ site.data.latest_version }}/';
147+
}, 1000);
148+
149+
// Load and display package versions from versions.json
150+
fetch('{{ site.data.latest_version }}/versions.json')
151+
.then(function(response) {
152+
if (!response.ok) throw new Error('versions.json not found');
153+
return response.json();
154+
})
155+
.then(function(data) {
156+
var container = document.getElementById('package-versions');
157+
var html = '<p>Packages included in the latest documentation:</p><ul class="package-list">';
158+
159+
for (var pkg in data.packages) {
160+
html += '<li><span class="package-name">' + pkg + '</span>: <span class="package-version">' + data.packages[pkg] + '</span></li>';
161+
}
162+
163+
html += '</ul>';
164+
html += '<p style="font-size: 0.85rem; color: #666; margin-top: 1rem;">Generated from tag: ' + data.generated_from_tag + '</p>';
165+
166+
container.innerHTML = html;
167+
container.classList.add('loaded');
168+
})
169+
.catch(function(err) {
170+
// versions.json may not exist for older docs
171+
document.getElementById('package-versions').style.display = 'none';
172+
});
173+
</script>
174+
</body>
175+
</html>

.github/workflows/main.yml

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,3 +108,42 @@ jobs:
108108
- run: pnpm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
109109
env:
110110
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
111+
112+
# Generates API documentation for GitHub Pages on any release
113+
# Supports both simple tags (v1.2.3) and package-scoped tags (@scope/package@1.2.3)
114+
publish-gh-pages:
115+
runs-on: ubuntu-latest
116+
if: github.event_name == 'release'
117+
needs: [publish]
118+
119+
permissions:
120+
contents: write
121+
122+
steps:
123+
- uses: actions/checkout@v4
124+
with:
125+
fetch-depth: 0 # Fetch all history for all branches and tags
126+
127+
- name: Install pnpm
128+
uses: pnpm/action-setup@v4
129+
with:
130+
run_install: false
131+
- uses: actions/setup-node@v4
132+
with:
133+
node-version: 24
134+
cache: pnpm
135+
cache-dependency-path: pnpm-lock.yaml
136+
137+
- name: Install dependencies
138+
run: pnpm install
139+
140+
- name: Configure Git
141+
run: |
142+
git config --global user.name "github-actions[bot]"
143+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
144+
145+
- name: Generate documentation
146+
run: ./scripts/generate-gh-pages.sh "${{ github.ref_name }}"
147+
148+
- name: Push to gh-pages
149+
run: git push origin gh-pages

README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@ Next steps:
132132
- [docs/capabilities.md](docs/capabilities.md) – sampling, elicitation (form and URL), and experimental task-based execution.
133133
- [docs/faq.md](docs/faq.md) – environment and troubleshooting FAQs (including Node.js Web Crypto support).
134134
- External references:
135+
- [SDK API documentation](https://modelcontextprotocol.github.io/typescript-sdk/)
135136
- [Model Context Protocol documentation](https://modelcontextprotocol.io)
136137
- [MCP Specification](https://spec.modelcontextprotocol.io)
137138
- [Example Servers](https://github.com/modelcontextprotocol/servers)

docs/capabilities.md

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
1+
---
2+
title: Capabilities
3+
---
4+
15
## Sampling
26

37
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.
48

59
For a runnable server that combines tools, logging and tasks, see:
610

7-
- [`toolWithSampleServer.ts`](../examples/server/src/toolWithSampleServer.ts)
11+
- [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/toolWithSampleServer.ts)
812

913
In practice you will:
1014

@@ -22,8 +26,8 @@ Form elicitation lets a tool ask the user for additional, **non‑sensitive** in
2226

2327
Runnable example:
2428

25-
- Server: [`elicitationFormExample.ts`](../examples/server/src/elicitationFormExample.ts)
26-
- Client‑side handling: [`simpleStreamableHttp.ts`](../examples/client/src/simpleStreamableHttp.ts)
29+
- Server: [`elicitationFormExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationFormExample.ts)
30+
- Client‑side handling: [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts)
2731

2832
The `simpleStreamableHttp` server also includes a `collect-user-info` tool that demonstrates how to drive elicitation from a tool and handle the response.
2933

@@ -33,8 +37,8 @@ URL elicitation is designed for sensitive data and secure web‑based flows (e.g
3337

3438
Runnable example:
3539

36-
- Server: [`elicitationUrlExample.ts`](../examples/server/src/elicitationUrlExample.ts)
37-
- Client: [`elicitationUrlExample.ts`](../examples/client/src/elicitationUrlExample.ts)
40+
- Server: [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationUrlExample.ts)
41+
- Client: [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/elicitationUrlExample.ts)
3842

3943
Key points:
4044

@@ -62,7 +66,7 @@ On the server you will:
6266

6367
For a runnable example that uses the in-memory store shipped with the SDK, see:
6468

65-
- [`toolWithSampleServer.ts`](../examples/server/src/toolWithSampleServer.ts)
69+
- [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/toolWithSampleServer.ts)
6670
- `packages/core/src/experimental/tasks/stores/in-memory.ts`
6771

6872
### Client-side usage
@@ -74,7 +78,7 @@ On the client, you use:
7478

7579
The interactive client in:
7680

77-
- [`simpleStreamableHttp.ts`](../examples/client/src/simpleStreamableHttp.ts)
81+
- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts)
7882

7983
includes commands to demonstrate calling tools that support tasks and handling their lifecycle.
8084

docs/client.md

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
title: Client
3+
---
4+
15
## Client overview
26

37
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
812

913
Runnable client examples live under:
1014

11-
- [`simpleStreamableHttp.ts`](../examples/client/src/simpleStreamableHttp.ts)
12-
- [`streamableHttpWithSseFallbackClient.ts`](../examples/client/src/streamableHttpWithSseFallbackClient.ts)
13-
- [`ssePollingClient.ts`](../examples/client/src/ssePollingClient.ts)
14-
- [`multipleClientsParallel.ts`](../examples/client/src/multipleClientsParallel.ts)
15-
- [`parallelToolCallsClient.ts`](../examples/client/src/parallelToolCallsClient.ts)
15+
- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleStreamableHttp.ts)
16+
- [`streamableHttpWithSseFallbackClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/streamableHttpWithSseFallbackClient.ts)
17+
- [`ssePollingClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/ssePollingClient.ts)
18+
- [`multipleClientsParallel.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/multipleClientsParallel.ts)
19+
- [`parallelToolCallsClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/parallelToolCallsClient.ts)
1620

1721
## Connecting and basic operations
1822

@@ -25,7 +29,7 @@ A typical flow:
2529
- `listPrompts`, `getPrompt`
2630
- `listResources`, `readResource`
2731

28-
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.
2933

3034
## Transports and backwards compatibility
3135

@@ -36,7 +40,7 @@ To support both modern Streamable HTTP and legacy SSE servers, use a client that
3640

3741
Runnable example:
3842

39-
- [`streamableHttpWithSseFallbackClient.ts`](../examples/client/src/streamableHttpWithSseFallbackClient.ts)
43+
- [`streamableHttpWithSseFallbackClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/streamableHttpWithSseFallbackClient.ts)
4044

4145
## OAuth client authentication helpers
4246

@@ -48,10 +52,10 @@ For OAuth-secured MCP servers, the client `auth` module exposes:
4852

4953
Examples:
5054

51-
- [`simpleOAuthClient.ts`](../examples/client/src/simpleOAuthClient.ts)
52-
- [`simpleOAuthClientProvider.ts`](../examples/client/src/simpleOAuthClientProvider.ts)
53-
- [`simpleClientCredentials.ts`](../examples/client/src/simpleClientCredentials.ts)
54-
- Server-side auth demo: [`demoInMemoryOAuthProvider.ts`](../examples/shared/src/demoInMemoryOAuthProvider.ts) (tests live under `examples/shared/test/demoInMemoryOAuthProvider.test.ts`)
55+
- [`simpleOAuthClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleOAuthClient.ts)
56+
- [`simpleOAuthClientProvider.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleOAuthClientProvider.ts)
57+
- [`simpleClientCredentials.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleClientCredentials.ts)
58+
- 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`)
5559

5660
These examples show how to:
5761

docs/documents.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Documents
3+
children:
4+
- ./server.md
5+
- ./client.md
6+
- ./capabilities.md
7+
- ./faq.md
8+
---
9+
10+
# Documents
11+
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
15+
- [FAQ](./faq.md) – frequently asked questions and troubleshooting

docs/faq.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
title: FAQ
3+
---
4+
15
## FAQ
26

37
<details>

0 commit comments

Comments
 (0)