@ts-pf/mcp 0.0.0-stage → 0.0.0

package/dist/toolkit.d.ts

@@ -0,0 +1,36 @@
+import type { AnySchema, InferSchemaInput } from '@ts-pf/contract';
+import { type CompositeTool, type CompositeToolDef } from './composite.js';
+import { type CoverageCheck } from './coverage.js';
+import type { DollarGuard, Split } from './names.js';
+import { type AnyNode, type ToolkitNode } from './node.js';
+import type { AnyTool } from './tool.js';
+import { type Host, type HostsCheck, type HostsNames, type HostsPaths, type NameCheck, type PathsOf, type Toolset, type ToolsInput } from './toolset.js';
+export type Toolkit<T, Ctx> = ToolkitNode<T, T, Ctx, ''> & {
+    /** Type the context every mapper, inject, and binding sees. Same toolkit at runtime. */
+    $context<C>(): Toolkit<T, C>;
+    /** Group tools behind `get_<key>[_<bucket>]_capabilities` / `call_<key>[_<bucket>]_capability`. */
+    $host<const Tools extends ToolsInput<Ctx>, const Sp extends Split = 'effect'>(def: {
+        /** What the model reads before searching. */
+        description: string;
+        tools: Tools & NameCheck<Tools, never>;
+        /** `'effect'` (default): `query` (read) and `operations` (write + destructive). */
+        split?: Sp;
+    }): Host<Ctx, PathsOf<Tools>, NoInfer<Sp>>;
+    /** One MCP server's tools: flat tools (the object key is the name) plus hosts. */
+    $toolset<const Tools extends ToolsInput<Ctx> = {}, const H extends {
+        [key: string]: Host<Ctx, string, Split>;
+    } = {}>(def: {
+        tools?: Tools & NameCheck<Tools, HostsNames<H>>;
+        hosts?: H & HostsCheck<H>;
+    }): Toolset<T, Ctx, PathsOf<Tools> | HostsPaths<H>>;
+    /** A composite N→1 tool over `call`. */
+    $tool<Sch extends AnySchema>(def: CompositeToolDef<T, Ctx, Sch>): CompositeTool<Ctx, InferSchemaInput<Sch>>;
+    /** Compile error (and runtime throw) naming every procedure no toolset exposes and no `exclude` names. */
+    $coverage<const S extends readonly Toolset<T, never, string>[], const X extends readonly (AnyTool | AnyNode)[] = []>(options: {
+        toolsets: S;
+        exclude?: X;
+    } & CoverageCheck<T, S, X[number]>): void;
+};
+/** Typed tool builders mirroring `contract`. Root members start with `$`, so no contract key can collide. */
+export declare function createToolkit<T>(contract: T & DollarGuard<T>): Toolkit<T, object>;
+//# sourceMappingURL=toolkit.d.ts.map

package/dist/toolkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolkit.d.ts","sourceRoot":"","sources":["../src/toolkit.ts"],"names":[],"mappings":"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"}

package/dist/toolkit.js

@@ -0,0 +1,22 @@
+import { createCompositeTool, } from './composite.js';
+import { uncoveredPaths } from './coverage.js';
+import { createNode } from './node.js';
+import { createHost, createToolset, } from './toolset.js';
+/** Typed tool builders mirroring `contract`. Root members start with `$`, so no contract key can collide. */
+export function createToolkit(contract) {
+    const members = {
+        $context: () => toolkit,
+        $host: createHost,
+        $toolset: (def) => createToolset(contract, def),
+        $tool: createCompositeTool,
+        $coverage: (options) => {
+            const missing = uncoveredPaths(contract, options.toolsets, options.exclude ?? []);
+            if (missing.length > 0) {
+                throw new Error(`$coverage(): not exposed by any toolset nor excluded: ${missing.join(', ')}`);
+            }
+        },
+    };
+    const toolkit = createNode(contract, [], members);
+    return toolkit;
+}
+//# sourceMappingURL=toolkit.js.map

package/dist/toolkit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolkit.js","sourceRoot":"","sources":["../src/toolkit.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,mBAAmB,GACpB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAsB,cAAc,EAAE,MAAM,eAAe,CAAA;AAElE,OAAO,EAAgB,UAAU,EAAoB,MAAM,WAAW,CAAA;AAEtE,OAAO,EAEL,UAAU,EACV,aAAa,GASd,MAAM,cAAc,CAAA;AAqCrB,6GAA6G;AAC7G,MAAM,UAAU,aAAa,CAC3B,QAA4B;IAE5B,MAAM,OAAO,GAAG;QACd,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO;QACvB,KAAK,EAAE,UAAU;QACjB,QAAQ,EAAE,CAAC,GAAwC,EAAE,EAAE,CACrD,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC;QAC9B,KAAK,EAAE,mBAAmB;QAC1B,SAAS,EAAE,CAAC,OAGX,EAAE,EAAE;YACH,MAAM,OAAO,GAAG,cAAc,CAC5B,QAAQ,EACR,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,OAAO,IAAI,EAAE,CACtB,CAAA;YACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CACb,yDAAyD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC9E,CAAA;YACH,CAAC;QACH,CAAC;KACF,CAAA;IACD,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAuB,CAAA;IACvE,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/toolset.d.ts

@@ -0,0 +1,89 @@
+import type { KeysOfUnion } from './infer.js';
+import { type HostToolNames, type Split } from './names.js';
+import { type AnyTool, type ToolSpec } from './tool.js';
+export type ToolRecord<Ctx = never> = {
+    readonly [name: string]: AnyTool<Ctx>;
+};
+export type ToolsInput<Ctx = never> = ToolRecord<Ctx> | readonly ToolRecord<Ctx>[];
+type Dups<L> = L extends readonly [infer H, ...infer R] ? (keyof H & KeysOfUnion<R[number]>) | Dups<R> : never;
+type RecordsOf<Tools> = Tools extends readonly unknown[] ? Tools[number] : Tools;
+export type PathsOf<Tools> = RecordsOf<Tools> extends infer R ? R extends unknown ? R[keyof R] extends infer V ? V extends {
+    readonly '~tool': {
+        path: infer P;
+    };
+} ? P : never : never : never : never;
+type NameMsg<K, Taken> = K extends Taken ? `Tool name "${K & string}" collides with a generated host tool name` : `Duplicate tool name "${K & string}"`;
+type NameProblems<Tools, Taken extends string> = Tools extends readonly unknown[] ? Dups<Tools> | (KeysOfUnion<Tools[number]> & Taken) : keyof Tools & Taken;
+/**
+ * Marks each offending key in each record with a message literal (the
+ * `RouterImplCheck` trick). `unknown` when nothing collides, so `Tools &
+ * NameCheck` stays `Tools`: intersecting a tuple with a mapped tuple makes the
+ * checker compare array methods structurally, which costs ~1.6M instantiations
+ * on a 400-procedure `all()`.
+ */
+export type NameCheck<Tools, Taken extends string> = [
+    NameProblems<Tools, Taken>
+] extends [never] ? unknown : NameMarks<Tools, Taken>;
+type NameMarks<Tools, Taken extends string> = Tools extends readonly unknown[] ? {
+    [I in keyof Tools]: {
+        [K in keyof Tools[I] & (Dups<Tools> | Taken)]: NameMsg<K, Taken>;
+    };
+} : {
+    [K in keyof Tools & Taken]: NameMsg<K, Taken>;
+};
+/** Runtime description of a tool host; what `'~host'` holds. */
+export type HostSpec = {
+    readonly description: string;
+    readonly tools: Readonly<Record<string, ToolSpec>>;
+    readonly split: Split;
+};
+export interface Host<Ctx, Paths extends string, Sp extends Split> {
+    readonly '~host': {
+        ctx: (c: Ctx) => void;
+        paths: Paths;
+        split: Sp;
+    };
+}
+/** `never` context: any host is assignable. */
+export type AnyHost<Sp extends Split = Split> = Host<never, string, Sp>;
+export type HostsNames<H> = {
+    [K in keyof H & string]: H[K] extends AnyHost<infer Sp> ? HostToolNames<K, Sp> : never;
+}[keyof H & string];
+export type HostsPaths<H> = {
+    [K in keyof H]: H[K] extends Host<never, infer P, Split> ? P : never;
+}[keyof H];
+export type HostsCheck<H> = {
+    [K in keyof H & string]: H[K] extends AnyHost<infer Sp> ? [HostToolNames<K, Sp> & HostsNames<Omit<H, K>>] extends [never] ? unknown : {
+        '~error': `Host "${K}" generates "${HostToolNames<K, Sp> & HostsNames<Omit<H, K>>}", which another host also generates`;
+    } : unknown;
+};
+/** Runtime description of a toolset; what `'~toolset'` holds. */
+export type ToolsetSpec = {
+    readonly contract: unknown;
+    readonly tools: Readonly<Record<string, ToolSpec>>;
+    readonly hosts: Readonly<Record<string, HostSpec>>;
+};
+export interface Toolset<T, Ctx, Paths extends string> {
+    readonly '~toolset': {
+        contract: T;
+        ctx: (c: Ctx) => void;
+        paths: Paths;
+    };
+}
+/** `unknown` contract and `never` context: any toolset is assignable. */
+export type AnyToolset = Toolset<unknown, never, string>;
+export declare function hostSpec(host: AnyHost): HostSpec;
+export declare function toolsetSpec(toolset: AnyToolset): ToolsetSpec;
+/** The MCP tool names a host lists (empty buckets are not listed, but their names stay reserved). */
+export declare function hostToolNames(key: string, split: Split): string[];
+export declare function createHost(def: {
+    description: string;
+    tools: unknown;
+    split?: Split;
+}): unknown;
+export declare function createToolset(contract: unknown, def: {
+    tools?: unknown;
+    hosts?: Record<string, unknown>;
+}): unknown;
+export {};
+//# sourceMappingURL=toolset.d.ts.map

package/dist/toolset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolset.d.ts","sourceRoot":"","sources":["../src/toolset.ts"],"names":[],"mappings":"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"}

package/dist/toolset.js

@@ -0,0 +1,67 @@
+import { discoverToolName, dispatchToolName, hostScope, } from './names.js';
+import { isTool, toolSpec } from './tool.js';
+export function hostSpec(host) {
+    return host['~host'];
+}
+export function toolsetSpec(toolset) {
+    return toolset['~toolset'];
+}
+/** Flatten one record or a list of records; the object key is the tool name. */
+function collectTools(input, where) {
+    const records = (Array.isArray(input) ? input : [input ?? {}]);
+    const tools = {};
+    for (const record of records) {
+        for (const [name, tool] of Object.entries(record)) {
+            if (!isTool(tool)) {
+                throw new TypeError(`${where}: "${name}" is not a tool`);
+            }
+            if (Object.hasOwn(tools, name)) {
+                throw new Error(`${where}: duplicate tool name "${name}"`);
+            }
+            tools[name] = toolSpec(tool);
+        }
+    }
+    return tools;
+}
+/** The MCP tool names a host lists (empty buckets are not listed, but their names stay reserved). */
+export function hostToolNames(key, split) {
+    const scopes = split === 'effect'
+        ? [hostScope(key, 'query'), hostScope(key, 'operations')]
+        : [hostScope(key, undefined)];
+    return scopes.flatMap((scope) => [
+        discoverToolName(scope),
+        dispatchToolName(scope),
+    ]);
+}
+export function createHost(def) {
+    if (!def.description) {
+        throw new TypeError('$host(): description is required');
+    }
+    const spec = {
+        description: def.description,
+        tools: collectTools(def.tools, '$host()'),
+        split: def.split ?? 'effect',
+    };
+    return { '~host': spec };
+}
+export function createToolset(contract, def) {
+    const tools = collectTools(def.tools, '$toolset()');
+    const hosts = {};
+    const taken = new Map();
+    for (const name of Object.keys(tools))
+        taken.set(name, `tool "${name}"`);
+    for (const [key, host] of Object.entries(def.hosts ?? {})) {
+        const spec = hostSpec(host);
+        for (const name of hostToolNames(key, spec.split)) {
+            const owner = taken.get(name);
+            if (owner) {
+                throw new Error(`$toolset(): host "${key}" generates "${name}", which ${owner} also uses`);
+            }
+            taken.set(name, `host "${key}"`);
+        }
+        hosts[key] = spec;
+    }
+    const spec = { contract, tools, hosts };
+    return { '~toolset': spec };
+}
+//# sourceMappingURL=toolset.js.map

package/dist/toolset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolset.js","sourceRoot":"","sources":["../src/toolset.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+import type { JsonSchema } from '@ts-pf/docs';
+import type { Effect } from './meta.js';
+/** What a caller brings to `McpTools.list` / `McpTools.call`. */
+export type McpCallInfo = {
+    /** Validated token info (HTTP: from `verifyBearer` or the SDK OAuth helpers). */
+    authInfo?: {
+        token: string;
+        clientId: string;
+        scopes: string[];
+        expiresAt?: number;
+        resource?: URL;
+        resourceMetadataUrl?: string;
+        extra?: Record<string, unknown>;
+    };
+    /** The HTTP request, when there is one. Headers are never forwarded to procedures. */
+    requestInfo?: Request;
+    signal?: AbortSignal;
+    inputResponses?: Record<string, unknown>;
+    /** `modern` = MCP 2026-07-28, `legacy` = the 2025 protocol. */
+    era?: 'legacy' | 'modern';
+    /**
+     * Set by `McpTools.call` before `context` runs: the tool being called (for a
+     * host call, the inner tool). Copy it into your own context type to trace it
+     * in interceptors.
+     */
+    tool?: {
+        name: string;
+        path: string;
+    };
+};
+export type McpToolAnnotations = {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+};
+export type McpToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    /** Only when the tool declares `.output(schema, map)`; results are then checked. */
+    outputSchema?: JsonSchema;
+    annotations: McpToolAnnotations;
+    effect: Effect;
+};
+export type McpToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: true;
+};
+/** A bound toolset: list and call tools without a transport (tests, agent frameworks, `./sdk`). */
+export interface McpTools {
+    list(info?: McpCallInfo): Promise<McpToolDefinition[]>;
+    call(name: string, args: unknown, info?: McpCallInfo): Promise<McpToolResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAEvC,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG;IACxB,iFAAiF;IACjF,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAA;QACb,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,EAAE,CAAA;QAChB,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,QAAQ,CAAC,EAAE,GAAG,CAAA;QACd,mBAAmB,CAAC,EAAE,MAAM,CAAA;QAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAChC,CAAA;IACD,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IACzB;;;;OAIG;IACH,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CACtC,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,UAAU,CAAA;IACvB,oFAAoF;IACpF,YAAY,CAAC,EAAE,UAAU,CAAA;IACzB,WAAW,EAAE,kBAAkB,CAAA;IAC/B,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,OAAO,CAAC,EAAE,IAAI,CAAA;CACf,CAAA;AAED,mGAAmG;AACnG,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAA;IACtD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC9E"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@ts-pf/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Opt-in typed projection of a ts-pf contract into MCP tools",
+  "keywords": [
+    "ts-pf",
+    "typescript",
+    "rpc",
+    "typesafe",
+    "typed-rpc",
+    "api",
+    "contract-first",
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "ai",
+    "tools"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crobinson42/ts-pf.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/crobinson42/ts-pf/tree/main/packages/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/crobinson42/ts-pf/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./meta": {
+      "types": "./dist/meta.d.ts",
+      "import": "./dist/meta.js"
+    },
+    "./sdk": {
+      "types": "./dist/sdk.d.ts",
+      "import": "./dist/sdk.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "biome check src tests bench/gen.mjs",
+    "bench:types": "node bench/gen.mjs"
+  },
+  "dependencies": {
+    "@ts-pf/contract": "0.2.0",
+    "@ts-pf/docs": "0.1.7",
+    "@ts-pf/protocol": "0.2.0",
+    "@ts-pf/server": "0.4.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/server": ">=2.4.0 <3"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/server": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.4.0",
+    "@modelcontextprotocol/server": "^2.4.0",
+    "@ts-pf/client": "0.2.0",
+    "zod": "^4.0.0"
+  }
+}

package/skills/ts-pf-mcp/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: ts-pf-mcp
+description: Use when exposing a ts-pf contract as MCP tools for LLM clients — one-call serving, shaping tools for the model, toolsets, tool hosts, coverage, or serving over HTTP / stdio with the MCP SDK v2. Triggers: @ts-pf/mcp, MCP, Model Context Protocol, createToolkit, createMcpFactory, bindTools, all(), $toolset, $host, $coverage, mcp({ effect }), audit().
+---
+
+# @ts-pf/mcp
+
+A typed projection of a ts-pf contract into MCP tools. The contract defines the tools; an executor (`{ app, context }` in-process through `runProcedure`, or `{ client }`) runs them; `@modelcontextprotocol/server` v2 serves them.
+
+Install: `npm i @ts-pf/mcp @modelcontextprotocol/server` (peer **>=2.4.0 <3**, needed for `./sdk` only). The app already has `@ts-pf/contract` and `@ts-pf/server`; add `@ts-pf/docs` to import `docs()` in contract files.
+
+Link for agents: `npx skills experimental_sync -y`
+
+## Do
+
+Small contract: one call. Every procedure is a tool named by path with `_` (`planet.find` → `planet_find`); `docs({ hidden: true })` is skipped. `context` is typed from the app's `$context<C>()` and required for a branded app.
+
+```ts
+import { createMcpFactory } from '@ts-pf/mcp/sdk'
+
+export const factory = createMcpFactory(app, { name: 'planets', version: '1.0.0' })
+```
+
+Classify and describe in the contract. Contract files import only `@ts-pf/mcp/meta` (no dependencies). Unclassified = `write`.
+
+```ts
+import { procedure } from '@ts-pf/contract'
+import { docs } from '@ts-pf/docs'
+import { mcp } from '@ts-pf/mcp/meta'
+import { z } from 'zod'
+
+export const find = procedure
+  .input(z.object({ id: z.number() }))
+  .meta({ ...docs({ description: 'Find a planet by id' }), ...mcp({ effect: 'read' }) })
+```
+
+Shape for the model with the toolkit; split into toolsets; enforce coverage; bind; serve.
+
+```ts
+import { all, bindTools, createToolkit } from '@ts-pf/mcp'
+import { createMcpFactory } from '@ts-pf/mcp/sdk'
+import { contract } from './contract.js'
+
+const tk = createToolkit(contract) // .$context<AppCtx>() to type context in inject / mappers
+
+const findPlanet = tk.planet.find
+  .describe('Get one planet by id. Call planet_list first if you only have a name.')
+  .errors({ NOT_FOUND: ({ data }) => `No planet ${data.id}. Call planet_list for ids.` })
+
+export const planetsMcp = tk.$toolset({
+  tools: [all(tk.planet, { exclude: [tk.planet.find] }), { planet_find: findPlanet }],
+})
+tk.$coverage({ toolsets: [planetsMcp] })
+
+export const tools = bindTools(planetsMcp, { app, context: () => ({ db }) })
+export const factory = createMcpFactory(tools, { name: 'planets', version: '1.0.0' })
+```
+
+- In a toolset the object key is the tool name. Duplicates and collisions with generated host names are type errors naming the key.
+- `.inject({ tenantId: ({ context }) => context.tenantId })` removes the key from the model's schema and fills it per call (also forced safe defaults: `.inject({ includePii: () => false })`). Injected values win over anything the model sends. `all(node, { inject })` applies a key only where the input has it; a typo or a conflicting field type is a compile error naming the path.
+- `.input(schema, map)` replaces the model input; it is exclusive with `.inject` (inject inside the map).
+- `.output(map)` reshapes; `.output(schema, map)` also advertises `outputSchema`, returns `structuredContent`, and checks the result (a mismatch is `INTERNAL`). Mapper `call` is a typed client on the same executor, for joins. Literal unions in a mapper return need `as const`.
+- `.errors({ CODE: ({ data }) => 'next step' })` for declared codes only. `VALIDATION` returns the issues plus the model-facing schema. Unknown throws are `INTERNAL: Internal server error` (via `toWireError`) and logged with `console.error` unless `onError` is set.
+- More than about 15 tools in a group: `tk.$host({ description, tools: all(tk.admin) })`. `split: 'effect'` (default) gives `get_admin_query_capabilities` / `call_admin_query_capability` (read) and `get_admin_operations_capabilities` / `call_admin_operations_capability` (write + destructive); `split: false` gives `get_admin_capabilities` / `call_admin_capability`. Pin hot tools flat beside the host. Whole-server discovery is one host over `all(tk)`.
+- `tk.$coverage({ toolsets, exclude })` is a compile error (and a runtime throw) naming every procedure no toolset exposes and no `exclude` names. Hosts count; `$tool` composites do not; `docs({ hidden: true })` counts as decided at runtime.
+- `audit(toolsets)` in CI: missing descriptions (error), unclassified tools, schema roots (unions, recursion, non-object), more than 15 tools, names over 60 characters.
+- Identity comes from `info.authInfo` (HTTP: your verified token passed to `createMcpHandler(factory).fetch(req, { authInfo })`). stdio never sets it: `serveStdio((ctx) => factory({ ...ctx, authInfo }))`, with `serveStdio` from `@modelcontextprotocol/server/stdio`. Enforce roles in procedure middleware; annotations and `docs({ hidden: true })` are hints, not security.
+- OAuth over HTTP: check the token in the SDK at the HTTP edge, so a missing or bad token is a `401` challenge and the client can start sign-in. Map claims to the app's context in `context`. A gateway calling upstream as the user uses `client: (info) => createClient(…)`. Full verifier and metadata setup: the package README, "OAuth".
+
+```ts
+import { createMcpHandler, getOAuthProtectedResourceMetadataUrl, type OAuthMetadata, type OAuthTokenVerifier, oauthMetadataResponse, requireBearerAuth } from '@modelcontextprotocol/server'
+import { createMcpFactory } from '@ts-pf/mcp/sdk'
+import { PFError } from '@ts-pf/protocol'
+
+declare const verifier: OAuthTokenVerifier // JWKS or introspection → AuthInfo (set expiresAt; bad token → OAuthError invalid_token)
+declare const oauthMetadata: OAuthMetadata // your IdP's RFC 8414 metadata
+const resourceServerUrl = new URL('https://api.example.com/mcp')
+const gate = requireBearerAuth({
+  verifier,
+  requiredScopes: ['mcp'], // optional
+  expectedResource: resourceServerUrl,
+  resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(resourceServerUrl),
+})
+const mcpHandler = createMcpHandler(
+  createMcpFactory(app, {
+    name: 'planets',
+    version: '1.0.0',
+    // IdP claims → contract context; `extra` is verifier-defined, so check it.
+    context: (info): AppCtx => {
+      const sub = info.authInfo?.extra?.sub
+      if (typeof sub !== 'string') throw new PFError({ code: 'UNAUTHORIZED', message: 'Token has no subject' })
+      return { db, user: { id: sub } }
+    },
+  }),
+)
+
+export async function fetchHandler(request: Request): Promise<Response> {
+  const metadata = oauthMetadataResponse(request, { oauthMetadata, resourceServerUrl })
+  if (metadata) return metadata
+  const authInfo = await gate(request)
+  return authInfo instanceof Response ? authInfo : mcpHandler.fetch(request, { authInfo })
+}
+```
+- Tests and agent frameworks: `tools.list(info)` / `tools.call(name, args, info)`, no transport. End to end: `createMcpHandler(factory).fetch` with the v2 `Client` and `versionNegotiation: { mode: 'auto' }` (the client defaults to the 2025 protocol).
+
+## API
+
+- `mcp` (`@ts-pf/mcp/meta`)
+- `createToolkit` — root members `$context`, `$tool`, `$host`, `$toolset`, `$coverage`
+- `all`
+- `bindTools` — `{ app, context, interceptors?, onError?, maxResultChars? }` or `{ client, context?, onError?, maxResultChars? }` (`context` required when the toolkit's context type has required keys)
+- `audit` — `(toolsets, { maxTools? = 15, maxNameLength? = 60, missingDescription? = 'error' })` → `{ level, tool, message }[]`
+- `createMcpFactory` (`@ts-pf/mcp/sdk`) — `(app, { name, version, instructions?, listTtlMs?, context, interceptors?, onError?, maxResultChars? })` (`context` optional for an unbranded app) or `(tools, { name, version, instructions?, listTtlMs? })`
+- `McpTools`
+- `McpCallInfo` — `{ authInfo?, requestInfo?, signal?, inputResponses?, era?, tool? }`; `tool` is `{ name, path }` of the tool being called (the inner tool for a host call)
+- `McpToolDefinition`
+- `McpToolResult`
+
+## Pair with
+
+- `ts-pf-contract`
+- `ts-pf-server`
+- `ts-pf-docs`
+
+## Don't
+
+- Import `@ts-pf/mcp` or `@ts-pf/mcp/sdk` from a contract file (use `@ts-pf/mcp/meta`).
+- Reuse `FetchHandler` or a message handler to serve MCP; MCP is JSON-RPC 2.0, served by the SDK.
+- Build on `@modelcontextprotocol/sdk` (v1) or the deprecated low-level `Server`.
+- Cache or share one `McpServer` across requests; the factory builds one per request.
+- Name contract keys starting with `$` (reserved for toolkit root members).
+- Forward `Authorization` / `Cookie` headers into context; use `info.authInfo`.
+- Expect interceptors to see the tool name; they see the procedure path. Copy `info.tool` into your context type in `context: (info) => …` if you trace tools.
+- Switch to hosts automatically by tool count, or add resources / prompts, `.visible()`, `confirm`, `.title()`, `.text()`, or custom host name templates (later versions).