Include docs/ markdown files in TypeDoc API documentation

- Add `projectDocuments` option to `typedoc.json` to include `docs/*.md`
- Prefix `docs/*.md` filenames with indexes to control sidebar ordering
- Convert relative links to absolute GitHub URLs so they work in the
  generated documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jonathanhefner

docs/server.md docs/01-server.mddocs/server.md renamed to docs/01-server.md

@@ -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/sdk/server/mcp.js` 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`](../src/examples/server/simpleStreamableHttp.ts) – feature‑rich Streamable HTTP server
-- [`jsonResponseStreamableHttp.ts`](../src/examples/server/jsonResponseStreamableHttp.ts) – Streamable HTTP with JSON response mode
-- [`simpleStatelessStreamableHttp.ts`](../src/examples/server/simpleStatelessStreamableHttp.ts) – stateless Streamable HTTP server
-- [`simpleSseServer.ts`](../src/examples/server/simpleSseServer.ts) – deprecated HTTP+SSE transport
-- [`sseAndStreamableHttpCompatibleServer.ts`](../src/examples/server/sseAndStreamableHttpCompatibleServer.ts) – backwards‑compatible server for old and new clients
+- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/simpleStreamableHttp.ts) – feature‑rich Streamable HTTP server
+- [`jsonResponseStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/jsonResponseStreamableHttp.ts) – Streamable HTTP with JSON response mode
+- [`simpleStatelessStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/simpleStatelessStreamableHttp.ts) – stateless Streamable HTTP server
+- [`simpleSseServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/simpleSseServer.ts) – deprecated HTTP+SSE transport
+- [`sseAndStreamableHttpCompatibleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/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`](../src/examples/server/simpleStreamableHttp.ts) – sessions, logging, tasks, elicitation, auth hooks
-- [`jsonResponseStreamableHttp.ts`](../src/examples/server/jsonResponseStreamableHttp.ts) – `enableJsonResponse: true`, no SSE
-- [`standaloneSseWithGetStreamableHttp.ts`](../src/examples/server/standaloneSseWithGetStreamableHttp.ts) – notifications with Streamable HTTP GET + SSE
+- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/simpleStreamableHttp.ts) – sessions, logging, tasks, elicitation, auth hooks
+- [`jsonResponseStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/jsonResponseStreamableHttp.ts) – `enableJsonResponse: true`, no SSE
+- [`standaloneSseWithGetStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/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,24 +46,24 @@ Streamable HTTP can run:
 
 Examples:
 
-- Stateless Streamable HTTP: [`simpleStatelessStreamableHttp.ts`](../src/examples/server/simpleStatelessStreamableHttp.ts)
-- Stateful with resumability: [`simpleStreamableHttp.ts`](../src/examples/server/simpleStreamableHttp.ts)
+- Stateless Streamable HTTP: [`simpleStatelessStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/simpleStatelessStreamableHttp.ts)
+- Stateful with resumability: [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/simpleStreamableHttp.ts)
 
 ### Deprecated HTTP + SSE
 
 The older HTTP+SSE transport (protocol version 2024‑11‑05) is supported only for backwards compatibility. New implementations should prefer Streamable HTTP.
 
 Examples:
 
-- Legacy SSE server: [`simpleSseServer.ts`](../src/examples/server/simpleSseServer.ts)
-- Backwards‑compatible server (Streamable HTTP + SSE):  
-  [`sseAndStreamableHttpCompatibleServer.ts`](../src/examples/server/sseAndStreamableHttpCompatibleServer.ts)
+- Legacy SSE server: [`simpleSseServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/simpleSseServer.ts)
+- Backwards‑compatible server (Streamable HTTP + SSE):
+  [`sseAndStreamableHttpCompatibleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/sseAndStreamableHttpCompatibleServer.ts)
 
 ## Running your server
 
 For a minimal “getting started” experience:
 
-1. Start from [`simpleStreamableHttp.ts`](../src/examples/server/simpleStreamableHttp.ts).
+1. Start from [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/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`](../src/examples/server/simpleStreamableHttp.ts)
-- [`toolWithSampleServer.ts`](../src/examples/server/toolWithSampleServer.ts)
+- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/simpleStreamableHttp.ts)
+- [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/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`](../src/examples/server/simpleStreamableHttp.ts)
+- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/simpleStreamableHttp.ts)
 
 ### Prompts
 
@@ -189,13 +193,13 @@ server.registerPrompt(
 
 For prompts integrated into a full server, see:
 
-- [`simpleStreamableHttp.ts`](../src/examples/server/simpleStreamableHttp.ts)
+- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/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`](../src/examples/client/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/src/examples/client/simpleStreamableHttp.ts) for client‑side usage patterns.
 
 ### Display names and metadata
 
@@ -205,21 +209,21 @@ Tools, resources and prompts support a `title` field for human‑readable names.
 
 ## Multi‑node deployment patterns
 
-The SDK supports multi‑node deployments using Streamable HTTP. The high‑level patterns are documented in [`README.md`](../src/examples/README.md):
+The SDK supports multi‑node deployments using Streamable HTTP. The high‑level patterns are documented in [`README.md`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/README.md):
 
 - Stateless mode (any node can handle any request)
 - Persistent storage mode (shared database for session state)
 - Local state with message routing (message queue + pub/sub)
 
-Those deployment diagrams are kept in [`README.md`](../src/examples/README.md) so the examples and documentation stay aligned.
+Those deployment diagrams are kept in [`README.md`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/README.md) so the examples and documentation stay aligned.
 
 ## Backwards compatibility
 
 To handle both modern and legacy clients:
 
 - Run a backwards‑compatible server:
-    - [`sseAndStreamableHttpCompatibleServer.ts`](../src/examples/server/sseAndStreamableHttpCompatibleServer.ts)
+    - [`sseAndStreamableHttpCompatibleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/sseAndStreamableHttpCompatibleServer.ts)
 - Use a client that falls back from Streamable HTTP to SSE:
-    - [`streamableHttpWithSseFallbackClient.ts`](../src/examples/client/streamableHttpWithSseFallbackClient.ts)
+    - [`streamableHttpWithSseFallbackClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/streamableHttpWithSseFallbackClient.ts)
 
 For the detailed protocol rules, see the “Backwards compatibility” section of the MCP spec.

docs/02-client.md

@@ -0,0 +1,64 @@
+---
+title: Client
+---
+
+## Client overview
+
+The SDK provides a high-level `Client` class that connects to MCP servers over different transports:
+
+- `StdioClientTransport` – for local processes you spawn.
+- `StreamableHTTPClientTransport` – for remote HTTP servers.
+- `SSEClientTransport` – for legacy HTTP+SSE servers (deprecated).
+
+Runnable client examples live under:
+
+- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/simpleStreamableHttp.ts)
+- [`streamableHttpWithSseFallbackClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/streamableHttpWithSseFallbackClient.ts)
+- [`ssePollingClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/ssePollingClient.ts)
+- [`multipleClientsParallel.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/multipleClientsParallel.ts)
+- [`parallelToolCallsClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/parallelToolCallsClient.ts)
+
+## Connecting and basic operations
+
+A typical flow:
+
+1. Construct a `Client` with name, version and capabilities.
+2. Create a transport and call `client.connect(transport)`.
+3. Use high-level helpers:
+    - `listTools`, `callTool`
+    - `listPrompts`, `getPrompt`
+    - `listResources`, `readResource`
+
+See [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/simpleStreamableHttp.ts) for an interactive CLI client that exercises these methods and shows how to handle notifications, elicitation and tasks.
+
+## Transports and backwards compatibility
+
+To support both modern Streamable HTTP and legacy SSE servers, use a client that:
+
+1. Tries `StreamableHTTPClientTransport`.
+2. Falls back to `SSEClientTransport` on a 4xx response.
+
+Runnable example:
+
+- [`streamableHttpWithSseFallbackClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/streamableHttpWithSseFallbackClient.ts)
+
+## OAuth client authentication helpers
+
+For OAuth-secured MCP servers, the client `auth` module exposes:
+
+- `ClientCredentialsProvider`
+- `PrivateKeyJwtProvider`
+- `StaticPrivateKeyJwtProvider`
+
+Examples:
+
+- [`simpleOAuthClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/simpleOAuthClient.ts)
+- [`simpleOAuthClientProvider.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/simpleOAuthClientProvider.ts)
+- [`simpleClientCredentials.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/simpleClientCredentials.ts)
+- Server-side auth demo: [`demoInMemoryOAuthProvider.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/demoInMemoryOAuthProvider.ts) (tests live under `test/examples/server/demoInMemoryOAuthProvider.test.ts`)
+
+These examples show how to:
+
+- Perform dynamic client registration if needed.
+- Acquire access tokens.
+- Attach OAuth credentials to Streamable HTTP requests.

docs/capabilities.md docs/03-capabilities.mddocs/capabilities.md renamed to docs/03-capabilities.md

@@ -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`](../src/examples/server/toolWithSampleServer.ts)
+- [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/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`](../src/examples/server/elicitationFormExample.ts)
-- Client‑side handling: [`simpleStreamableHttp.ts`](../src/examples/client/simpleStreamableHttp.ts)
+- Server: [`elicitationFormExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/elicitationFormExample.ts)
+- Client‑side handling: [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/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`](../src/examples/server/elicitationUrlExample.ts)
-- Client: [`elicitationUrlExample.ts`](../src/examples/client/elicitationUrlExample.ts)
+- Server: [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/elicitationUrlExample.ts)
+- Client: [`elicitationUrlExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/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`](../src/examples/server/toolWithSampleServer.ts)
+- [`toolWithSampleServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/server/toolWithSampleServer.ts)
 - `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`](../src/examples/client/simpleStreamableHttp.ts)
+- [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/client/simpleStreamableHttp.ts)
 
 includes commands to demonstrate calling tools that support tasks and handling their lifecycle.
 

docs/faq.md docs/04-faq.mddocs/faq.md renamed to docs/04-faq.md

@@ -1,3 +1,7 @@
+---
+title: FAQ
+---
+
 ## FAQ
 
 <details>

docs/client.md

@@ -2,5 +2,10 @@
     "$schema": "https://typedoc.org/schema.json",
     "entryPoints": ["src"],
     "entryPointStrategy": "expand",
-    "exclude": ["**/*.test.ts", "**/__*__/**", "**/examples/**", "**/integration-tests/**", "**/spec.types.ts", "**/zodTestMatrix.ts"]
+    "exclude": ["**/*.test.ts", "**/__*__/**", "**/examples/**", "**/integration-tests/**", "**/spec.types.ts", "**/zodTestMatrix.ts"],
+    "projectDocuments": ["docs/*.md"],
+    "navigation": {
+      "includeGroups": true,
+      "includeCategories": true
+    }
 }