@procedures/mcp-server 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @procedures/mcp-server
 
+## 0.8.1
+
+### Patch Changes
+
+- 2523b1b: One MCP host factory, `createMcpHost()`, and the questions of a procedure to the person at the caller (CLI-10, CLI-12). PATCH: new exports and new optional options before 1.0.0. The old exports and their behavior stay.
+  
+  - `@procedures/mcp-server`: `createMcpHost(options)` builds the registry (or the modules), the tool surface, the read-only narrowing, the host policy, the `ProcedureServer` and one `McpServerTransport` for each face (stdio, Streamable HTTP, SDK transports). The stdio face stops the host when its input ends, and `host.closed` resolves. `mcp.serve` and the dev-tools server use the factory. Thus `mcp.serve` gets its options from `hostPolicy()`, and it takes `readOnly` and `instructions`.
+  - `@procedures/client`: `ctx.elicit` asks the person at the caller for input or a confirmation. The helpers `elicitInput()` and `elicitConfirmation()` give the action `unavailable` with a reason when no one can answer. `elicitWithPolicy()` adds the consents of the operator (`operatorConsent`), and `ask: false` turns the questions off. The operator answers only when the face cannot ask. A failed question of a face that can ask (a timeout, a lost connection) gives `unavailable`, and an abort gives `cancel`. `ServerRequest` and `InvokeOptions` get `elicit` and `progress`.
+  - `@procedures/client`: `ctx.progress` tells the caller the progress of the call of the host. `metadata.untrusted` declares the output fields with text from outside the host, and `metadata.title` gives the title of a tool. `metadata.toolHints` can make a tool look more dangerous than its effects (`readOnlyHint: false`, `idempotentHint: false`, `destructiveHint: true`, `openWorldHint: true`). The registry refuses each other value, and `toolHintsOf()` gives the hints with the override.
+  - `@procedures/mcp-server`: `McpServerTransport` answers `ctx.elicit` with MCP elicitation (form and URL), over stdio and Streamable HTTP. It sends `ctx.progress` as `notifications/progress`, and it gives the instructions of the server. An untrusted field goes in envelopes with a random id, and its text cannot close its envelope. The option `content` can give other text blocks for a result. The option `json: "compact"` gives the JSON of the default blocks on one line. The option `toolName` gives the name of each tool, so a server that moves to the host keeps its tool names. A call finds its procedure by the tool, not by the decoded name. Each tool call over Streamable HTTP carries the credentials of its HTTP request, so the request hook `principalOf` and the token check of the server apply to it. A server that reads cookies gets the CSRF rule on this face too.
+  - `@procedures/mcp`: a tool gets `title` from `metadata.title`. In the output schema, each untrusted field is a string.
+  - `@procedures/mcp-dev-tools`: `createDevToolsHost()` gives the MCP host as `mcp`. `dist/server.js` ends its process when the client closes the input of stdio. The tool list stays the same.
+- Updated dependencies [2d3f235]
+- Updated dependencies [1aa9ef7]
+- Updated dependencies [2523b1b]
+- Updated dependencies [c559b00]
+  - @procedures/client@0.8.1
+  - @procedures/mcp@0.8.1
+
+## 0.8.0
+
+### Patch Changes
+
+- Updated dependencies [4b09a03]
+- Updated dependencies [4b09a03]
+- Updated dependencies [aa6e3aa]
+- Updated dependencies [698e24d]
+- Updated dependencies [4b09a03]
+- Updated dependencies [600c497]
+- Updated dependencies [7c2e7f7]
+- Updated dependencies [90ea741]
+- Updated dependencies [c4cfa34]
+- Updated dependencies [d25805a]
+  - @procedures/client@0.8.0
+  - @procedures/mcp@0.8.0
+
 ## 0.7.0
 
 ### Patch Changes

package/README.md

@@ -2,365 +2,284 @@
 
 [![npm](https://img.shields.io/npm/v/@procedures/mcp-server?color=2346c4&label=npm)](https://www.npmjs.com/package/@procedures/mcp-server)
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green.svg)](https://nodejs.org/)
-[![MCP](https://img.shields.io/badge/MCP-Protocol-purple.svg)](https://modelcontextprotocol.io/)
+`@procedures/mcp-server` serves typed procedures as MCP tools to Claude and to other MCP clients. Its folder in the monorepo is `packages/client-mcp`.
 
-> MCP server transport for the procedure system. Exposes procedures as MCP tools for Claude integration.
+- `createMcpHost()` builds a complete MCP host from a registry, a tool surface and a host policy.
+- `McpServerTransport` is the MCP face of a `ProcedureServer`. The host uses it for each face.
+- A procedure can ask the person at the caller for input or a confirmation (MCP elicitation).
+- A procedure can tell the caller the progress of a long call. The caller can cancel a call.
+- A procedure can declare the fields of its output that hold text from outside the host. The host shows that text in envelopes.
 
-## Table of Contents
+## Contents
 
-- [Overview](#overview)
-- [Installation](#installation)
-- [Architecture](#architecture)
-- [Quick Start](#quick-start)
-- [API Reference](#api-reference)
-- [Tool Filtering](#tool-filtering)
-- [Claude Desktop Setup](#claude-desktop-setup)
-- [Integration](#integration)
-- [Requirements](#requirements)
-- [License](#license)
+- [Install](#install)
+- [Start a host](#start-a-host)
+- [The faces](#the-faces)
+- [Questions to the person](#questions-to-the-person)
+- [Progress and cancel](#progress-and-cancel)
+- [Text from outside the host](#text-from-outside-the-host)
+- [The result of a tool](#the-result-of-a-tool)
+- [The transport](#the-transport)
+- [The procedures of this package](#the-procedures-of-this-package)
+- [Set up Claude](#set-up-claude)
 
----
-
-## Overview
-
-**client-mcp** bridges the procedure system with MCP (Model Context Protocol):
-
-- **Transport Layer** - Connects `ProcedureServer` to Claude via stdio
-- **Dynamic Registration** - Automatically refreshes tools when procedures change
-- **Tool Filtering** - Control which procedures are exposed as MCP tools
-- **Debug Mode** - Logging for troubleshooting MCP connections
-
----
-
-## Installation
+## Install
 
 ```bash
-npm install @procedures/mcp-server
+npm install @procedures/mcp-server @procedures/client
 ```
 
----
-
-## Architecture
-
-### System Overview
-
-```mermaid
-graph TB
-    subgraph "Claude Layer"
-        Claude[Claude Desktop / Code]
-    end
-
-    subgraph "MCP Protocol"
-        ListTools[ListToolsRequest]
-        CallTool[CallToolRequest]
-    end
-
-    subgraph "client-mcp"
-        Transport[McpServerTransport]
-        ToolMap[Tool Mapper]
-    end
-
-    subgraph "Procedure Layer"
-        Server[ProcedureServer]
-        Registry[PROCEDURE_REGISTRY]
-    end
-
-    subgraph "Procedures"
-        FS[fs.read]
-        Git[git.commit]
-        Shell[shell.run]
-        More[...]
-    end
-
-    Claude -->|stdio| ListTools
-    Claude -->|stdio| CallTool
-    ListTools --> Transport
-    CallTool --> Transport
-    Transport --> ToolMap
-    ToolMap --> Registry
-    Transport --> Server
-    Server --> FS
-    Server --> Git
-    Server --> Shell
-    Server --> More
-```
+The package needs Node.js 22 or later.
 
-### Request Flow
-
-```mermaid
-sequenceDiagram
-    participant Claude as Claude
-    participant MCP as McpServerTransport
-    participant Server as ProcedureServer
-    participant Registry as PROCEDURE_REGISTRY
-    participant Handler as Procedure Handler
-
-    Note over Claude,Handler: Tool Discovery
-    Claude->>MCP: ListToolsRequest
-    MCP->>Registry: getAll()
-    Registry-->>MCP: Procedure[]
-    MCP->>MCP: Convert to MCP tools
-    MCP-->>Claude: ListToolsResponse (tools[])
-
-    Note over Claude,Handler: Tool Execution
-    Claude->>MCP: CallToolRequest (fs.read)
-    MCP->>Server: handle({ path: ["fs", "read"], input })
-    Server->>Registry: get(["fs", "read"])
-    Registry-->>Server: Procedure
-    Server->>Handler: handler(input, ctx)
-    Handler-->>Server: Result
-    Server-->>MCP: Response
-    MCP-->>Claude: CallToolResponse
-```
+## Start a host
 
-### Transport Architecture
-
-```mermaid
-graph LR
-    subgraph "McpServerTransport"
-        Init[Initialize]
-        Connect[Connect stdio]
-        Register[Register handlers]
-    end
-
-    subgraph "MCP Handlers"
-        ListTools[tools/list]
-        CallTool[tools/call]
-    end
-
-    subgraph "Procedure System"
-        Server[ProcedureServer]
-        Convert[proceduresToMcpTools]
-    end
-
-    Init --> Connect
-    Connect --> Register
-    Register --> ListTools
-    Register --> CallTool
-    ListTools --> Convert
-    CallTool --> Server
+`createMcpHost()` builds the registry, the expose rule, the host policy, the `ProcedureServer` and a transport for each face. It starts nothing: `start()` starts the faces.
+
+```typescript
+import { createRegistry } from "@procedures/client";
+import { createMcpHost } from "@procedures/mcp-server";
+
+const host = createMcpHost({
+  registry: createRegistry(graphModule),
+  surface: { namespaces: ["graph"] },
+  readOnly: process.argv.includes("--read-only"),
+  name: "graph",
+  version: "0.1.0",
+});
+await host.start();
+console.error(`${host.tools().length} tools over stdio`);
 ```
 
----
+The options:
 
-## Quick Start
+| Option | Default | Function |
+|---|---|---|
+| `registry` | the global registry | The procedures of the host. |
+| `modules` | none | Modules of procedures. Without `registry`, the host makes a registry of them. With `registry`, the host registers them in it. |
+| `surface` | each procedure | The tools: a surface (`{ namespaces, exclude }`), keys and patterns (`["git.status", "fs.*"]`), or a function of the path. A list of keys gives a subset of tools. |
+| `exclude` | none | Keys that are not tools, also when the surface matches them. |
+| `readOnly` | `false` | With `true`, the tools are only the procedures that change nothing. Each call has that capability. |
+| `policy` | strict calls | More of the host policy (`hostPolicy()` of `@procedures/client`): `strictCalls`, `timeout`, `interceptors`, `capability`, `resources`, `token`, `browser`. Refer to [Strict calls](#strict-calls). |
+| `interceptors` | none | Interceptors after `policy.interceptors`. A function gets the registry and the expose rule of the host. |
+| `serverOptions` | none | The options of `ProcedureServer` that the policy does not give: `autoRegister`, `collections`, `idempotency`. |
+| `name`, `version` | `procedure-server`, `1.0.0` | The server info in the MCP handshake. |
+| `instructions` | none | The instructions of the server. The MCP client gives them to the model. |
+| `faces` | `{ stdio: true }` | The faces of the host. Refer to [The faces](#the-faces). |
+| `elicitation` | ask the person | The rules of the questions to the person. Refer to [Questions to the person](#questions-to-the-person). |
+| `untrusted` | tag `untrusted-content` | The envelopes of text from outside the host. |
+| `content` | none | A hook that gives other text blocks for a result. |
+| `json` | `pretty` | The JSON of the default text blocks: `pretty` (an indent of 2 spaces) or `compact` (one line, fewer tokens). |
+| `toolFilter` | none | More filters of the tools: tags and internal procedures. |
+| `toolName` | `git.status` | The name of the tool of a procedure, a function of the path. `(path) => path.join("_")` gives `git_status`. A server that moves to the host keeps its tool names. |
+| `streamLimits` | 100 items, 30 seconds | The limits of a stream that can continue without an end. |
+| `debug` | `false` | With `true`, the host writes debug lines to stderr. |
 
-```typescript
-import { ProcedureServer, PROCEDURE_REGISTRY } from "@procedures/client";
-import { McpServerTransport } from "@procedures/mcp-server";
+The host has these parts:
 
-// Load procedures (via side-effect imports)
-import "@procedures/bundle-dev/register"; // registers its procedures
+| Part | Function |
+|---|---|
+| `registry`, `policy`, `server` | The registry, the `HostPolicy` and the `ProcedureServer` of the host. |
+| `expose` | The expose rule: the procedures that are tools. |
+| `transports` | One `McpServerTransport` for each face. |
+| `start()`, `stop()` | These functions start and stop the faces. The calls in flight get the grace time. A host stops one time. |
+| `closed` | A promise. It resolves when the host stopped. |
+| `tools()`, `state()` | The tools of the host at this time, and the state of each face. |
 
-// Create procedure server
-const server = new ProcedureServer({
-  autoRegister: true,
-  registry: PROCEDURE_REGISTRY,
-});
+The host does not build the options of `ProcedureServer` by hand. `hostPolicy()` and `procedureServerOptions()` of `@procedures/client` give them. The dev-tools server (`mark mcp`) and `mcp.serve` use `createMcpHost()` too.
 
-// Create MCP transport
-const mcp = new McpServerTransport(server, {
-  transport: "stdio",
-  serverInfo: { name: "my-server", version: "1.0.0" },
-});
+### Strict calls
 
-// Add transport and start
-server.addTransport(mcp);
-await server.start();
-```
+Strict calls are the safe default of an MCP host. A procedure of code without `metadata.calls` can use only the tools of the host in its nested calls. Thus a tool cannot reach a procedure that the host does not expose. A procedure with `metadata.calls` can also use the procedures that it declares.
 
----
+To turn strict calls off, give `policy: { strictCalls: false }`. Turn them off only for a host whose tools you trust with each procedure of the registry.
 
-## API Reference
+## The faces
 
-### McpServerTransport
+Each face is one `McpServerTransport` on the server of the host. A host can have more than one face.
 
-Main transport class for MCP integration.
+| Face | Function |
+|---|---|
+| `stdio: true` | The standard input and output. Over stdio, `console.log` writes to stderr from `start()` on, because stdout carries the protocol. |
+| `stdio: { stdin, stdout, stopOnEnd, redirectConsole }` | Other streams, for a test or an embedding. With `stopOnEnd: true` (the default), the host stops when the input ends. |
+| `http: { port, host, path, token, allowedOrigins }` | Streamable HTTP. The host listens on `127.0.0.1` by default. Without a token, the face takes the token of the policy. |
+| `sdk` | One or more MCP SDK transports, for example the `InMemoryTransport` of a test. |
 
-```typescript
-interface McpServerTransportOptions {
-  transport: "stdio" | "sse";      // Transport type
-  serverInfo: {
-    name: string;                   // Server name
-    version: string;                // Server version
-  };
-  filter?: McpToolFilter;           // Tool filtering options
-  debug?: boolean;                  // Enable debug logging
-}
+When the client closes the input of stdio, the host stops, and `closed` resolves. The entry `dist/server.js` of `@procedures/mcp-dev-tools` then ends its process.
 
-class McpServerTransport {
-  constructor(server: ProcedureServer, options: McpServerTransportOptions);
+Each tool call over Streamable HTTP carries the credentials of its HTTP request: the bearer token, the cookies, the headers and the query. Thus the request hook of the policy (`principalOf`) and the token check of the server apply to each call. When the server reads cookies, the face trusts a request with a cookie only from a named origin (CSRF). A call over stdio comes from this process and has no credentials.
 
-  // Get current transport state
-  getState(): {
-    connected: boolean;
-    toolCount: number;
-    lastRefresh: Date;
-  };
+## Questions to the person
 
-  // Close the transport
-  close(): Promise<void>;
-}
+A procedure can ask the person at the caller for input or a confirmation during a call. MCP elicitation is one face that answers. The shape is not specific to MCP: another face (a terminal) can answer the same questions.
+
+```typescript
+import { elicitConfirmation } from "@procedures/client";
+
+handler: async (input, ctx) => {
+  const answer = await elicitConfirmation(ctx, `Did you give the URL ${input.url} yourself?`, {
+    consent: "user-provided",
+  });
+  if (!answer.confirmed) return { released: false, note: answer.reason ?? "The person said no." };
+  return { released: true, by: answer.by };
+};
 ```
 
-### Built-in Procedures
+The parts in `@procedures/client`:
 
-| Path | Description |
-|------|-------------|
-| `mcp.serve` | Start MCP server programmatically |
-| `mcp.list-tools` | List available MCP tools with filtering |
+- `ctx.elicit` is the function of the face. It is absent when no one can answer. Its `modes` tells which kinds of question the face can ask: `form`, `url`.
+- `elicitInput(ctx, request)` asks a question with a form of fields. The fields are the primitive fields of MCP: text, number, yes or no, and choices.
+- `elicitConfirmation(ctx, question)` asks a question of yes or no. `confirmed` is true only for an accepted yes.
+- The procedures that a procedure starts ask the same person.
 
----
+Each answer has an `action`:
 
-## Tool Filtering
+| Action | Meaning |
+|---|---|
+| `accept` | The person, or the consent of the operator, gave the answer. `by` tells who: `person` or `operator`. |
+| `decline` | The person said no. |
+| `cancel` | The person closed the question without a choice, or the call aborted. |
+| `unavailable` | No one can answer. `reason` tells why. The helpers do not throw for this case. |
 
-Control which procedures are exposed as MCP tools:
+The operator can give a consent when the server starts. Thus a server refuses input from the user without a consent of the operator. The host option `elicitation` has the rules:
 
-```typescript
-interface McpToolFilter {
-  includeTags?: string[];      // Only include these tags
-  excludeTags?: string[];      // Exclude these tags
-  excludeInternal?: boolean;   // Exclude internal procedures
-  pathPrefix?: string[];       // Only include procedures with this prefix
-}
+| Option | Default | Function |
+|---|---|---|
+| `ask` | `true` | With `false`, the face does not ask the person, also when the client can. |
+| `operatorConsent` | none | `true` for each question with a consent key, or a list of consent keys. |
+| `timeout` | 5 minutes | The time that the face waits for the answer of the person. |
 
-const mcp = new McpServerTransport(server, {
-  transport: "stdio",
-  filter: {
-    includeTags: ["public"],
-    excludeInternal: true,
-    pathPrefix: ["api"],
-  },
+```typescript
+const allow = process.argv.includes("--allow-user-provided") || process.env.POLITE_CRAWLER_ALLOW_USER_PROVIDED === "1";
+const host = createMcpHost({
+  registry,
+  elicitation: { operatorConsent: allow ? ["user-provided"] : [] },
 });
 ```
 
-### Filtering Examples
-
-```mermaid
-graph TB
-    subgraph "All Procedures"
-        FS[fs.read]
-        Git[git.commit]
-        Internal[_internal.debug]
-        API[api.users.list]
-    end
-
-    subgraph "Filter: excludeInternal"
-        F1[fs.read]
-        F2[git.commit]
-        F3[api.users.list]
-    end
-
-    subgraph "Filter: pathPrefix api"
-        F4[api.users.list]
-    end
-
-    FS --> F1
-    Git --> F2
-    API --> F3
-    API --> F4
-```
-
----
+The order of the answers:
 
-## Claude Desktop Setup
+1. When the client can ask (it declares elicitation), the face asks the person. A decline of the person stays a decline.
+2. When the question of the face fails (a timeout, a lost connection), the answer is `unavailable`. The operator does not answer: the person can see the question, and silence is not a consent.
+3. When the client cannot ask, the consent of the operator answers. The operator answers only a form question with a consent key that the operator gave.
+4. Else the answer is `unavailable`, with a reason.
 
-### Configuration File Locations
+Over Streamable HTTP, each question goes on the stream of its tool call.
 
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+## Progress and cancel
 
-### Basic Configuration
+A procedure tells the caller the progress of a long call with `ctx.progress`:
 
-```json
-{
-  "mcpServers": {
-    "my-server": {
-      "command": "npx",
-      "args": ["-y", "@procedures/mcp-dev-tools"]
-    }
+```typescript
+handler: async (input, ctx) => {
+  for (const [index, url] of input.urls.entries()) {
+    await fetchPage(url, ctx.signal);
+    await ctx.progress?.({ progress: index + 1, total: input.urls.length, message: url });
   }
-}
+  return { done: input.urls.length };
+};
 ```
 
-### With Custom Bundle
+- `ctx.progress` is present only when the client sent a progress token. Each update becomes a `notifications/progress` message.
+- Only the call of the host gets `ctx.progress`, not its nested calls. Thus the values of one call stay in order.
+- The function does not reject. A client that is gone does not stop the call.
+- A stream does not need it: the face gives each item of a stream as progress. When the procedure of a stream uses `ctx.progress`, the face gives only those updates.
+- When the client cancels a call (`notifications/cancelled`), `ctx.signal` of the procedure aborts.
 
-```json
-{
-  "mcpServers": {
-    "dev-tools": {
-      "command": "node",
-      "args": ["C:/Users/me/git/client/packages/impl-mcp-dev/dist/server.js"],
-      "env": {
-        "MCP_BUNDLES": "@procedures/bundle-mcp",
-        "MCP_DEBUG": "true"
-      }
-    }
-  }
-}
+## Text from outside the host
+
+A procedure that gives text from outside the host (a web page, a mail) declares the fields of its output that hold it. Then a model gets that text apart from the data, as data and not as instructions.
+
+```typescript
+import { untrustedText } from "@procedures/client";
+
+createProcedure()
+  .path(["crawl", "read"])
+  .meta({ description: "Read a stored page", untrusted: ["web_content"], effects: { reads: ["store"], writes: [] } })
+  .handler(async (input) => ({
+    doc: input.doc,
+    web_content: [untrustedText(page.text, { url: page.url, capture: page.capture })],
+  }));
 ```
 
----
+- The value of an untrusted field is a text, an `UntrustedText` with its source, or a list of them.
+- The first text block of the result has the data as JSON, without the untrusted fields.
+- The second text block has a notice, then one envelope for each text: `<untrusted-content id="..." url="..." capture="...">`.
+- A random id marks the start and the end of each envelope of one answer. A text cannot hold the name of the tag, in any case and with any dash or space. Thus a text cannot close its envelope.
+- In the structured content and the output schema, each untrusted field is a string: the text of its envelopes.
+- The host option `untrusted` changes the tag (`tag: "untrusted-web-content"`) and the notice. Its `wrap` function replaces the envelopes.
+- `createUntrustedEnvelopes()` gives the same envelopes for other uses.
+
+## The result of a tool
+
+- A tool whose output schema is an object has an `outputSchema`. Each result then has `structuredContent`, and a text block for clients that do not read it.
+- The hints of a tool (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) come from the declared `effects` of its procedure.
+- `metadata.toolHints` of a procedure can make its tool look more dangerous than its effects. Refer to [Hint overrides](#hint-overrides).
+- `metadata.title` of a procedure gives the `title` of its tool.
+- A failed call gives `isError` with the code and the reason in `_meta`.
+- The host option `content` can give other text blocks for a result that is a value. It gets the tool, the value and the default content, and it gives undefined for the default.
+- The host option `json: "compact"` gives the JSON of the default blocks on one line. Use it in place of a content hook for that change only.
 
-## Integration
+### Hint overrides
 
-### Dynamic Tool Registration
+The declared effects stay the truth: the host enforces the effects, not the hints. An override can only make a tool look more dangerous:
 
-The transport automatically refreshes MCP tools when procedures are registered or unregistered:
+| Hint | The only value of an override | Meaning |
+|---|---|---|
+| `readOnlyHint` | `false` | The tool can change something. |
+| `idempotentHint` | `false` | A second call can change more. |
+| `destructiveHint` | `true` | The tool can delete or overwrite data. |
+| `openWorldHint` | `true` | The tool can reach systems outside the host. |
 
 ```typescript
-// Tools are automatically updated when procedures change
-PROCEDURE_REGISTRY.register(newProcedure);  // → MCP tools refresh
-PROCEDURE_REGISTRY.unregister(oldPath);     // → MCP tools refresh
+createProcedure()
+  .path(["notes", "read"])
+  .meta({ description: "Read a shared note", effects: { reads: ["store"], writes: [] }, toolHints: { openWorldHint: true } });
 ```
 
-### Debug Mode
+The registry refuses each other value when the procedure registers, also when the effects give the same value. The type `ToolHintOverride` refuses it before the registry does. `toolHintsOf()` of `@procedures/client` gives the hints of a tool with its override.
 
-Enable debug logging for troubleshooting:
+## The transport
+
+`McpServerTransport` is the MCP face of a `ProcedureServer`. `createMcpHost()` makes one for each face. Use it directly to add an MCP face to a server of your own:
 
 ```typescript
-const mcp = new McpServerTransport(server, {
-  transport: "stdio",
-  debug: true,  // Logs to stderr
-});
-```
+import { ProcedureServer, createRegistry } from "@procedures/client";
+import { McpServerTransport } from "@procedures/mcp-server";
 
-### With Other Packages
+const registry = createRegistry(myModule);
+const server = new ProcedureServer({ registry, autoRegister: true });
+server.addTransport(new McpServerTransport(server, { registry, transport: "stdio", serverInfo: { name: "my-server", version: "1.0.0" } }));
+await server.start();
+```
 
-```mermaid
-graph TB
-    subgraph "Implementation"
-        ImplMCP[impl-mcp-dev<br/>Ready-to-run server]
-    end
+- The tools follow the registry. When the list of tools changes, the transport sends `notifications/tools/list_changed`.
+- The options `instructions`, `stdio`, `elicitation`, `untrusted` and `content` are the same as the options of the host.
+- `toolFilter` selects the tools: `include` (a function of the path), `pathPrefix`, `includeTags`, `excludeTags` and `excludeInternal`.
+- `transport: "http"` with `httpOptions` gives Streamable HTTP. `sdkTransport` connects an MCP SDK transport.
+- `transport: "sse"` is not implemented.
 
-    subgraph "Transport"
-        ClientMCP[client-mcp<br/>McpServerTransport]
-    end
+## The procedures of this package
 
-    subgraph "Core"
-        MCP[mcp<br/>Types & utilities]
-        Client[client<br/>ProcedureServer]
-    end
+| Procedure | Function |
+|---|---|
+| `mcp.serve` | This procedure starts an MCP host over stdio with `createMcpHost()`. Without `namespaces`, the tools come from `mcpNamespaces` and `mcpExclude` of the bundles (default `@procedures/bundle-mcp`). Without a list, no procedure is a tool. |
+| `mcp.list-tools` | This procedure lists the procedures of the registry of the caller as MCP tools. |
 
-    ImplMCP --> ClientMCP
-    ClientMCP --> MCP
-    ClientMCP --> Client
-```
+`exposeRule()`, `mergeSurfaces()` and `importBundles()` give the tool surface of some bundles.
 
----
+## Set up Claude
 
-## Requirements
+`@procedures/mcp-dev-tools` is a ready MCP server with this package. Add it to the MCP configuration of Claude Code or Claude Desktop:
 
-- **Node.js** >= 22
-- **Dependencies:**
-  - `@procedures/client`
-  - `@procedures/mcp`
-  - `@modelcontextprotocol/sdk`
+```json
+{
+  "mcpServers": {
+    "dev-tools": { "command": "npx", "args": ["-y", "@procedures/mcp-dev-tools"] }
+  }
+}
+```
 
----
+The [README of mcp-dev-tools](../impl-mcp-dev/README.md) has the configuration.
 
 ## License