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
23 changed files with 11403 additions and 2391 deletions
5
.github/pages/_config.yml
vendored
Normal file
5
.github/pages/_config.yml
vendored
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
title: '@modelcontextprotocol/sdk'
|
||||
|
||||
# Include generated files and directories which may start with underscores
|
||||
include:
|
||||
- '_*'
|
||||
175
.github/pages/index.html
vendored
Normal file
175
.github/pages/index.html
vendored
Normal file
|
|
@ -0,0 +1,175 @@
|
|||
---
|
||||
# Jekyll front matter to enable Liquid templating
|
||||
---
|
||||
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>MCP TypeScript SDK - API Documentation</title>
|
||||
<meta http-equiv="refresh" content="1; url={{ site.data.latest_version }}/" />
|
||||
<link rel="canonical" href="{{ site.data.latest_version }}/" />
|
||||
<style>
|
||||
* {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
|
||||
max-width: 800px;
|
||||
margin: 0 auto;
|
||||
padding: 2rem;
|
||||
line-height: 1.6;
|
||||
color: #333;
|
||||
}
|
||||
h1 {
|
||||
color: #1a1a1a;
|
||||
border-bottom: 2px solid #eee;
|
||||
padding-bottom: 0.5rem;
|
||||
}
|
||||
h2 {
|
||||
color: #444;
|
||||
margin-top: 2rem;
|
||||
}
|
||||
a {
|
||||
color: #0066cc;
|
||||
text-decoration: none;
|
||||
}
|
||||
a:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
.redirect-notice {
|
||||
background: #f0f7ff;
|
||||
border: 1px solid #cce0ff;
|
||||
border-radius: 6px;
|
||||
padding: 1rem;
|
||||
margin-bottom: 2rem;
|
||||
}
|
||||
.versions-table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 1rem 0;
|
||||
}
|
||||
.versions-table th,
|
||||
.versions-table td {
|
||||
text-align: left;
|
||||
padding: 0.75rem;
|
||||
border-bottom: 1px solid #eee;
|
||||
}
|
||||
.versions-table th {
|
||||
background: #f5f5f5;
|
||||
font-weight: 600;
|
||||
}
|
||||
.package-versions {
|
||||
display: none;
|
||||
background: #fafafa;
|
||||
border-radius: 6px;
|
||||
padding: 1rem;
|
||||
margin-top: 1rem;
|
||||
}
|
||||
.package-versions.loaded {
|
||||
display: block;
|
||||
}
|
||||
.package-list {
|
||||
list-style: none;
|
||||
padding: 0;
|
||||
margin: 0;
|
||||
}
|
||||
.package-list li {
|
||||
padding: 0.25rem 0;
|
||||
font-family: monospace;
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
.package-name {
|
||||
color: #666;
|
||||
}
|
||||
.package-version {
|
||||
color: #0066cc;
|
||||
font-weight: 500;
|
||||
}
|
||||
@media (prefers-color-scheme: dark) {
|
||||
body {
|
||||
background: #1a1a1a;
|
||||
color: #e0e0e0;
|
||||
}
|
||||
h1 {
|
||||
color: #fff;
|
||||
border-bottom-color: #333;
|
||||
}
|
||||
h2 {
|
||||
color: #ccc;
|
||||
}
|
||||
a {
|
||||
color: #66b3ff;
|
||||
}
|
||||
.redirect-notice {
|
||||
background: #1a2a3a;
|
||||
border-color: #2a4a6a;
|
||||
}
|
||||
.versions-table th {
|
||||
background: #2a2a2a;
|
||||
}
|
||||
.versions-table td,
|
||||
.versions-table th {
|
||||
border-bottom-color: #333;
|
||||
}
|
||||
.package-versions {
|
||||
background: #2a2a2a;
|
||||
}
|
||||
.package-name {
|
||||
color: #999;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>MCP TypeScript SDK</h1>
|
||||
|
||||
<div class="redirect-notice">
|
||||
<p>Redirecting to <a href="{{ site.data.latest_version }}/">latest documentation ({{ site.data.latest_version }})</a>...</p>
|
||||
</div>
|
||||
|
||||
<h2>Package Versions</h2>
|
||||
<div id="package-versions" class="package-versions">
|
||||
<p>Loading package versions...</p>
|
||||
</div>
|
||||
|
||||
<h2>All Documentation Versions</h2>
|
||||
<p>Select a version to view its API documentation:</p>
|
||||
<ul id="versions-list">
|
||||
<li><a href="{{ site.data.latest_version }}/">{{ site.data.latest_version }}</a> (latest)</li>
|
||||
</ul>
|
||||
|
||||
<script>
|
||||
// Redirect to latest version
|
||||
setTimeout(function() {
|
||||
window.location.href = '{{ site.data.latest_version }}/';
|
||||
}, 1000);
|
||||
|
||||
// Load and display package versions from versions.json
|
||||
fetch('{{ site.data.latest_version }}/versions.json')
|
||||
.then(function(response) {
|
||||
if (!response.ok) throw new Error('versions.json not found');
|
||||
return response.json();
|
||||
})
|
||||
.then(function(data) {
|
||||
var container = document.getElementById('package-versions');
|
||||
var html = '<p>Packages included in the latest documentation:</p><ul class="package-list">';
|
||||
|
||||
for (var pkg in data.packages) {
|
||||
html += '<li><span class="package-name">' + pkg + '</span>: <span class="package-version">' + data.packages[pkg] + '</span></li>';
|
||||
}
|
||||
|
||||
html += '</ul>';
|
||||
html += '<p style="font-size: 0.85rem; color: #666; margin-top: 1rem;">Generated from tag: ' + data.generated_from_tag + '</p>';
|
||||
|
||||
container.innerHTML = html;
|
||||
container.classList.add('loaded');
|
||||
})
|
||||
.catch(function(err) {
|
||||
// versions.json may not exist for older docs
|
||||
document.getElementById('package-versions').style.display = 'none';
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
39
.github/workflows/main.yml
vendored
39
.github/workflows/main.yml
vendored
|
|
@ -108,3 +108,42 @@ jobs:
|
|||
- run: pnpm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
|
||||
env:
|
||||
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
|
||||
# Generates API documentation for GitHub Pages on any release
|
||||
# Supports both simple tags (v1.2.3) and package-scoped tags (@scope/package@1.2.3)
|
||||
publish-gh-pages:
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event_name == 'release'
|
||||
needs: [publish]
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # Fetch all history for all branches and tags
|
||||
|
||||
- name: Install pnpm
|
||||
uses: pnpm/action-setup@v4
|
||||
with:
|
||||
run_install: false
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 24
|
||||
cache: pnpm
|
||||
cache-dependency-path: pnpm-lock.yaml
|
||||
|
||||
- name: Install dependencies
|
||||
run: pnpm install
|
||||
|
||||
- name: Configure Git
|
||||
run: |
|
||||
git config --global user.name "github-actions[bot]"
|
||||
git config --global user.email "github-actions[bot]@users.noreply.github.com"
|
||||
|
||||
- name: Generate documentation
|
||||
run: ./scripts/generate-gh-pages.sh "${{ github.ref_name }}"
|
||||
|
||||
- name: Push to gh-pages
|
||||
run: git push origin gh-pages
|
||||
|
|
|
|||
|
|
@ -132,6 +132,7 @@ Next steps:
|
|||
- [docs/capabilities.md](docs/capabilities.md) – sampling, elicitation (form and URL), and experimental task-based execution.
|
||||
- [docs/faq.md](docs/faq.md) – environment and troubleshooting FAQs (including Node.js Web Crypto support).
|
||||
- External references:
|
||||
- [SDK API documentation](https://modelcontextprotocol.github.io/typescript-sdk/)
|
||||
- [Model Context Protocol documentation](https://modelcontextprotocol.io)
|
||||
- [MCP Specification](https://spec.modelcontextprotocol.io)
|
||||
- [Example Servers](https://github.com/modelcontextprotocol/servers)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
4878
package-lock.json
generated
Normal file
4878
package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -1,5 +1,6 @@
|
|||
{
|
||||
"name": "@modelcontextprotocol/sdk",
|
||||
"private": true,
|
||||
"version": "2.0.0-alpha.0",
|
||||
"description": "Model Context Protocol implementation for TypeScript",
|
||||
"license": "SEE LICENSE IN LICENSE",
|
||||
|
|
@ -23,6 +24,8 @@
|
|||
"scripts": {
|
||||
"fetch:spec-types": "tsx scripts/fetch-spec-types.ts",
|
||||
"examples:simple-server:w": "pnpm --filter @modelcontextprotocol/examples-server exec tsx --watch src/simpleStreamableHttp.ts --oauth",
|
||||
"docs": "typedoc",
|
||||
"docs:check": "typedoc --emit none",
|
||||
"typecheck:all": "pnpm -r typecheck",
|
||||
"build:all": "pnpm -r build",
|
||||
"prepack:all": "pnpm -r prepack",
|
||||
|
|
@ -45,8 +48,10 @@
|
|||
"@eslint/js": "catalog:devTools",
|
||||
"@modelcontextprotocol/client": "workspace:^",
|
||||
"@modelcontextprotocol/conformance": "0.1.9",
|
||||
"@modelcontextprotocol/server": "workspace:^",
|
||||
"@modelcontextprotocol/node": "workspace:^",
|
||||
"@modelcontextprotocol/server": "workspace:^",
|
||||
"@pnpm/workspace.find-packages": "^1000.0.54",
|
||||
"@pnpm/workspace.read-manifest": "^1000.2.9",
|
||||
"@types/content-type": "catalog:devTools",
|
||||
"@types/cors": "catalog:devTools",
|
||||
"@types/cross-spawn": "catalog:devTools",
|
||||
|
|
@ -65,7 +70,9 @@
|
|||
"prettier": "catalog:devTools",
|
||||
"supertest": "catalog:devTools",
|
||||
"tsdown": "catalog:devTools",
|
||||
"tslib": "^2.8.1",
|
||||
"tsx": "catalog:devTools",
|
||||
"typedoc": "catalog:devTools",
|
||||
"typescript": "catalog:devTools",
|
||||
"typescript-eslint": "catalog:devTools",
|
||||
"vitest": "catalog:devTools",
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@
|
|||
"prepack": "npm run build",
|
||||
"lint": "eslint src/ && prettier --ignore-path ../../.prettierignore --check .",
|
||||
"lint:fix": "eslint src/ --fix && prettier --ignore-path ../../.prettierignore --write .",
|
||||
"check": "npm run typecheck && npm run lint",
|
||||
"check": "npm run typecheck && npm run lint && pnpm exec -- typedoc --emit none",
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"start": "npm run server",
|
||||
|
|
|
|||
10
packages/client/typedoc.json
Normal file
10
packages/client/typedoc.json
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"$schema": "https://typedoc.org/schema.json",
|
||||
"entryPoints": ["src"],
|
||||
"entryPointStrategy": "expand",
|
||||
"exclude": ["**/*.test.ts"],
|
||||
"navigation": {
|
||||
"includeGroups": true,
|
||||
"includeCategories": true
|
||||
}
|
||||
}
|
||||
|
|
@ -18,8 +18,9 @@ export function resourceUrlFromServerUrl(url: URL | string): URL {
|
|||
* A requested resource matches if it has the same scheme, domain, port,
|
||||
* and its path starts with the configured resource's path.
|
||||
*
|
||||
* @param requestedResource The resource URL being requested
|
||||
* @param configuredResource The resource URL that has been configured
|
||||
* @param options - The options object
|
||||
* @param options.requestedResource - The resource URL being requested
|
||||
* @param options.configuredResource - The resource URL that has been configured
|
||||
* @returns true if the requested resource matches the configured resource, false otherwise
|
||||
*/
|
||||
export function checkResourceAllowed({
|
||||
|
|
|
|||
10
packages/middleware/express/typedoc.json
Normal file
10
packages/middleware/express/typedoc.json
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"$schema": "https://typedoc.org/schema.json",
|
||||
"entryPoints": ["src"],
|
||||
"entryPointStrategy": "expand",
|
||||
"exclude": ["**/*.test.ts"],
|
||||
"navigation": {
|
||||
"includeGroups": true,
|
||||
"includeCategories": true
|
||||
}
|
||||
}
|
||||
10
packages/middleware/hono/typedoc.json
Normal file
10
packages/middleware/hono/typedoc.json
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"$schema": "https://typedoc.org/schema.json",
|
||||
"entryPoints": ["src"],
|
||||
"entryPointStrategy": "expand",
|
||||
"exclude": ["**/*.test.ts"],
|
||||
"navigation": {
|
||||
"includeGroups": true,
|
||||
"includeCategories": true
|
||||
}
|
||||
}
|
||||
10
packages/middleware/node/typedoc.json
Normal file
10
packages/middleware/node/typedoc.json
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"$schema": "https://typedoc.org/schema.json",
|
||||
"entryPoints": ["src"],
|
||||
"entryPointStrategy": "expand",
|
||||
"exclude": ["**/*.test.ts"],
|
||||
"navigation": {
|
||||
"includeGroups": true,
|
||||
"includeCategories": true
|
||||
}
|
||||
}
|
||||
|
|
@ -37,7 +37,7 @@
|
|||
"prepack": "npm run build",
|
||||
"lint": "eslint src/ && prettier --ignore-path ../../.prettierignore --check .",
|
||||
"lint:fix": "eslint src/ --fix && prettier --ignore-path ../../.prettierignore --write .",
|
||||
"check": "npm run typecheck && npm run lint",
|
||||
"check": "npm run typecheck && npm run lint && pnpm exec -- typedoc --emit none",
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"start": "npm run server",
|
||||
|
|
|
|||
10
packages/server/typedoc.json
Normal file
10
packages/server/typedoc.json
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"$schema": "https://typedoc.org/schema.json",
|
||||
"entryPoints": ["src"],
|
||||
"entryPointStrategy": "expand",
|
||||
"exclude": ["**/*.test.ts", "**/__*__/**"],
|
||||
"navigation": {
|
||||
"includeGroups": true,
|
||||
"includeCategories": true
|
||||
}
|
||||
}
|
||||
3686
pnpm-lock.yaml
generated
3686
pnpm-lock.yaml
generated
File diff suppressed because it is too large
Load diff
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue