Skip to content

Commit 58ce8a1

Browse files
KKonstantinovKKonstantinov
committed
README refactor
1 parent 4fb4d4d commit 58ce8a1

File tree

8 files changed

+529
-1792
lines changed

8 files changed

+529
-1792
lines changed

‎README.md‎

Lines changed: 83 additions & 1792 deletions
Large diffs are not rendered by default.

‎docs/client.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
## Client overview
2+
3+
The SDK provides a high-level `Client` class that connects to MCP servers over
4+
different transports:
5+
6+
- `StdioClientTransport` – for local processes you spawn.
7+
- `StreamableHTTPClientTransport` – for remote HTTP servers.
8+
- `SSEClientTransport` – for legacy HTTP+SSE servers (deprecated).
9+
10+
Runnable client examples live under:
11+
12+
- `src/examples/client/simpleStreamableHttp.ts`
13+
- `src/examples/client/streamableHttpWithSseFallbackClient.ts`
14+
- `src/examples/client/ssePollingClient.ts`
15+
- `src/examples/client/multipleClientsParallel.ts`
16+
- `src/examples/client/parallelToolCallsClient.ts`
17+
18+
## Connecting and basic operations
19+
20+
A typical flow:
21+
22+
1. Construct a `Client` with name, version and capabilities.
23+
2. Create a transport and call `client.connect(transport)`.
24+
3. Use high-level helpers:
25+
- `listTools`, `callTool`
26+
- `listPrompts`, `getPrompt`
27+
- `listResources`, `readResource`
28+
29+
See `src/examples/client/simpleStreamableHttp.ts` for an interactive CLI client
30+
that exercises these methods and shows how to handle notifications, elicitation
31+
and tasks.
32+
33+
## Transports and backwards compatibility
34+
35+
To support both modern Streamable HTTP and legacy SSE servers, use a client
36+
that:
37+
38+
1. Tries `StreamableHTTPClientTransport`.
39+
2. Falls back to `SSEClientTransport` on a 4xx response.
40+
41+
Runnable example:
42+
43+
- `src/examples/client/streamableHttpWithSseFallbackClient.ts`
44+
45+
## OAuth client authentication helpers
46+
47+
For OAuth-secured MCP servers, the client `auth` module exposes:
48+
49+
- `ClientCredentialsProvider`
50+
- `PrivateKeyJwtProvider`
51+
- `StaticPrivateKeyJwtProvider`
52+
53+
Examples:
54+
55+
- `src/examples/client/simpleOAuthClient.ts`
56+
- `src/examples/client/simpleOAuthClientProvider.ts`
57+
- `src/examples/client/simpleClientCredentials.ts`
58+
- Server-side auth demo: `src/examples/server/demoInMemoryOAuthProvider.ts`
59+
60+
These examples show how to:
61+
62+
- Perform dynamic client registration if needed.
63+
- Acquire access tokens.
64+
- Attach OAuth credentials to Streamable HTTP requests.
65+
66+
67+

‎docs/faq.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
## FAQ
2+
3+
- [General](#general)
4+
- [Clients](#clients)
5+
- [Servers](#servers)
6+
7+
## General
8+
9+
### Why do I see `TS2589: Type instantiation is excessively deep and possibly infinite` after upgrading the SDK?
10+
11+
This TypeScript error can appear when upgrading to newer SDK versions that support Zod v4 (for example, from `@modelcontextprotocol/sdk` `1.22.0` to `1.23.0`) **and** your project ends up with multiple `zod` versions in the dependency tree.
12+
13+
When there are multiple copies or versions of `zod`, TypeScript may try to instantiate very complex, cross-version types and hit its recursion limits, resulting in `TS2589`. This scenario is discussed in GitHub issue [#1180](https://github.com/modelcontextprotocol/typescript-sdk/issues/1180#event-21236550401).
14+
15+
To diagnose and fix this:
16+
17+
- **Inspect your installed `zod` versions**:
18+
- Run `npm ls zod` or `npm explain zod`, `pnpm list zod` or `pnpm why zod`, or `yarn why zod` and check whether more than one version is installed.
19+
- **Align on a single `zod` version**:
20+
- Make sure all packages that depend on `zod` use a compatible version range so that your package manager can hoist a single copy.
21+
- In monorepos, consider declaring `zod` at the workspace root and using compatible ranges in individual packages.
22+
- **Use overrides/resolutions if necessary**:
23+
- With npm, Yarn, or pnpm, you can use `overrides` / `resolutions` to force a single `zod` version if some transitive dependencies pull in a different one.
24+
25+
Once your project is using a single, compatible `zod` version, the `TS2589` error should no longer occur.
26+
27+
## Clients
28+
29+
### How do I enable Web Crypto (`globalThis.crypto`) for client authentication in older Node.js versions?
30+
31+
The SDK’s OAuth client authentication helpers (for example, those in `src/client/auth-extensions.ts` that use `jose`) rely on the Web Crypto API exposed as `globalThis.crypto`. This is especially important for **client credentials** and **JWT-based** authentication flows used by MCP clients.
32+
33+
- **Node.js v19.0.0 and later**: `globalThis.crypto` is available by default.
34+
- **Node.js v18.x**: `globalThis.crypto` may not be defined by default. In this repository we polyfill it for tests (see `vitest.setup.ts`), and you should do the same in your app if it is missing – or alternatively, run Node with `--experimental-global-webcrypto` as per your
35+
Node version documentation. (See https://nodejs.org/dist/latest-v18.x/docs/api/globals.html#crypto )
36+
37+
If you run clients on Node.js versions where `globalThis.crypto` is missing, you can polyfill it using the built-in `node:crypto` module, similar to the SDK's own `vitest.setup.ts`:
38+
39+
```typescript
40+
import { webcrypto } from 'node:crypto';
41+
42+
if (typeof globalThis.crypto === 'undefined') {
43+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
44+
(globalThis as any).crypto = webcrypto as unknown as Crypto;
45+
}
46+
```
47+
48+
For production use, you can either:
49+
50+
- Run clients on a Node.js version where `globalThis.crypto` is available by default (recommended), or
51+
- Apply a similar polyfill early in your client's startup code when targeting older Node.js runtimes, so that OAuth client authentication works reliably.
52+
53+
## Servers
54+
55+
### Where can I find runnable server examples?
56+
57+
The SDK ships several runnable server examples under `src/examples/server`. The root `README.md` contains a curated **Server examples** table that links to each scenario (stateful/stateless Streamable HTTP, JSON-only mode, SSE/backwards compatibility, elicitation, sampling, tasks, and OAuth demos), and `src/examples/README.md` includes commands and deployment diagrams for running them.
58+
59+

‎docs/sampling-and-elicitation.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
## Sampling
2+
3+
MCP servers can request LLM completions from connected clients that support the
4+
sampling capability. This lets your tools offload summarisation or generation
5+
to the client’s model.
6+
7+
For a runnable server that combines tools, logging and tasks, see:
8+
9+
- `src/examples/server/toolWithSampleServer.ts`
10+
11+
In practice you will:
12+
13+
- Declare the sampling capability on the client.
14+
- Call `server.server.createMessage(...)` from within a tool handler.
15+
- Return the model’s response as structured content and/or text.
16+
17+
Refer to the MCP spec’s sampling section for full request/response details.
18+
19+
## Form elicitation
20+
21+
Form elicitation lets a tool ask the user for additional, **non‑sensitive**
22+
information via a schema‑driven form. The server sends a schema and message,
23+
and the client is responsible for collecting and returning the data.
24+
25+
Runnable example:
26+
27+
- Server: `src/examples/server/elicitationFormExample.ts`
28+
- Client‑side handling: `src/examples/client/simpleStreamableHttp.ts`
29+
30+
The `simpleStreamableHttp` server also includes a `collect-user-info` tool that
31+
demonstrates how to drive elicitation from a tool and handle the response.
32+
33+
## URL elicitation
34+
35+
URL elicitation is designed for sensitive data and secure web‑based flows
36+
(e.g., collecting an API key, confirming a payment, or doing third‑party OAuth).
37+
Instead of returning form data, the server asks the client to open a URL and
38+
the rest of the flow happens in the browser.
39+
40+
Runnable example:
41+
42+
- Server: `src/examples/server/elicitationUrlExample.ts`
43+
- Client: `src/examples/client/elicitationUrlExample.ts`
44+
45+
Key points:
46+
47+
- Use `mode: 'url'` when calling `server.server.elicitInput(...)`.
48+
- Implement a client‑side handler for `ElicitRequestSchema` that:
49+
- Shows the full URL and reason to the user.
50+
- Asks for explicit consent.
51+
- Opens the URL in the system browser.
52+
53+
Sensitive information **must not** be collected via form elicitation; always
54+
use URL elicitation or out‑of‑band flows for secrets.
55+
56+
57+

‎docs/server.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
## Server overview
2+
3+
This SDK lets you build MCP servers in TypeScript and connect them to different transports.
4+
For most use cases you will use `McpServer` from `@modelcontextprotocol/sdk/server/mcp.js`
5+
and choose one of:
6+
7+
- **Streamable HTTP** (recommended for remote servers)
8+
- **HTTP + SSE** (deprecated, for backwards compatibility only)
9+
- **stdio** (for local, process‑spawned integrations)
10+
11+
For a complete, runnable example server, see:
12+
13+
- `src/examples/server/simpleStreamableHttp.ts` – feature‑rich Streamable HTTP server
14+
- `src/examples/server/jsonResponseStreamableHttp.ts` – Streamable HTTP with JSON response mode
15+
- `src/examples/server/simpleStatelessStreamableHttp.ts` – stateless Streamable HTTP server
16+
- `src/examples/server/simpleSseServer.ts` – deprecated HTTP+SSE transport
17+
- `src/examples/server/sseAndStreamableHttpCompatibleServer.ts` – backwards‑compatible server for old and new clients
18+
19+
## Transports
20+
21+
### Streamable HTTP
22+
23+
Streamable HTTP is the modern, fully featured transport. It supports:
24+
25+
- Request/response over HTTP POST
26+
- Server‑to‑client notifications over SSE (when enabled)
27+
- Optional JSON‑only response mode with no SSE
28+
- Session management and resumability
29+
30+
Key examples:
31+
32+
- `src/examples/server/simpleStreamableHttp.ts` – sessions, logging, tasks, elicitation, auth hooks
33+
- `src/examples/server/jsonResponseStreamableHttp.ts` – `enableJsonResponse: true`, no SSE
34+
- `src/examples/server/standaloneSseWithGetStreamableHttp.ts` – notifications with Streamable HTTP GET + SSE
35+
36+
See the MCP spec for full transport details:
37+
`https://modelcontextprotocol.io/specification/2025-03-26/basic/transports`
38+
39+
### Stateless vs stateful sessions
40+
41+
Streamable HTTP can run:
42+
43+
- **Stateless** – no session tracking, ideal for simple API‑style servers.
44+
- **Stateful** – sessions have IDs, and you can enable resumability and advanced features.
45+
46+
Examples:
47+
48+
- Stateless Streamable HTTP: `src/examples/server/simpleStatelessStreamableHttp.ts`
49+
- Stateful with resumability: `src/examples/server/simpleStreamableHttp.ts`
50+
51+
### Deprecated HTTP + SSE
52+
53+
The older HTTP+SSE transport (protocol version 2024‑11‑05) is supported only for
54+
backwards compatibility. New implementations should prefer Streamable HTTP.
55+
56+
Examples:
57+
58+
- Legacy SSE server: `src/examples/server/simpleSseServer.ts`
59+
- Backwards‑compatible server (Streamable HTTP + SSE):
60+
`src/examples/server/sseAndStreamableHttpCompatibleServer.ts`
61+
62+
## Running your server
63+
64+
For a minimal “getting started” experience:
65+
66+
1. Start from `src/examples/server/simpleStreamableHttp.ts`.
67+
2. Remove features you do not need (tasks, advanced logging, OAuth, etc.).
68+
3. Register your own tools, resources and prompts.
69+
70+
For more detailed patterns (stateless vs stateful, JSON response mode, CORS, DNS
71+
rebind protection), see the examples above and the MCP spec sections on transports.
72+
73+
## Multi‑node deployment patterns
74+
75+
The SDK supports multi‑node deployments using Streamable HTTP. The high‑level
76+
patterns are documented in `src/examples/README.md`:
77+
78+
- Stateless mode (any node can handle any request)
79+
- Persistent storage mode (shared database for session state)
80+
- Local state with message routing (message queue + pub/sub)
81+
82+
Those deployment diagrams are kept in `src/examples/README.md` so the examples
83+
and documentation stay aligned.
84+
85+
## Backwards compatibility
86+
87+
To handle both modern and legacy clients:
88+
89+
- Run a backwards‑compatible server:
90+
- `src/examples/server/sseAndStreamableHttpCompatibleServer.ts`
91+
- Use a client that falls back from Streamable HTTP to SSE:
92+
- `src/examples/client/streamableHttpWithSseFallbackClient.ts`
93+
94+
For the detailed protocol rules, see the “Backwards compatibility” section of the MCP spec.
95+
96+
97+

‎docs/tasks-and-long-running.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
## Task-based execution (experimental)
2+
3+
Task-based execution enables “call-now, fetch-later” patterns for long-running
4+
operations. Instead of returning a result immediately, a tool creates a task
5+
that can be polled or resumed later.
6+
7+
The APIs live under the experimental `.experimental.tasks` namespace and may
8+
change without notice.
9+
10+
### Server-side concepts
11+
12+
On the server you will:
13+
14+
- Provide a `TaskStore` implementation that persists task metadata and results.
15+
- Enable the `tasks` capability when constructing the server.
16+
- Register tools with `server.experimental.tasks.registerToolTask(...)`.
17+
18+
For a runnable example that uses the in-memory store shipped with the SDK, see:
19+
20+
- `src/examples/server/toolWithSampleServer.ts`
21+
- `src/experimental/tasks/stores/in-memory.ts`
22+
23+
### Client-side usage
24+
25+
On the client, you use:
26+
27+
- `client.experimental.tasks.callToolStream(...)` to start a tool call that may
28+
create a task and emit status updates over time.
29+
- `client.getTask(...)` and `client.getTaskResult(...)` to check status and
30+
fetch results after reconnecting.
31+
32+
The interactive client in:
33+
34+
- `src/examples/client/simpleStreamableHttp.ts`
35+
36+
includes commands to demonstrate calling tools that support tasks and handling
37+
their lifecycle.
38+
39+
See the MCP spec’s tasks section and the example server/client above for a full
40+
walkthrough of the task status lifecycle and TTL handling.
41+
42+
43+

0 commit comments

Comments
 (0)