purra-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lybrands
+
+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

@@ -0,0 +1,128 @@
+# purra-mcp (TypeScript)
+
+Development package for explicitly authorized, read-only MCP tools. Requires
+Node.js 22+, matching `purra`, and the pinned official
+`@modelcontextprotocol/sdk@1.30.0` (v1 line). Core has no MCP dependency.
+Build Core and this package, then install both in the consuming application.
+
+The application owns the connected official `Client`, transport, credentials,
+initialization and shutdown. The adapter sends only paginated `tools/list` and
+single `tools/call` requests. Configure monitoring before connecting:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { McpCatalogMonitor, discoverMcpTools } from "purra-mcp";
+
+async function attach(transport: Transport) {
+  const monitor = new McpCatalogMonitor();
+  const setVersion = transport.setProtocolVersion?.bind(transport);
+  transport.setProtocolVersion = version => {
+    setVersion?.(version);
+    monitor.acceptProtocolVersion(version);
+  };
+  const client = new Client({ name: "my-host", version: "1" });
+  client.setNotificationHandler(ToolListChangedNotificationSchema,
+    notification => monitor.onNotification(notification));
+  client.onclose = () => monitor.close();
+  await client.connect(transport);
+  const catalog = await discoverMcpTools(client, "documents", {
+    "remote.search": {
+      localName: "search_documents",
+      policy: { mode: "read", title: "Search documents" },
+      scope: (args, context) => context.runId ? undefined : "Missing Run",
+      concurrencySafe: false,
+    },
+  }, { monitor });
+  // Pass catalog.registrations as Agent tools while client remains connected.
+  // Replace the sample scope check with the application's real authorization.
+  return { client, catalog, monitor }; // Caller eventually awaits client.close().
+}
+```
+
+Compose existing notification/close handlers rather than replacing host logic.
+The protocol hook receives the actual handshake version from SDK `connect`;
+never fill it with a configured guess. Supported negotiated versions are
+`2025-06-18` and `2025-11-25`. A previously connected host must have retained its
+negotiated version and fed all list-change notifications.
+
+Each binding is a host assertion of read-only behavior and authorized scope.
+Remote annotations grant no authority. `scope: null` explicitly opts out of an
+additional host scope check. A function returns `undefined`/true to allow, or
+false/a non-empty string to deny. Core supplies Run/root/agent/lease context.
+`concurrencySafe` records a declaration and does not itself enable scheduling.
+The adapter cannot make a falsely declared remote write read-only.
+
+The immutable snapshot has `schemaVersion: 1`, `serverId`, `protocolVersion`,
+`revisionDigest` and entries sorted by local name. Identity uses Core's
+`purra.json-identity/v1` over these fields without `revisionDigest`; entries
+include names, description, schemas, read policy and concurrency declaration.
+A list-change notification makes old registrations stale. Discover again and
+replace the host's catalog at a safe boundary. Registration never widens itself.
+
+Selected schemas use Core's strict `purra.output-schema/v1` object profile;
+unsupported schemas fail discovery without weakening. Arguments are not
+coerced. Success contains `{ text: string[], structured: object | null }`.
+An output schema requires valid `structuredContent`. Text that resembles JSON
+does not satisfy it. Media, resource content/links, required tasks and `isError`
+results fail closed. This adapter does not install sampling, elicitation,
+resources or task handlers; the host must not enable them on this tools-only path.
+
+Default `limits`: `maxPages: 32`, `maxTools: 256`, `maxCatalogBytes: 1048576`,
+`maxSchemaBytes: 65536`, `maxDescriptionBytes: 8192`, `maxResultBytes: 65536`,
+`maxContentBlocks: 128`, `timeoutMs: 30000`. Lower any limit, or raise timeout
+up to 300000 ms. The result budget also bounds decoded argument objects; Core
+adds depth/node/validation budgets. Hosts must separately bound transport
+frames/bodies before SDK decoding.
+
+Discovery throws sanitized `McpAdapterError`. Known tool failures produce an
+empty envelope and `errorCode`: `mcp_invalid_arguments`, `mcp_scope_denied`,
+`mcp_catalog_stale`, `mcp_connection_closed`, `mcp_timeout`,
+`mcp_protocol_error`, `mcp_transport_error`, `mcp_tool_error`,
+`mcp_result_invalid`, `mcp_result_unsupported`, or `mcp_result_too_large`.
+Core's batch admission can fail earlier with Core argument/scope errors.
+No remote error message is passed to the model. No adapter retries, implicit
+rediscovery or hidden model calls occur.
+
+An AbortSignal stops local waiting; the official SDK sends a best-effort
+cancellation notification. It does not prove the remote task stopped. Late
+results are discarded. `effectState: "not_started"` describes the declared
+absence of host writes, not whether a network request was sent. Write tools are
+outside this adapter's support.
+
+Shared fixtures run against the official local client/server protocol, with a
+JSON serialization boundary. The installed smoke also launches and closes a
+separate stdio server. Third-party MCP services, real Providers and downstream
+applications require separate validation. See the [MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+and [cancellation specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation).
+
+Core's separately configured argument and result limits also apply. A result
+accepted by the adapter may still exceed a lower Core result limit and fail
+with `tool_result_too_large`. Align both budgets in the host configuration.
+
+
+Unsupported schema metadata is rejected as well as unsupported validation
+keywords. For example, `default` and `x-fastmcp-wrap-result` are outside
+`purra.output-schema/v1`: a selected tool using either fails discovery with
+`mcp_schema_unsupported` before `tools/call`. The adapter never strips these
+fields to make a remote tool appear supported. Select compatible tools explicitly;
+unselected unsupported tools do not widen the catalog. A working MCP handshake
+alone does not establish tool compatibility.
+
+MCP input/output schemas may declare the root `$schema` as exactly
+`https://json-schema.org/draft/2020-12/schema`. The adapter recognizes this
+MCP dialect declaration, retains it in the immutable snapshot and revision
+digest, and compiles the remaining constraints with `purra.output-schema/v1`.
+The full remote schema, including the declaration, counts against the schema
+byte limit. Other dialect URIs, nested declarations, references, and unknown
+keywords remain unsupported; no schema document is fetched. This does not add
+`$schema` to the Core structured-output profile or promise full JSON Schema
+2020-12 support. See the [MCP schema rules](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
+
+HTTP connection failures (including `fetch` transport `TypeError`) return
+`mcp_transport_error`; SDK response validation failures remain
+`mcp_result_invalid`. A lost response stream may remain pending until the
+configured request timeout. The host must close the monitor when discarding a
+failed session, then initialize a new session and explicitly rediscover tools
+before resuming work. Transport recovery never authorizes new tools.

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { type ServerNotification } from "@modelcontextprotocol/sdk/types.js";
+import { AgentError, type JsonValue, type ToolDefinition, type ToolPolicy } from "purra";
+export declare class McpAdapterError extends AgentError {
+    constructor(code: string);
+}
+export interface McpToolLimits {
+    readonly maxPages: number;
+    readonly maxTools: number;
+    readonly maxCatalogBytes: number;
+    readonly maxSchemaBytes: number;
+    readonly maxDescriptionBytes: number;
+    readonly maxResultBytes: number;
+    readonly maxContentBlocks: number;
+    readonly timeoutMs: number;
+}
+/** Feed negotiated protocol, list-change notifications and disconnects from the host. */
+export declare class McpCatalogMonitor {
+    #private;
+    acceptProtocolVersion(version: string): void;
+    onNotification(notification: ServerNotification): void;
+    close(): void;
+    get revision(): number;
+    get protocolVersion(): string | undefined;
+    check(revision: number): void;
+}
+export interface McpToolBinding {
+    readonly localName: string;
+    readonly policy: ToolPolicy;
+    readonly scope: NonNullable<ToolDefinition["scope"]> | null;
+    readonly concurrencySafe?: boolean;
+}
+export interface McpToolEntry {
+    readonly remoteName: string;
+    readonly localName: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, JsonValue>>;
+    readonly outputSchema: Readonly<Record<string, JsonValue>> | null;
+    readonly policy: Readonly<{
+        mode: "read";
+        title: string;
+        riskLevel: "read";
+    }>;
+    readonly concurrencySafe: boolean;
+}
+export interface McpToolSnapshot {
+    readonly schemaVersion: 1;
+    readonly serverId: string;
+    readonly protocolVersion: string;
+    readonly revisionDigest: string;
+    readonly entries: readonly McpToolEntry[];
+}
+export interface McpToolCatalog {
+    readonly snapshot: McpToolSnapshot;
+    readonly registrations: readonly ToolDefinition[];
+    readonly stale: boolean;
+}
+export interface McpDiscoveryOptions {
+    readonly monitor: McpCatalogMonitor;
+    readonly limits?: Partial<McpToolLimits>;
+    readonly signal?: AbortSignal;
+}
+export declare function discoverMcpTools(client: Client, serverId: string, bindings: Readonly<Record<string, McpToolBinding>>, options: McpDiscoveryOptions): Promise<McpToolCatalog>;

package/dist/index.js

@@ -0,0 +1,247 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { CallToolResultSchema, ListToolsResultSchema, ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { AgentCanceledError, AgentError, StructuredOutputContract, StructuredOutputError, jsonIdentityDigest } from "purra";
+export class McpAdapterError extends AgentError {
+    constructor(code) { super(code, "MCP tool boundary rejected the operation"); }
+}
+function fail(code) { throw new McpAdapterError(code); }
+const encoder = new TextEncoder();
+const size = (value) => encoder.encode(JSON.stringify(value)).length;
+const defaults = Object.freeze({ maxPages: 32, maxTools: 256, maxCatalogBytes: 1_048_576,
+    maxSchemaBytes: 65_536, maxDescriptionBytes: 8_192, maxResultBytes: 65_536, maxContentBlocks: 128, timeoutMs: 30_000 });
+function limitsOf(input = {}) {
+    if (Object.keys(input).some(key => !(key in defaults)))
+        fail("mcp_binding_invalid");
+    const limits = { ...defaults, ...input };
+    for (const key of Object.keys(defaults)) {
+        if (!Number.isSafeInteger(limits[key]) || limits[key] <= 0 || limits[key] > (key === "timeoutMs" ? 300_000 : defaults[key]))
+            fail("mcp_binding_invalid");
+    }
+    return Object.freeze(limits);
+}
+/** Feed negotiated protocol, list-change notifications and disconnects from the host. */
+export class McpCatalogMonitor {
+    #revision = 0;
+    #closed = false;
+    #protocol;
+    acceptProtocolVersion(version) {
+        if (!["2025-06-18", "2025-11-25"].includes(version)) {
+            this.close();
+            fail("mcp_protocol_unsupported");
+        }
+        if (this.#protocol !== undefined && this.#protocol !== version) {
+            this.close();
+            fail("mcp_protocol_conflict");
+        }
+        this.#protocol = version;
+    }
+    onNotification(notification) {
+        if (notification.method === "notifications/tools/list_changed")
+            this.#revision++;
+    }
+    close() { this.#closed = true; }
+    get revision() { return this.#revision; }
+    get protocolVersion() { return this.#protocol; }
+    check(revision) {
+        if (this.#closed)
+            fail("mcp_connection_closed");
+        if (this.#protocol === undefined)
+            fail("mcp_not_initialized");
+        if (revision !== this.#revision)
+            fail("mcp_catalog_stale");
+    }
+}
+function stopped(signal) { if (signal?.aborted)
+    throw new AgentCanceledError(); }
+async function request(operation, signal) {
+    stopped(signal);
+    try {
+        return await operation();
+    }
+    catch (error) {
+        stopped(signal);
+        if (error instanceof McpError) {
+            if (error.code === ErrorCode.RequestTimeout)
+                fail("mcp_timeout");
+            if (error.code === ErrorCode.ConnectionClosed)
+                fail("mcp_transport_error");
+            fail("mcp_protocol_error");
+        }
+        if (error !== null && typeof error === "object" && "name" in error
+            && (error.name === "ZodError" || error.name === "$ZodError"))
+            fail("mcp_result_invalid");
+        fail("mcp_transport_error");
+    }
+}
+async function contract(schema, limits) {
+    try {
+        return await StructuredOutputContract.create({ schemaId: "mcp.object", schemaVersion: "1", schema,
+            limits: { schemaBytes: limits.maxSchemaBytes, outputBytes: limits.maxResultBytes } });
+    }
+    catch {
+        return fail("mcp_schema_unsupported");
+    }
+}
+async function remoteContract(schema, limits) {
+    // Keep the recognized MCP root dialect in snapshot identity, outside the constraint profile.
+    if (size(schema) > limits.maxSchemaBytes)
+        fail("mcp_schema_unsupported");
+    const declared = Object.hasOwn(schema, "$schema");
+    if (declared && schema.$schema !== "https://json-schema.org/draft/2020-12/schema")
+        fail("mcp_schema_unsupported");
+    const compiled = await contract(Object.fromEntries(Object.entries(schema).filter(([key]) => key !== "$schema")), limits);
+    const snapshot = declared ? Object.freeze({ ...compiled.schema, $schema: schema.$schema }) : compiled.schema;
+    return { compiled, snapshot };
+}
+function resultValue(raw, output, envelope, limits) {
+    if (raw.isError)
+        fail("mcp_tool_error");
+    if (raw.content.length > limits.maxContentBlocks || size(raw) > limits.maxResultBytes)
+        fail("mcp_result_too_large");
+    const text = [];
+    for (const block of raw.content) {
+        if (block.type !== "text")
+            fail("mcp_result_unsupported");
+        text.push(block.text);
+    }
+    try {
+        const value = envelope.validateValue({ text, structured: raw.structuredContent ?? null });
+        output?.validateValue(raw.structuredContent ?? null);
+        return value;
+    }
+    catch (error) {
+        if (error instanceof StructuredOutputError)
+            fail("mcp_result_invalid");
+        throw error;
+    }
+}
+export async function discoverMcpTools(client, serverId, bindings, options) {
+    const monitor = options.monitor;
+    const limits = limitsOf(options.limits);
+    if (!(client instanceof Client) || !(monitor instanceof McpCatalogMonitor)
+        || typeof serverId !== "string" || !/^[A-Za-z0-9_.-]{1,128}$/.test(serverId)
+        || !bindings || typeof bindings !== "object" || Array.isArray(bindings))
+        fail("mcp_binding_invalid");
+    const bound = new Map();
+    const localNames = new Set();
+    for (const [remote, binding] of Object.entries(bindings)) {
+        if (!/^[A-Za-z0-9_.-]{1,128}$/.test(remote) || !binding || typeof binding.localName !== "string"
+            || !/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(binding.localName) || binding.policy?.mode !== "read"
+            || binding.policy.riskLevel !== undefined && binding.policy.riskLevel !== "read"
+            || typeof binding.policy.title !== "string" || !binding.policy.title.trim()
+            || binding.scope !== null && typeof binding.scope !== "function"
+            || binding.concurrencySafe !== undefined && typeof binding.concurrencySafe !== "boolean")
+            fail("mcp_binding_invalid");
+        if (localNames.has(binding.localName))
+            fail("mcp_name_conflict");
+        localNames.add(binding.localName);
+        bound.set(remote, Object.freeze({ ...binding, policy: Object.freeze({ mode: "read", title: binding.policy.title.trim(), riskLevel: "read" }) }));
+    }
+    if (bound.size === 0 || bound.size > limits.maxTools)
+        fail("mcp_binding_invalid");
+    const revision = monitor.revision;
+    monitor.check(revision);
+    if (client.getServerCapabilities()?.tools === undefined || client.transport === undefined)
+        fail("mcp_tools_unavailable");
+    const envelope = await contract({ type: "object" }, limits);
+    const seen = new Set(), cursors = new Set();
+    const found = new Map();
+    let cursor, totalBytes = 0, finished = false;
+    const requestOptions = { timeout: limits.timeoutMs, maxTotalTimeout: limits.timeoutMs,
+        ...(options.signal === undefined ? {} : { signal: options.signal }) };
+    for (let page = 0; page < limits.maxPages; page++) {
+        monitor.check(revision);
+        // Do not use callTool/listTools convenience caches or implicit rediscovery.
+        const result = await request(() => client.request({ method: "tools/list", ...(cursor === undefined ? {} : { params: { cursor } }) }, ListToolsResultSchema, requestOptions), options.signal);
+        monitor.check(revision);
+        totalBytes += size(result);
+        if (totalBytes > limits.maxCatalogBytes || seen.size + result.tools.length > limits.maxTools)
+            fail("mcp_catalog_limit_exceeded");
+        for (const tool of result.tools) {
+            if (seen.has(tool.name))
+                fail("mcp_name_conflict");
+            seen.add(tool.name);
+            const binding = bound.get(tool.name);
+            if (binding === undefined)
+                continue;
+            const description = tool.description ?? "";
+            if (encoder.encode(description).length > limits.maxDescriptionBytes)
+                fail("mcp_catalog_limit_exceeded");
+            if (tool.execution?.taskSupport === "required")
+                fail("mcp_tool_unsupported");
+            const inputContract = await remoteContract(tool.inputSchema, limits);
+            const outputContract = tool.outputSchema === undefined ? undefined : await remoteContract(tool.outputSchema, limits);
+            const input = inputContract.compiled, output = outputContract?.compiled;
+            const entry = Object.freeze({ remoteName: tool.name, localName: binding.localName, description,
+                inputSchema: inputContract.snapshot, outputSchema: outputContract?.snapshot ?? null,
+                policy: Object.freeze({ mode: "read", title: binding.policy.title, riskLevel: "read" }), concurrencySafe: binding.concurrencySafe ?? false });
+            found.set(tool.name, { entry, binding, input, output });
+        }
+        cursor = result.nextCursor;
+        if (cursor === undefined) {
+            finished = true;
+            break;
+        }
+        if (!cursor || encoder.encode(cursor).length > 512 || cursors.has(cursor))
+            fail("mcp_pagination_invalid");
+        cursors.add(cursor);
+    }
+    if (!finished)
+        fail("mcp_catalog_limit_exceeded");
+    if (found.size !== bound.size)
+        fail("mcp_binding_missing");
+    const ordered = [...found.entries()].sort((a, b) => a[1].entry.localName < b[1].entry.localName ? -1 : 1);
+    const identity = Object.freeze({ schemaVersion: 1, serverId, protocolVersion: monitor.protocolVersion,
+        entries: Object.freeze(ordered.map(([, row]) => row.entry)) });
+    let revisionDigest;
+    try {
+        revisionDigest = await jsonIdentityDigest(identity);
+    }
+    catch {
+        return fail("mcp_catalog_limit_exceeded");
+    }
+    const snapshot = Object.freeze({ ...identity, revisionDigest });
+    const registrations = Object.freeze(ordered.map(([remote, row]) => {
+        const scope = async (input, context) => {
+            monitor.check(revision);
+            stopped(context.signal);
+            return row.binding.scope?.(input, context);
+        };
+        return Object.freeze({ name: row.entry.localName, description: row.entry.description || row.binding.policy.title,
+            inputSchema: row.input.schema, argumentContract: row.input, policy: row.binding.policy, concurrencySafe: row.entry.concurrencySafe,
+            scope, async run(input, context) {
+                try {
+                    monitor.check(revision);
+                    let value;
+                    try {
+                        value = row.input.validateValue(input);
+                    }
+                    catch {
+                        return { content: { text: [], structured: null }, effectState: "not_started", errorCode: "mcp_invalid_arguments" };
+                    }
+                    const decision = await scope(value, context);
+                    if (decision === false || typeof decision === "string" && decision.trim())
+                        fail("mcp_scope_denied");
+                    monitor.check(revision);
+                    stopped(context.signal);
+                    const result = await request(() => client.request({ method: "tools/call", params: { name: remote, arguments: value } }, CallToolResultSchema, { timeout: limits.timeoutMs, maxTotalTimeout: limits.timeoutMs, ...(context.signal === undefined ? {} : { signal: context.signal }) }), context.signal);
+                    monitor.check(revision);
+                    return { content: resultValue(result, row.output, envelope, limits), effectState: "not_started" };
+                }
+                catch (error) {
+                    if (error instanceof McpAdapterError)
+                        return { content: { text: [], structured: null }, effectState: "not_started", errorCode: error.code };
+                    throw error;
+                }
+            },
+        });
+    }));
+    monitor.check(revision);
+    return Object.freeze({ snapshot, registrations, get stale() { try {
+            monitor.check(revision);
+            return false;
+        }
+        catch {
+            return true;
+        } } });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "purra-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Host-owned, read-only MCP tools for PurrA",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0"
+  },
+  "peerDependencies": {
+    "purra": "1.0.0"
+  },
+  "devDependencies": {
+    "purra": "file:../../../typescript",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "check": "npm run build && npm test && npm run test:types",
+    "prepack": "npm run build",
+    "test:types": "tsc -p test/tsconfig.json"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}