@ts-pf/mcp 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ts-pf contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# @ts-pf/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Opt-in MCP tools from a ts-pf contract. The contract defines the tools, an executor runs them (your `app` in-process, or a typed client), and the official MCP SDK v2 serves them. A projection plus an executor: no MCP wire code here, and no ts-pf HTTP or message handler is reused.
+
+Agent skill: [`skills/ts-pf-mcp/`](skills/ts-pf-mcp/). Sync with `npx skills experimental_sync -y`.
+
+Three entries:
+
+- `@ts-pf/mcp/meta`: `mcp({ effect, description, aliases })`, dependency-free, safe in contract files.
+- `@ts-pf/mcp`: the toolkit (`createToolkit`, `all`, `bindTools`, `audit`). Depends on `@ts-pf/contract`, `@ts-pf/docs`, `@ts-pf/server`, `@ts-pf/protocol`.
+- `@ts-pf/mcp/sdk`: `createMcpFactory`, a per-request `McpServer` factory. Peer **`@modelcontextprotocol/server` >=2.4.0 <3**.
+
+## One call
+
+Every procedure becomes a tool named by its path (`planet.find` → `planet_find`); `docs({ hidden: true })` procedures are skipped. `context` runs once per call and is typed from the app's `$context<C>()`.
+
+```ts
+import { createMcpFactory } from '@ts-pf/mcp/sdk'
+
+export const factory = createMcpFactory(app, { name: 'planets', version: '1.0.0' })
+```
+
+## Shape tools, compose toolsets, check coverage
+
+Classify in the contract with `.meta({ ...docs({ description }), ...mcp({ effect: 'read' }) })`; unclassified tools count as `write`. Descriptions come from `.describe()`, then `mcp({ description })`, then `docs()` description / summary.
+
+```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)
+
+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 }],
+})
+
+// A new procedure fails this line until a toolset exposes it or `exclude` names it.
+tk.$coverage({ toolsets: [planetsMcp] })
+
+export const tools = bindTools(planetsMcp, { app, context: () => ({ db }) })
+export const factory = createMcpFactory(tools, { name: 'planets', version: '1.0.0' })
+```
+
+Builder methods: `.describe(text)`, `.effect('read' | 'write' | 'destructive')`, `.inject({ key: fn })` (hidden from the model, filled per call), `.input(schema, map)` (a new model input; exclusive with `.inject`), `.output(map)` / `.output(schema, map)` (mappers get `{ context, info, call }`, `call` a typed client for joins; `outputSchema` and `structuredContent` only with a schema, and results are then checked), `.errors({ CODE: fn })`, `.examples([...])`. `tk.$tool({ description, effect, input, run })` is a composite tool over `call`.
+
+`all(node, { effect, tags, exclude, inject })` makes default tools for a node; each `inject` key goes only to tools whose input has it, and a typo or a type conflict is a compile error naming the field.
+
+Large groups go behind a host: `tk.$host({ description, tools, split })` lists `get_<key>_query_capabilities` / `call_<key>_query_capability` (read) and `get_<key>_operations_capabilities` / `call_<key>_operations_capability` (write + destructive), or `get_<key>_capabilities` / `call_<key>_capability` with `split: false`. Discovery takes `{ query, category, names, detail, limit }` and ranks with BM25. Flat tools do best up to about 15 per toolset; `audit()` warns above that.
+
+## Serve
+
+`@modelcontextprotocol/server` owns the transport. Over HTTP, pass the verified token as `authInfo`; it reaches `context` as `info.authInfo`. Request headers are not forwarded to procedures; `context` sees the `Request` as `info.requestInfo` and should derive identity from `authInfo`, not raw `Authorization` / `Cookie`. stdio never carries a token, so give identity from the process: `serveStdio((ctx) => factory({ ...ctx, authInfo }))` with `serveStdio` from `@modelcontextprotocol/server/stdio`.
+
+```ts
+import { createMcpHandler } from '@modelcontextprotocol/server'
+import { createMcpFactory } from '@ts-pf/mcp/sdk'
+
+const factory = createMcpFactory(app, { name: 'planets', version: '1.0.0' })
+const mcpHandler = createMcpHandler(factory)
+export const response = await mcpHandler.fetch(request)
+```
+
+## OAuth
+
+An HTTP MCP server is an OAuth resource server. The SDK checks the token at the HTTP edge, before any MCP message is handled: a client starts sign-in only on a `401` with a `WWW-Authenticate` challenge, and an error from a tool call does not trigger it. ts-pf takes over from the verified `AuthInfo`. `context` maps your IdP's claims into the app's context, then the procedure's own middleware runs as usual.
+
+```ts
+import {
+  createMcpHandler,
+  getOAuthProtectedResourceMetadataUrl,
+  OAuthError,
+  OAuthErrorCode,
+  type OAuthMetadata,
+  type OAuthTokenVerifier,
+  oauthMetadataResponse,
+  requireBearerAuth,
+} from '@modelcontextprotocol/server'
+import { createMcpFactory } from '@ts-pf/mcp/sdk'
+import { PFError } from '@ts-pf/protocol'
+
+const issuer = 'https://idp.example.com'
+const resourceServerUrl = new URL('https://api.example.com/mcp')
+
+// Your IdP's RFC 8414 metadata, re-served for clients that probe this origin.
+// Fetched once at startup (fails fast if the IdP is down); hardcode it if you prefer.
+const oauthMetadata = (await (
+  await fetch(`${issuer}/.well-known/oauth-authorization-server`)
+).json()) as OAuthMetadata
+
+const invalid = (message: string) =>
+  new OAuthError(OAuthErrorCode.InvalidToken, message)
+
+// Introspection (RFC 7662) as this server's own client; validating a JWT against the IdP's JWKS works too.
+// Anything unexpected is `invalid_token` (a 401 challenge), never a crash.
+const verifier: OAuthTokenVerifier = {
+  async verifyAccessToken(token) {
+    const response = await fetch(`${issuer}/oauth/introspect`, {
+      method: 'POST',
+      headers: {
+        authorization: `Basic ${btoa(`${env.MCP_CLIENT_ID}:${env.MCP_CLIENT_SECRET}`)}`,
+      },
+      body: new URLSearchParams({ token }),
+    })
+    if (!response.ok) throw invalid('Introspection failed')
+    const claims = (await response.json()) as {
+      active?: boolean
+      sub?: string
+      client_id?: string
+      scope?: string
+      exp?: number
+      aud?: string | string[]
+    }
+    if (!claims.active || typeof claims.sub !== 'string') {
+      throw invalid('Token is not active')
+    }
+    if (typeof claims.exp !== 'number') throw invalid('Token has no expiry')
+    if (![claims.aud ?? []].flat().includes(resourceServerUrl.href)) {
+      throw invalid('Token was issued for another resource')
+    }
+    return {
+      token,
+      clientId: claims.client_id ?? '',
+      scopes: claims.scope?.split(' ') ?? [],
+      expiresAt: claims.exp, // required: the SDK refuses tokens without it
+      resource: resourceServerUrl,
+      extra: { sub: claims.sub },
+    }
+  },
+}
+
+const gate = requireBearerAuth({
+  verifier,
+  requiredScopes: ['mcp'],
+  expectedResource: resourceServerUrl, // refuse tokens issued for another audience
+  resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(resourceServerUrl),
+})
+
+// IdP claims → the contract's context. Procedure middleware then sees AppCtx, as on any other transport.
+const factory = createMcpFactory(app, {
+  name: 'planets',
+  version: '1.0.0',
+  context: async (info): Promise<AppCtx> => {
+    const sub = info.authInfo?.extra?.sub
+    if (typeof sub !== 'string') {
+      // `extra` is whatever the verifier set; stdio and tests have no token at all.
+      throw new PFError({ code: 'UNAUTHORIZED', message: 'Token has no subject' })
+    }
+    return { db, user: { id: sub } } // or look the user up by IdP subject
+  },
+})
+const mcpHandler = createMcpHandler(factory)
+
+export async function fetchHandler(request: Request): Promise<Response> {
+  // `/.well-known/oauth-protected-resource/mcp` (RFC 9728) and the AS metadata.
+  const metadata = oauthMetadataResponse(request, { oauthMetadata, resourceServerUrl })
+  if (metadata) return metadata
+  const authInfo = await gate(request)
+  if (authInfo instanceof Response) return authInfo // 401 / 403 with the challenge
+  return mcpHandler.fetch(request, { authInfo })
+}
+```
+
+- With a toolkit, the same function goes on the binding: `bindTools(toolset, { app, context: (info) => … })`. `.inject()` and output mappers get both the mapped `context` and the raw `info.authInfo`.
+- A gateway that calls an upstream ts-pf API as the user builds a client per caller: `bindTools(toolset, { client: (info) => createClient(…) })`, with the token from `info.authInfo` (exchanged for an upstream one when your IdP requires it).
+- `context` can reject per tool (`info.tool`), for example when a scope is missing. The model gets the error as text; v1 does not answer it with a `403 insufficient_scope` step-up.
+- Every caller gets the same `tools/list`. Enforce roles and scopes in procedure middleware, not by hiding tools.
+
+`tools.list(info)` and `tools.call(name, args, info)` work without MCP, in tests or an agent framework. `McpCallInfo` is `{ authInfo?, requestInfo?, signal?, inputResponses?, era?, tool? }`; `tool` (`{ name, path }`) is set before `context` runs, so a project that wants tool-level tracing in interceptors copies it into its own context type.
+
+Call pipeline options live on the executor: `bindTools(toolset, { app, context, interceptors?, onError?, maxResultChars? })` or `bindTools(toolset, { client, context?, onError?, maxResultChars? })` (`client` may be `(info) => client`; `context` is required when the toolkit's `$context<C>()` type has required keys). `createMcpFactory(app, …)` takes the same options plus `name`, `version`, `instructions`, `listTtlMs`. Unknown throws become `INTERNAL: Internal server error` and are logged with `console.error` unless `onError` is set, like `FetchHandler`. Text results are cut at `maxResultChars` (default 25,000).
+
+`audit(toolsets, { maxTools?, maxNameLength?, missingDescription? })` returns `AuditFinding[]` (`{ level, tool, message }`) for CI: missing descriptions (`missingDescription`, default `'error'`), unclassified tools, schema roots, more than `maxTools` (15) listed tools, and names over `maxNameLength` (60) characters or outside the MCP name charset.
+
+## API
+
+- `mcp`
+- `createToolkit`
+- `all`
+- `bindTools`
+- `audit`
+- `createMcpFactory`
+- `McpTools`
+- `McpCallInfo`
+- `McpToolDefinition`
+- `McpToolResult`
+
+`mcp` is `@ts-pf/mcp/meta`. `createMcpFactory` is `@ts-pf/mcp/sdk`. The rest are `@ts-pf/mcp`, which also exports the types that appear in inferred toolkit values (`Toolkit`, `ToolkitNode`, `ToolBuilder`, `Toolset`, `Host`, `AllTools`, `CompositeTool`, …) so a toolset can be exported under `declaration: true`.

package/dist/all.d.ts

@@ -0,0 +1,63 @@
+import type { DistOmit, FieldOf, KeysOfUnion, Meta } from './infer.js';
+import type { Effect } from './meta.js';
+import { type ToolName } from './names.js';
+import { type AnyNode, type NodeBrand, type NodeCtx } from './node.js';
+import { type AnyTool, type ToolBuilder } from './tool.js';
+import type { McpCallInfo } from './types.js';
+type LeafTools<N> = {
+    [K in Exclude<keyof N, NodeBrand>]: N[K] extends AnyTool ? N[K] : LeafTools<N[K]>;
+}[Exclude<keyof N, NodeBrand>];
+/** A tool excludes its own path; a node excludes everything under its prefix. */
+export type ExcludedPath<X> = X extends AnyTool ? X['~tool']['path'] : X extends {
+    readonly [K in NodeBrand]?: {
+        prefix: infer P extends string;
+    };
+} ? `${P}${string}` : never;
+/** Effect from typed meta `{ mcp: { effect } }`; unclassified counts as `write`. */
+type ToolEffect<Tl> = Tl extends ToolBuilder<infer _T, infer P, infer _C, infer _Path, infer _S> ? Meta<P> extends {
+    mcp: {
+        effect: infer E extends Effect;
+    };
+} ? E : 'write' : 'write';
+type Injected<Tl, IK extends PropertyKey> = [IK] extends [never] ? Tl : Tl extends ToolBuilder<infer T, infer P, infer C, infer Path, infer S> ? [IK & KeysOfUnion<S['model']>] extends [never] ? Tl : ToolBuilder<T, P, C, Path, {
+    model: DistOmit<S['model'], IK>;
+    mode: 'inject';
+}> : Tl;
+/**
+ * Filters once into `Selected` (shared with the inject check), then maps. A
+ * filtering `as` clause here would re-run over every leaf on each `keyof`,
+ * which the toolset name checks take several times.
+ */
+export type AllTools<N, X, E, IK extends PropertyKey> = {
+    [Tl in Selected<N, X, E> as ToolName<Tl['~tool']['path']>]: Injected<Tl, IK>;
+};
+type ModelOf<Tl> = Tl extends AnyTool ? Tl['~tool']['model'] : never;
+/** Concrete (`N` is fixed before `inject` is checked), so it contextually types `context`. */
+type InjectCtx<N> = {
+    [k: string]: (o: {
+        context: NodeCtx<N>;
+        info: McpCallInfo;
+    }) => unknown;
+};
+type Selected<N, X, E> = LeafTools<N> extends infer Tl ? Tl extends AnyTool ? Tl['~tool']['path'] extends ExcludedPath<X> ? never : ToolEffect<Tl> extends E ? Tl : never : never : never;
+type ConflictPaths<Tl, K extends PropertyKey, V> = Tl extends AnyTool ? K extends KeysOfUnion<Tl['~tool']['model']> ? [V] extends [FieldOf<Tl['~tool']['model'], K>] ? never : `${Tl['~tool']['path']}.${K & string}` : never : never;
+/** Per key: not an input field anywhere → message; value does not fit some field → message naming it. */
+type AllInjectCheck<Tls, Inj> = {
+    [K in keyof Inj]: K extends KeysOfUnion<ModelOf<Tls>> ? ConflictPaths<Tls, K, Inj[K] extends (...a: never[]) => infer R ? Awaited<R> : never> extends infer C extends string ? [C] extends [never] ? unknown : `Injected "${K & string}" does not fit field ${C}` : unknown : `"${K & string}" is not an input field of any selected procedure`;
+};
+export type AllOptions<N, X extends readonly unknown[], E, Inj> = {
+    exclude?: X;
+    effect?: E | readonly E[];
+    /** `docs()` tags; a procedure matches when it has any of them. Filtered at runtime only. */
+    tags?: readonly string[];
+    /** Each key goes only to tools whose input has it. */
+    inject?: Inj & InjectCtx<N> & AllInjectCheck<Selected<N, X[number], E>, Inj>;
+};
+/**
+ * Default tools for every procedure under `node`, named by path. Skips
+ * `docs({ hidden: true })` procedures, then filters by `exclude`, `effect`,
+ * and `tags`, and applies `inject` per tool.
+ */
+export declare function all<N extends AnyNode, const X extends readonly (AnyTool | AnyNode)[] = [], const E extends Effect = Effect, Inj extends object = {}>(node: N, options?: AllOptions<N, X, E, Inj>): AllTools<N, X[number], E, keyof Inj>;
+export {};
+//# sourceMappingURL=all.d.ts.map

package/dist/all.d.ts.map

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

package/dist/all.js

@@ -0,0 +1,55 @@
+import { walkContract } from '@ts-pf/docs';
+import { toolName } from './names.js';
+import { nodeInfo } from './node.js';
+import { procedureInputKeys } from './schema.js';
+import { createToolBuilder, isTool, procedureSpec, toolSpec, } from './tool.js';
+import { effectOf, isHidden, tagsOf } from './tool-meta.js';
+function exclusion(value) {
+    if (isTool(value))
+        return { path: toolSpec(value).path, subtree: false };
+    const info = nodeInfo(value);
+    if (info)
+        return { path: info.path.join('.'), subtree: true };
+    throw new TypeError('all() exclude takes toolkit tools or nodes');
+}
+function isExcluded(path, exclusions) {
+    return exclusions.some((x) => path === x.path ||
+        (x.subtree && (x.path === '' || path.startsWith(`${x.path}.`))));
+}
+/**
+ * Default tools for every procedure under `node`, named by path. Skips
+ * `docs({ hidden: true })` procedures, then filters by `exclude`, `effect`,
+ * and `tags`, and applies `inject` per tool.
+ */
+export function all(node, options) {
+    const info = nodeInfo(node);
+    if (!info) {
+        throw new TypeError('all() takes a toolkit node, e.g. all(tk.user)');
+    }
+    const exclusions = (options?.exclude ?? []).map(exclusion);
+    const effects = options?.effect === undefined ? undefined : [options.effect].flat();
+    const tags = options?.tags;
+    const inject = (options?.inject ?? {});
+    const tools = {};
+    for (const entry of walkContract(info.contract)) {
+        const path = [...info.path, ...entry.path].join('.');
+        const spec = procedureSpec(path, entry.procedure);
+        if (isHidden(spec) || isExcluded(path, exclusions))
+            continue;
+        if (effects && !effects.includes(effectOf(spec)))
+            continue;
+        if (tags && !tagsOf(spec).some((tag) => tags.includes(tag)))
+            continue;
+        const keys = procedureInputKeys(spec).filter((key) => Object.hasOwn(inject, key));
+        const name = toolName(path);
+        if (Object.hasOwn(tools, name)) {
+            throw new Error(`all(): duplicate tool name "${name}"`);
+        }
+        tools[name] = createToolBuilder({
+            ...spec,
+            inject: Object.fromEntries(keys.map((key) => [key, inject[key]])),
+        });
+    }
+    return tools;
+}
+//# sourceMappingURL=all.js.map

package/dist/all.js.map

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

package/dist/audit.d.ts

@@ -0,0 +1,21 @@
+import { type AnyToolset } from './toolset.js';
+export type AuditFinding = {
+    level: 'error' | 'warn';
+    /** A tool name, or `toolset[i]` for a finding about a whole toolset. */
+    tool: string;
+    message: string;
+};
+export type AuditOptions = {
+    /** Warn when a toolset lists more MCP tools than this. Default 15. */
+    maxTools?: number;
+    /** Warn above this name length (a soft limit for Cursor; the spec allows 128). Default 60. */
+    maxNameLength?: number;
+    /** Severity of an empty description. Default `'error'` (descriptions come from `docs()` first). */
+    missingDescription?: 'error' | 'warn';
+};
+/**
+ * Runtime lint for CI: descriptions, classification, schema roots, toolset
+ * size, and names. Coverage is `$coverage`'s job, not this one's.
+ */
+export declare function audit(toolsets: readonly AnyToolset[], options?: AuditOptions): AuditFinding[];
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,UAAU,EAIhB,MAAM,cAAc,CAAA;AAErB,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;IACvB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8FAA8F;IAC9F,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mGAAmG;IACnG,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CACtC,CAAA;AAeD;;;GAGG;AACH,wBAAgB,KAAK,CACnB,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,OAAO,GAAE,YAAiB,GACzB,YAAY,EAAE,CAsEhB"}

package/dist/audit.js

@@ -0,0 +1,85 @@
+import { bindTool } from './bound-tool.js';
+import { declaredEffect, effectOf } from './tool-meta.js';
+import { hostToolNames, toolsetSpec, } from './toolset.js';
+const MCP_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+/** Host tool names actually listed: buckets with no tools list nothing. */
+function listedHostNames(key, host) {
+    if (host.split !== 'effect')
+        return hostToolNames(key, false);
+    const effects = Object.values(host.tools).map(effectOf);
+    const [getQuery, callQuery, getOps, callOps] = hostToolNames(key, 'effect');
+    return [
+        ...(effects.includes('read') ? [getQuery, callQuery] : []),
+        ...(effects.some((e) => e !== 'read') ? [getOps, callOps] : []),
+    ].filter((name) => name !== undefined);
+}
+/**
+ * Runtime lint for CI: descriptions, classification, schema roots, toolset
+ * size, and names. Coverage is `$coverage`'s job, not this one's.
+ */
+export function audit(toolsets, options = {}) {
+    const maxTools = options.maxTools ?? 15;
+    const maxNameLength = options.maxNameLength ?? 60;
+    const missingDescription = options.missingDescription ?? 'error';
+    const findings = [];
+    toolsets.forEach((toolset, index) => {
+        const spec = toolsetSpec(toolset);
+        const listed = [
+            ...Object.keys(spec.tools),
+            ...Object.entries(spec.hosts).flatMap(([key, host]) => listedHostNames(key, host)),
+        ];
+        if (listed.length > maxTools) {
+            findings.push({
+                level: 'warn',
+                tool: `toolset[${index}]`,
+                message: `lists ${listed.length} tools (more than ${maxTools}); split it or put a large group behind a $host`,
+            });
+        }
+        for (const name of listed) {
+            if (!MCP_NAME.test(name)) {
+                findings.push({
+                    level: 'error',
+                    tool: name,
+                    message: 'name must be 1-128 characters of A-Z, a-z, 0-9, "_", "-", "."',
+                });
+            }
+            else if (name.length > maxNameLength) {
+                findings.push({
+                    level: 'warn',
+                    tool: name,
+                    message: `name is ${name.length} characters (more than ${maxNameLength}); some clients cut or reject it`,
+                });
+            }
+        }
+        const tools = [
+            ...Object.entries(spec.tools),
+            ...Object.values(spec.hosts).flatMap((host) => Object.entries(host.tools)),
+        ];
+        for (const [name, toolSpec] of tools) {
+            const bound = bindTool(name, toolSpec);
+            if (bound.definition.description.trim() === '') {
+                findings.push({
+                    level: missingDescription,
+                    tool: name,
+                    message: 'no description; add docs({ description }) in the contract, mcp({ description }), or .describe()',
+                });
+            }
+            if (toolSpec.procedure && declaredEffect(toolSpec) === undefined) {
+                findings.push({
+                    level: 'warn',
+                    tool: name,
+                    message: 'unclassified; treated as write. Add mcp({ effect }) in the contract or .effect()',
+                });
+            }
+            for (const issue of bound.issues) {
+                findings.push({
+                    level: issue.level,
+                    tool: name,
+                    message: issue.message,
+                });
+            }
+        }
+    });
+    return findings;
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

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

package/dist/bind.d.ts

@@ -0,0 +1,42 @@
+import type { ContractClient } from '@ts-pf/contract';
+import type { CallInterceptor, ImplementedRouter } from '@ts-pf/server';
+import { type CallOptions } from './call.js';
+import type { McpOnError } from './error-text.js';
+import type { MaybePromise } from './infer.js';
+import { type Toolset, type ToolsetSpec } from './toolset.js';
+import type { McpCallInfo, McpTools } from './types.js';
+/** Options that act inside `McpTools.call`, for both executors. */
+export type CallPipelineOptions = {
+    /** Replaces the default `console.error` of unknown / `INTERNAL` throws. */
+    onError?: McpOnError;
+    /** Text results are cut here with a truncation note. Default 25,000. */
+    maxResultChars?: number;
+};
+export type AppBinding<T, Ctx> = CallPipelineOptions & {
+    app: ImplementedRouter<T, Ctx>;
+    /** Runs once per call, with `info.tool` set. */
+    context: (info: McpCallInfo) => MaybePromise<Ctx>;
+    /** Server `CallInterceptor`s, passed straight to `runProcedure`. */
+    interceptors?: readonly CallInterceptor[];
+};
+/**
+ * Mappers and `inject` still see `context`, so it is required when the
+ * toolset's context type has required keys (`$context<AppCtx>()`), and `{}`
+ * when omitted otherwise.
+ */
+type ClientContext<Ctx> = {} extends Ctx ? {
+    context?: (info: McpCallInfo) => MaybePromise<Ctx>;
+} : {
+    context: (info: McpCallInfo) => MaybePromise<Ctx>;
+};
+export type ClientBinding<T, Ctx> = CallPipelineOptions & {
+    /** A typed client, or one built per caller (a gateway calling upstream as the user). */
+    client: ContractClient<T> | ((info: McpCallInfo) => ContractClient<T>);
+} & ClientContext<Ctx>;
+/** Bound tools from runtime specs; definitions, schemas, and search indexes are built once here. */
+export declare function bindToolset(spec: ToolsetSpec, options: CallOptions): McpTools;
+/** Bind a toolset to an executor. The contract and context are checked against the toolset's. */
+export declare function bindTools<T, Ctx>(toolset: Toolset<T, Ctx, string>, binding: AppBinding<NoInfer<T>, NoInfer<Ctx>>): McpTools;
+export declare function bindTools<T, Ctx>(toolset: Toolset<T, Ctx, string>, binding: ClientBinding<NoInfer<T>, NoInfer<Ctx>>): McpTools;
+export {};
+//# sourceMappingURL=bind.d.ts.map

package/dist/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../src/bind.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEvE,OAAO,EAAE,KAAK,WAAW,EAAY,MAAM,WAAW,CAAA;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAGjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAe,MAAM,cAAc,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAEvD,mEAAmE;AACnE,MAAM,MAAM,mBAAmB,GAAG;IAChC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,GAAG,IAAI,mBAAmB,GAAG;IACrD,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAC9B,gDAAgD;IAChD,OAAO,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,YAAY,CAAC,GAAG,CAAC,CAAA;IACjD,oEAAoE;IACpE,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;CAC1C,CAAA;AAED;;;;GAIG;AACH,KAAK,aAAa,CAAC,GAAG,IAAI,EAAE,SAAS,GAAG,GACpC;IAAE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,YAAY,CAAC,GAAG,CAAC,CAAA;CAAE,GACtD;IAAE,OAAO,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,YAAY,CAAC,GAAG,CAAC,CAAA;CAAE,CAAA;AAEzD,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,GAAG,IAAI,mBAAmB,GAAG;IACxD,wFAAwF;IACxF,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,WAAW,KAAK,cAAc,CAAC,CAAC,CAAC,CAAC,CAAA;CACvE,GAAG,aAAa,CAAC,GAAG,CAAC,CAAA;AAEtB,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,QAAQ,CAoC7E;AAED,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAC9B,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAChC,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,GAC5C,QAAQ,CAAA;AACX,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAC9B,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAChC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,GAC/C,QAAQ,CAAA"}

package/dist/bind.js

@@ -0,0 +1,46 @@
+import { bindTool } from './bound-tool.js';
+import { callTool } from './call.js';
+import { appExecutor, clientExecutor } from './executor.js';
+import { hostEntries } from './host.js';
+import { DEFAULT_MAX_RESULT_CHARS, errorResult } from './result.js';
+import { toolsetSpec } from './toolset.js';
+/** Bound tools from runtime specs; definitions, schemas, and search indexes are built once here. */
+export function bindToolset(spec, options) {
+    const entries = new Map();
+    const invoke = (tool, args, info) => callTool(tool, args, info, options);
+    for (const [name, toolSpec] of Object.entries(spec.tools)) {
+        const tool = bindTool(name, toolSpec);
+        entries.set(name, {
+            definition: tool.definition,
+            invoke: (args, info) => invoke(tool, args, info),
+        });
+    }
+    for (const [key, host] of Object.entries(spec.hosts)) {
+        const inner = Object.entries(host.tools).map(([name, s]) => bindTool(name, s));
+        for (const entry of hostEntries(key, host, inner, invoke, options.maxResultChars)) {
+            entries.set(entry.definition.name, entry);
+        }
+    }
+    const definitions = [...entries.values()].map((entry) => entry.definition);
+    return {
+        list: async () => [...definitions],
+        async call(name, args, info = {}) {
+            const entry = entries.get(name);
+            if (!entry) {
+                return errorResult(`Unknown tool "${name}"`, options.maxResultChars);
+            }
+            return entry.invoke(args, info);
+        },
+    };
+}
+export function bindTools(toolset, binding) {
+    const executor = 'app' in binding
+        ? appExecutor(binding.app, binding.context, binding.interceptors)
+        : clientExecutor(binding.client, binding.context);
+    return bindToolset(toolsetSpec(toolset), {
+        executor,
+        onError: binding.onError,
+        maxResultChars: binding.maxResultChars ?? DEFAULT_MAX_RESULT_CHARS,
+    });
+}
+//# sourceMappingURL=bind.js.map

package/dist/bind.js.map

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

package/dist/bound-tool.d.ts

@@ -0,0 +1,18 @@
+import type { JsonSchema } from '@ts-pf/docs';
+import { type SchemaIssue } from './schema.js';
+import type { ToolSpec } from './tool.js';
+import type { McpToolDefinition } from './types.js';
+/** One tool after binding: computed once, so listing and calling only read it. */
+export type BoundTool = {
+    readonly name: string;
+    readonly spec: ToolSpec;
+    /** The schema the model fills (injected keys removed). */
+    readonly inputSchema: JsonSchema;
+    /** `structuredContent` is returned only when `outputSchema` is advertised. */
+    readonly structured: boolean;
+    readonly definition: McpToolDefinition;
+    /** Schema problems for `audit()`. */
+    readonly issues: readonly SchemaIssue[];
+};
+export declare function bindTool(name: string, spec: ToolSpec): BoundTool;
+//# sourceMappingURL=bound-tool.d.ts.map

package/dist/bound-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bound-tool.d.ts","sourceRoot":"","sources":["../src/bound-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAA;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;IACtC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;CACxC,CAAA;AAQD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,CAoBhE"}

package/dist/bound-tool.js

@@ -0,0 +1,31 @@
+import { modelInputSchema, modelOutputSchema, } from './schema.js';
+import { annotationsFor, descriptionOf, effectOf } from './tool-meta.js';
+function withExamples(description, examples) {
+    if (examples.length === 0)
+        return description;
+    const lines = examples.map((example) => JSON.stringify(example)).join('\n');
+    return `${description}\n\nExamples:\n${lines}`;
+}
+export function bindTool(name, spec) {
+    const input = modelInputSchema(spec);
+    const output = modelOutputSchema(spec);
+    const effect = effectOf(spec);
+    const definition = {
+        name,
+        description: withExamples(descriptionOf(spec), spec.examples),
+        inputSchema: input.schema,
+        annotations: annotationsFor(effect),
+        effect,
+    };
+    if (output.schema)
+        definition.outputSchema = output.schema;
+    return {
+        name,
+        spec,
+        inputSchema: input.schema,
+        structured: output.schema !== undefined,
+        definition,
+        issues: [...input.issues, ...output.issues],
+    };
+}
+//# sourceMappingURL=bound-tool.js.map

package/dist/bound-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bound-tool.js","sourceRoot":"","sources":["../src/bound-tool.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,EAChB,iBAAiB,GAElB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAgBxE,SAAS,YAAY,CAAC,WAAmB,EAAE,QAA4B;IACrE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,WAAW,CAAA;IAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC3E,OAAO,GAAG,WAAW,kBAAkB,KAAK,EAAE,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,IAAc;IACnD,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAA;IACpC,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAA;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC7B,MAAM,UAAU,GAAsB;QACpC,IAAI;QACJ,WAAW,EAAE,YAAY,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC;QAC7D,WAAW,EAAE,KAAK,CAAC,MAAM;QACzB,WAAW,EAAE,cAAc,CAAC,MAAM,CAAC;QACnC,MAAM;KACP,CAAA;IACD,IAAI,MAAM,CAAC,MAAM;QAAE,UAAU,CAAC,YAAY,GAAG,MAAM,CAAC,MAAM,CAAA;IAC1D,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,WAAW,EAAE,KAAK,CAAC,MAAM;QACzB,UAAU,EAAE,MAAM,CAAC,MAAM,KAAK,SAAS;QACvC,UAAU;QACV,MAAM,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;KAC5C,CAAA;AACH,CAAC"}