purra-mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # purra-mcp (TypeScript)
 
-Development package for explicitly authorized, read-only MCP tools. Requires
+Development package for host-authorized MCP read tools and durable approval-gated writes. 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.
@@ -88,8 +88,8 @@ 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.
+absence of host writes for read bindings, not whether a network request was sent.
+The separate write entry point below classifies uncertain effects conservatively.
 
 Shared fixtures run against the official local client/server protocol, with a
 JSON serialization boundary. The installed smoke also launches and closes a
@@ -126,3 +126,82 @@ HTTP connection failures (including `fetch` transport `TypeError`) return
 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.
+
+## Durable writes (1.0 development)
+
+The separate write discovery entry point requires explicit host authorization:
+confirm policy, matching `write` or `destructive` effect, a callable scope validator,
+and nonempty binding/scope IDs and revisions. Server annotations never grant this
+permission. Read discovery keeps its 1.0 contract and schema-1 snapshot. Write
+snapshots use schema 2 and include the host authorization identity; concurrency
+is disabled for these tools.
+
+```ts
+import { discoverMcpWriteTools } from "purra-mcp";
+
+const writes = await discoverMcpWriteTools(client, "documents", {
+  "remote.update": {
+    localName: "update_document",
+    policy: { mode: "confirm", title: "Update document", riskLevel: "write" },
+    scope: validateCurrentDocumentScope,
+    bindingId: "document-service", bindingRevision: "host-config-1",
+    scopeId: "sandbox-documents", scopeRevision: "scope-1", effect: "write",
+  },
+}, { monitor });
+const identity = writes.registrations[0]!.approvalBinding!;
+```
+
+In `toolCheckpointHandler`, spread the current `identity` into `ApprovalIntent.create`
+alongside the actual checkpoint call and current Run preset fingerprint, then call
+`approvals.prepare`. Configure Agent with `approval: approvals.gateway()`,
+`idempotency: storage.idempotency`, and `toolCheckpointNames: ["update_document"]`.
+
+The registration's effective binding revision is the complete write catalog digest,
+which includes the original host binding revision, server identity, selected schemas,
+and scope identity. Do not substitute the original host revision or reuse old binding
+metadata after rediscovery. Core requires a durable approval gateway and its exact
+receipt store, and the SQLite gateway checks the current registration identity against
+the approved intent before dispatch. A live in-memory approval gateway is insufficient.
+The handler function is an adapter implementation; applications execute it through
+Core's tool catalog, never as a substitute for approval/claim checks.
+
+A validated success response records `committed`. Local argument/scope/catalog
+rejection before sending records `not_started`. Once a request is submitted,
+timeout, cancellation, disconnect, catalog changes, RPC errors, `isError` responses,
+and invalid/unsupported output record `unknown`. An error response cannot prove
+that no remote write occurred. Unknown effects retain their durable claim; the
+adapter never retries or automatically reconciles them. Host reconciliation requires
+independent evidence. A successful remote response is protocol completion evidence,
+not a read-back audit of the business data.
+
+The protocol tests include SQLite approval restart, current-binding mismatch,
+scope revocation, committed receipts and retained unknown claims against a synthetic
+SDK server. Build the sibling Core and SQLite packages before TypeScript tests; include
+Core, MCP and SQLite source directories on `PYTHONPATH` for Python tests. These are
+deterministic local tests, separate from real Provider/MCP service and downstream
+acceptance. See [durable approval](../../../conformance/durable-approval.md).
+
+## Independent write-server acceptance
+
+The repository's installed-consumer check now runs five scenarios against the
+separate Python SDK process in `integrations/mcp/fixtures/write_server.py`:
+success, lost response, exit before write, exit after write, and an error response
+after write. The server accepts only a fixed synthetic value, writes inside a
+fresh temporary directory, and fsyncs an independent event ledger. The host waits
+for durable approval, reopens SQLite before approving, then checks both the local
+receipt/unknown claim and the remote file. Reopening after completion/failure must
+not dispatch again. Every scenario verifies that the server process has exited.
+
+Copy `scripts/check-installed-write.mjs` into an independent npm consumer
+containing matching Core, SQLite and MCP tarballs. Use a Python environment
+containing the pinned `mcp` SDK for the fixture server:
+
+```sh
+node check-installed-write.mjs /absolute/path/to/write_server.py /absolute/path/to/python
+```
+
+These are controlled independent-service fault checks, using a scripted model.
+They do not prove real Provider capability or third-party business-service
+acceptance. The remote ledger is verification evidence, never an approval or
+automatic reconciliation command. The CI workflow includes both consumers;
+local success does not claim that remote CI has executed.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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";
+import { AgentError, type ToolApprovalBinding, type JsonValue, type ToolDefinition, type ToolPolicy } from "purra";
 export declare class McpAdapterError extends AgentError {
     constructor(code: string);
 }
@@ -30,6 +30,27 @@ export interface McpToolBinding {
     readonly scope: NonNullable<ToolDefinition["scope"]> | null;
     readonly concurrencySafe?: boolean;
 }
+export interface McpWriteToolBinding extends ToolApprovalBinding {
+    readonly localName: string;
+    readonly policy: Readonly<{
+        mode: "confirm";
+        title: string;
+        riskLevel: "write" | "destructive";
+    }>;
+    readonly scope: NonNullable<ToolDefinition["scope"]>;
+    readonly concurrencySafe?: false;
+}
+export interface McpWriteToolEntry extends Omit<McpToolEntry, "policy"> {
+    readonly policy: McpWriteToolBinding["policy"];
+    readonly authorization: ToolApprovalBinding;
+}
+export interface McpWriteToolSnapshot extends Omit<McpToolSnapshot, "schemaVersion" | "entries"> {
+    readonly schemaVersion: 2;
+    readonly entries: readonly McpWriteToolEntry[];
+}
+export interface McpWriteToolCatalog extends Omit<McpToolCatalog, "snapshot"> {
+    readonly snapshot: McpWriteToolSnapshot;
+}
 export interface McpToolEntry {
     readonly remoteName: string;
     readonly localName: string;
@@ -61,3 +82,4 @@ export interface McpDiscoveryOptions {
     readonly signal?: AbortSignal;
 }
 export declare function discoverMcpTools(client: Client, serverId: string, bindings: Readonly<Record<string, McpToolBinding>>, options: McpDiscoveryOptions): Promise<McpToolCatalog>;
+export declare function discoverMcpWriteTools(client: Client, serverId: string, bindings: Readonly<Record<string, McpWriteToolBinding>>, options: McpDiscoveryOptions): Promise<McpWriteToolCatalog>;

package/dist/index.js

@@ -116,6 +116,12 @@ function resultValue(raw, output, envelope, limits) {
     }
 }
 export async function discoverMcpTools(client, serverId, bindings, options) {
+    return await discover(client, serverId, bindings, options, false);
+}
+export async function discoverMcpWriteTools(client, serverId, bindings, options) {
+    return await discover(client, serverId, bindings, options, true);
+}
+async function discover(client, serverId, bindings, options, writing) {
     const monitor = options.monitor;
     const limits = limitsOf(options.limits);
     if (!(client instanceof Client) || !(monitor instanceof McpCatalogMonitor)
@@ -126,16 +132,28 @@ export async function discoverMcpTools(client, serverId, bindings, options) {
     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"
+            || !/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(binding.localName) || binding.policy?.mode !== (writing ? "confirm" : "read")
+            || !writing && 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");
+        let authorization;
+        if (writing) {
+            const write = binding;
+            if (!["write", "destructive"].includes(write.effect) || write.policy.riskLevel !== write.effect
+                || typeof write.scope !== "function" || write.concurrencySafe !== undefined && write.concurrencySafe !== false
+                || ![write.bindingId, write.bindingRevision, write.scopeId, write.scopeRevision]
+                    .every(text => typeof text === "string" && text.length > 0 && [...text].length <= 1024 && text.trim() === text))
+                fail("mcp_binding_invalid");
+            authorization = Object.freeze({ bindingId: write.bindingId, bindingRevision: write.bindingRevision,
+                scopeId: write.scopeId, scopeRevision: write.scopeRevision, effect: write.effect });
+        }
         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" }) }));
+        bound.set(remote, Object.freeze({ ...binding, ...(authorization === undefined ? {} : { authorization }),
+            policy: Object.freeze({ mode: writing ? "confirm" : "read", title: binding.policy.title.trim(), riskLevel: authorization?.effect ?? "read" }) }));
     }
     if (bound.size === 0 || bound.size > limits.maxTools)
         fail("mcp_binding_invalid");
@@ -174,7 +192,8 @@ export async function discoverMcpTools(client, serverId, bindings, options) {
             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 });
+                policy: binding.policy, concurrencySafe: binding.concurrencySafe ?? false,
+                ...(binding.authorization === undefined ? {} : { authorization: binding.authorization }) });
             found.set(tool.name, { entry, binding, input, output });
         }
         cursor = result.nextCursor;
@@ -191,7 +210,7 @@ export async function discoverMcpTools(client, serverId, bindings, options) {
     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,
+    const identity = Object.freeze({ schemaVersion: writing ? 2 : 1, serverId, protocolVersion: monitor.protocolVersion,
         entries: Object.freeze(ordered.map(([, row]) => row.entry)) });
     let revisionDigest;
     try {
@@ -209,7 +228,9 @@ export async function discoverMcpTools(client, serverId, bindings, options) {
         };
         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,
+            ...(row.binding.authorization === undefined ? {} : { approvalBinding: Object.freeze({ ...row.binding.authorization, bindingRevision: revisionDigest }) }),
             scope, async run(input, context) {
+                let dispatched = false;
                 try {
                     monitor.check(revision);
                     let value;
@@ -224,13 +245,16 @@ export async function discoverMcpTools(client, serverId, bindings, options) {
                         fail("mcp_scope_denied");
                     monitor.check(revision);
                     stopped(context.signal);
+                    dispatched = true;
                     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" };
+                    return { content: resultValue(result, row.output, envelope, limits), effectState: writing ? "committed" : "not_started" };
                 }
                 catch (error) {
                     if (error instanceof McpAdapterError)
-                        return { content: { text: [], structured: null }, effectState: "not_started", errorCode: error.code };
+                        return { content: { text: [], structured: null }, effectState: writing && dispatched ? "unknown" : "not_started", errorCode: error.code };
+                    if (writing && dispatched && error instanceof AgentCanceledError)
+                        return { content: { text: [], structured: null }, effectState: "unknown", errorCode: "mcp_canceled" };
                     throw error;
                 }
             },

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "purra-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "license": "MIT",
-  "description": "Host-owned, read-only MCP tools for PurrA",
+  "description": "Host-owned MCP tools with durable write approvals for PurrA",
   "files": [
     "dist",
     "README.md",
@@ -19,7 +19,7 @@
     "@modelcontextprotocol/sdk": "1.30.0"
   },
   "peerDependencies": {
-    "purra": "1.0.0"
+    "purra": "1.0.1"
   },
   "devDependencies": {
     "purra": "file:../../../typescript",