consolidate docs

Author: KKonstantinov

README.md

@@ -0,0 +1,81 @@
+## 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)
+
+In practice you will:
+
+- Declare the sampling capability on the client.
+- Call `server.server.createMessage(...)` from within a tool handler.
+- Return the model’s response as structured content and/or text.
+
+Refer to the MCP spec’s sampling section for full request/response details.
+
+## Elicitation
+
+### Form elicitation
+
+Form elicitation lets a tool ask the user for additional, **non‑sensitive** information via a schema‑driven form. The server sends a schema and message, and the client is responsible for collecting and returning the data.
+
+Runnable example:
+
+- Server: [`elicitationFormExample.ts`](../src/examples/server/elicitationFormExample.ts)
+- Client‑side handling: [`simpleStreamableHttp.ts`](../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.
+
+### URL elicitation
+
+URL elicitation is designed for sensitive data and secure web‑based flows (e.g., collecting an API key, confirming a payment, or doing third‑party OAuth). Instead of returning form data, the server asks the client to open a URL and the rest of the flow happens in the browser.
+
+Runnable example:
+
+- Server: [`elicitationUrlExample.ts`](../src/examples/server/elicitationUrlExample.ts)
+- Client: [`elicitationUrlExample.ts`](../src/examples/client/elicitationUrlExample.ts)
+
+Key points:
+
+- Use `mode: 'url'` when calling `server.server.elicitInput(...)`.
+- Implement a client‑side handler for `ElicitRequestSchema` that:
+    - Shows the full URL and reason to the user.
+    - Asks for explicit consent.
+    - Opens the URL in the system browser.
+
+Sensitive information **must not** be collected via form elicitation; always use URL elicitation or out‑of‑band flows for secrets.
+
+## Task-based execution (experimental)
+
+Task-based execution enables “call-now, fetch-later” patterns for long-running operations. Instead of returning a result immediately, a tool creates a task that can be polled or resumed later.
+
+The APIs live under the experimental `.experimental.tasks` namespace and may change without notice.
+
+### Server-side concepts
+
+On the server you will:
+
+- Provide a `TaskStore` implementation that persists task metadata and results.
+- Enable the `tasks` capability when constructing the server.
+- Register tools with `server.experimental.tasks.registerToolTask(...)`.
+
+For a runnable example that uses the in-memory store shipped with the SDK, see:
+
+- [`toolWithSampleServer.ts`](../src/examples/server/toolWithSampleServer.ts)
+- `src/experimental/tasks/stores/in-memory.ts`
+
+### Client-side usage
+
+On the client, you use:
+
+- `client.experimental.tasks.callToolStream(...)` to start a tool call that may create a task and emit status updates over time.
+- `client.getTask(...)` and `client.getTaskResult(...)` to check status and fetch results after reconnecting.
+
+The interactive client in:
+
+- [`simpleStreamableHttp.ts`](../src/examples/client/simpleStreamableHttp.ts)
+
+includes commands to demonstrate calling tools that support tasks and handling their lifecycle.
+
+See the MCP spec’s tasks section and the example server/client above for a full walkthrough of the task status lifecycle and TTL handling.

docs/capabilities.md

@@ -8,11 +8,11 @@ The SDK provides a high-level `Client` class that connects to MCP servers over d
 
 Runnable client examples live under:
 
-- `src/examples/client/simpleStreamableHttp.ts`
-- `src/examples/client/streamableHttpWithSseFallbackClient.ts`
-- `src/examples/client/ssePollingClient.ts`
-- `src/examples/client/multipleClientsParallel.ts`
-- `src/examples/client/parallelToolCallsClient.ts`
+- [`simpleStreamableHttp.ts`](../src/examples/client/simpleStreamableHttp.ts)
+- [`streamableHttpWithSseFallbackClient.ts`](../src/examples/client/streamableHttpWithSseFallbackClient.ts)
+- [`ssePollingClient.ts`](../src/examples/client/ssePollingClient.ts)
+- [`multipleClientsParallel.ts`](../src/examples/client/multipleClientsParallel.ts)
+- [`parallelToolCallsClient.ts`](../src/examples/client/parallelToolCallsClient.ts)
 
 ## Connecting and basic operations
 
@@ -25,7 +25,7 @@ A typical flow:
     - `listPrompts`, `getPrompt`
     - `listResources`, `readResource`
 
-See `src/examples/client/simpleStreamableHttp.ts` for an interactive CLI client that exercises these methods and shows how to handle notifications, elicitation and tasks.
+See [`simpleStreamableHttp.ts`](../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
 
@@ -36,7 +36,7 @@ To support both modern Streamable HTTP and legacy SSE servers, use a client that
 
 Runnable example:
 
-- `src/examples/client/streamableHttpWithSseFallbackClient.ts`
+- [`streamableHttpWithSseFallbackClient.ts`](../src/examples/client/streamableHttpWithSseFallbackClient.ts)
 
 ## OAuth client authentication helpers
 
@@ -48,10 +48,10 @@ For OAuth-secured MCP servers, the client `auth` module exposes:
 
 Examples:
 
-- `src/examples/client/simpleOAuthClient.ts`
-- `src/examples/client/simpleOAuthClientProvider.ts`
-- `src/examples/client/simpleClientCredentials.ts`
-- Server-side auth demo: `src/examples/server/demoInMemoryOAuthProvider.ts`
+- [`simpleOAuthClient.ts`](../src/examples/client/simpleOAuthClient.ts)
+- [`simpleOAuthClientProvider.ts`](../src/examples/client/simpleOAuthClientProvider.ts)
+- [`simpleClientCredentials.ts`](../src/examples/client/simpleClientCredentials.ts)
+- Server-side auth demo: [`demoInMemoryOAuthProvider.ts`](../src/examples/server/demoInMemoryOAuthProvider.ts)
 
 These examples show how to:
 

docs/client.md

@@ -8,11 +8,11 @@ This SDK lets you build MCP servers in TypeScript and connect them to different
 
 For a complete, runnable example server, see:
 
-- `src/examples/server/simpleStreamableHttp.ts` – feature‑rich Streamable HTTP server
-- `src/examples/server/jsonResponseStreamableHttp.ts` – Streamable HTTP with JSON response mode
-- `src/examples/server/simpleStatelessStreamableHttp.ts` – stateless Streamable HTTP server
-- `src/examples/server/simpleSseServer.ts` – deprecated HTTP+SSE transport
-- `src/examples/server/sseAndStreamableHttpCompatibleServer.ts` – backwards‑compatible server for old and new clients
+- [`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
 
 ## Transports
 
@@ -27,9 +27,9 @@ Streamable HTTP is the modern, fully featured transport. It supports:
 
 Key examples:
 
-- `src/examples/server/simpleStreamableHttp.ts` – sessions, logging, tasks, elicitation, auth hooks
-- `src/examples/server/jsonResponseStreamableHttp.ts` – `enableJsonResponse: true`, no SSE
-- `src/examples/server/standaloneSseWithGetStreamableHttp.ts` – notifications with Streamable HTTP GET + SSE
+- [`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
 
 See the MCP spec for full transport details:  
 `https://modelcontextprotocol.io/specification/2025-03-26/basic/transports`
@@ -43,46 +43,156 @@ Streamable HTTP can run:
 
 Examples:
 
-- Stateless Streamable HTTP: `src/examples/server/simpleStatelessStreamableHttp.ts`
-- Stateful with resumability: `src/examples/server/simpleStreamableHttp.ts`
+- Stateless Streamable HTTP: [`simpleStatelessStreamableHttp.ts`](../src/examples/server/simpleStatelessStreamableHttp.ts)
+- Stateful with resumability: [`simpleStreamableHttp.ts`](../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: `src/examples/server/simpleSseServer.ts`
+- Legacy SSE server: [`simpleSseServer.ts`](../src/examples/server/simpleSseServer.ts)
 - Backwards‑compatible server (Streamable HTTP + SSE):  
-  `src/examples/server/sseAndStreamableHttpCompatibleServer.ts`
+  [`sseAndStreamableHttpCompatibleServer.ts`](../src/examples/server/sseAndStreamableHttpCompatibleServer.ts)
 
 ## Running your server
 
 For a minimal “getting started” experience:
 
-1. Start from `src/examples/server/simpleStreamableHttp.ts`.
+1. Start from [`simpleStreamableHttp.ts`](../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.
 
 For more detailed patterns (stateless vs stateful, JSON response mode, CORS, DNS rebind protection), see the examples above and the MCP spec sections on transports.
 
+## Tools, resources, and prompts
+
+### Tools
+
+Tools let MCP clients ask your server to take actions. They are usually the main way that LLMs call into your application.
+
+A typical registration with `registerTool` looks like this:
+
+```typescript
+server.registerTool(
+    'calculate-bmi',
+    {
+        title: 'BMI Calculator',
+        description: 'Calculate Body Mass Index',
+        inputSchema: {
+            weightKg: z.number(),
+            heightM: z.number()
+        },
+        outputSchema: { bmi: z.number() }
+    },
+    async ({ weightKg, heightM }) => {
+        const output = { bmi: weightKg / (heightM * heightM) };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(output) }],
+            structuredContent: output
+        };
+    }
+);
+```
+
+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)
+
+#### ResourceLink outputs
+
+Tools can return `resource_link` content items to reference large resources without embedding them directly, allowing clients to fetch only what they need.
+
+The README’s `list-files` example shows the pattern conceptually; for concrete usage, see the Streamable HTTP examples in `src/examples/server`.
+
+### Resources
+
+Resources expose data to clients, but should not perform heavy computation or side‑effects. They are ideal for configuration, documents, or other reference data.
+
+Conceptually, you might register resources like:
+
+```typescript
+server.registerResource(
+    'config',
+    'config://app',
+    {
+        title: 'Application Config',
+        description: 'Application configuration data',
+        mimeType: 'text/plain'
+    },
+    async uri => ({
+        contents: [{ uri: uri.href, text: 'App configuration here' }]
+    })
+);
+```
+
+Dynamic resources use `ResourceTemplate` and can support completions on path parameters. For full runnable examples of resources:
+
+- [`simpleStreamableHttp.ts`](../src/examples/server/simpleStreamableHttp.ts)
+
+### Prompts
+
+Prompts are reusable templates that help humans (or client UIs) talk to models in a consistent way. They are declared on the server and listed through MCP.
+
+A minimal prompt:
+
+```typescript
+server.registerPrompt(
+    'review-code',
+    {
+        title: 'Code Review',
+        description: 'Review code for best practices and potential issues',
+        argsSchema: { code: z.string() }
+    },
+    ({ code }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Please review this code:\n\n${code}`
+                }
+            }
+        ]
+    })
+);
+```
+
+For prompts integrated into a full server, see:
+
+- [`simpleStreamableHttp.ts`](../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.
+
+### Display names and metadata
+
+Tools, resources and prompts support a `title` field for human‑readable names. Older APIs can also attach `annotations.title`. To compute the correct display name on the client, use:
+
+- `getDisplayName` from `@modelcontextprotocol/sdk/shared/metadataUtils.js`
+
 ## Multi‑node deployment patterns
 
-The SDK supports multi‑node deployments using Streamable HTTP. The high‑level patterns are documented in `src/examples/README.md`:
+The SDK supports multi‑node deployments using Streamable HTTP. The high‑level patterns are documented in [`README.md`](../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 `src/examples/README.md` so the examples and documentation stay aligned.
+Those deployment diagrams are kept in [`README.md`](../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:
-    - `src/examples/server/sseAndStreamableHttpCompatibleServer.ts`
+    - [`sseAndStreamableHttpCompatibleServer.ts`](../src/examples/server/sseAndStreamableHttpCompatibleServer.ts)
 - Use a client that falls back from Streamable HTTP to SSE:
-    - `src/examples/client/streamableHttpWithSseFallbackClient.ts`
+    - [`streamableHttpWithSseFallbackClient.ts`](../src/examples/client/streamableHttpWithSseFallbackClient.ts)
 
 For the detailed protocol rules, see the “Backwards compatibility” section of the MCP spec.