@sheafhq/mcp-tools 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @sheafhq/mcp-tools
 
-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.
+MCP server exposing three Sheaf read tools to any MCP-compatible agent:
+
+| Tool | Purpose |
+| --- | --- |
+| `sheaf_chain_head` | Fetch the current head of a Sheaf chain (seq + hash). |
+| `sheaf_get_proof_for` | Fetch a Merkle inclusion proof + on-chain anchor reference for a specific event. |
+| `sheaf_verify_bundle` | Verify a Sheaf receipt bundle end-to-end (signature, Merkle inclusion, anchor tx). |
+
+All three are **read-only and free**. No wallet, no payment, no mutation.
+
+For event *capture* (transparently recording every tool call an agent makes), use the companion package [`@sheafhq/mcp-recorder`](https://www.npmjs.com/package/@sheafhq/mcp-recorder). It stays a pure proxy; this package is a separate, opt-in tool surface.
+
+## Install
+
+```bash
+npm install -g @sheafhq/mcp-tools
+```
+
+## Use with Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sheaf-tools": {
+      "command": "sheaf-mcp-tools"
+    }
+  }
+}
+```
+
+## Env vars
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `SHEAF_RECORDER_URL` | `https://sheaf-recorder.goldencalf.workers.dev` | Recorder host to query. |
+| `SHEAF_BASE_RPC` | `https://mainnet.base.org` | Base mainnet RPC used by `sheaf_verify_bundle` to read the anchor tx. |
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// CLI entry for sheaf-mcp-tools. Spawned by an MCP-compatible client
+// (Claude Desktop, Cline, custom runtime) and speaks JSON-RPC over stdio.
+//
+// Environment variables (all optional):
+//   SHEAF_RECORDER_URL   where to query (default: production recorder)
+//   SHEAF_BASE_RPC       Base mainnet RPC for anchor verification
+//                        (default: https://mainnet.base.org)
+import { runServer } from "./server.js";
+const ctx = {
+    recorderUrl: process.env.SHEAF_RECORDER_URL ??
+        "https://sheaf-recorder.goldencalf.workers.dev",
+    baseRpc: process.env.SHEAF_BASE_RPC ?? "https://mainnet.base.org",
+};
+runServer(ctx);

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { type ToolContext } from "./tools.js";
+export declare function runServer(ctx: ToolContext): void;

package/dist/server.js

@@ -0,0 +1,200 @@
+// Stdio MCP server. Reads JSON-RPC lines from stdin, writes responses to
+// stdout. No SSE / HTTP transport — this is designed to be launched by an
+// MCP-compatible client (Claude Desktop, Cline, etc.) and speak JSON-RPC
+// directly over stdio.
+import { createInterface } from "node:readline";
+import { chainHead, getProofFor, verifyBundle, } from "./tools.js";
+// Tool definitions sent in reply to tools/list. The decider model chooses
+// among these entirely from the description + inputSchema — so the
+// descriptions below are the product, not a doc. Every field documented;
+// an example call + example response in each description.
+const TOOL_DEFS = [
+    {
+        name: "sheaf_chain_head",
+        description: [
+            "Return the current head (latest sequence number + hash) of a Sheaf chain.",
+            "",
+            "WHEN TO USE: You have a chain_id (an agent-run identifier recorded on Sheaf) and want to check what the latest event is, how many events exist, or whether the chain exists at all. Common uses: verify that your own agent's events reached the recorder; synchronize local state after a crash; prove to an auditor that no events were recorded on a given chain.",
+            "",
+            "WHEN NOT TO USE: You want to verify a specific receipt — use sheaf_verify_bundle instead. You want to prove an event is anchored on-chain — use sheaf_get_proof_for. You want to CREATE a new event — this tool is read-only; events are created transparently by the @sheafhq/mcp-recorder proxy.",
+            "",
+            "EXAMPLE CALL:",
+            '  { "chain_id": "agent-run-2026-11-11-smoke" }',
+            "",
+            "EXAMPLE RESPONSE:",
+            '  { "chain_id": "agent-run-2026-11-11-smoke", "head_seq": 42, "head_hash": "26795706...4951f12", "event_count": 43, "created_at_unix": 1794367540, "updated_at_unix": 1794367611, "source_url": "https://sheaf-recorder.goldencalf.workers.dev/chains/agent-run-2026-11-11-smoke/head" }',
+            "",
+            "If the chain does not exist (no events recorded), returns { head: null, note: ... } with HTTP 200. Free; no payment required.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                chain_id: {
+                    type: "string",
+                    description: "Stable identifier the recorder uses to group related events in order. Typically matches what the operator set in SHEAF_CHAIN_ID when running the recorder. Required.",
+                },
+            },
+            required: ["chain_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "sheaf_get_proof_for",
+        description: [
+            "Return a Merkle inclusion proof for one specific event (chain_id + seq) along with its on-chain anchor reference.",
+            "",
+            "WHEN TO USE: You want to prove to a third party that a specific recorded event is included in the Sheaf chain and committed on Base mainnet. Common uses: attach compliance evidence to an agent output; selectively disclose one action from a longer chain; let an external auditor independently check the proof against the on-chain anchor.",
+            "",
+            "WHEN NOT TO USE: You want to verify a receipt the other party already sent you — use sheaf_verify_bundle. You want to query chain state generally — use sheaf_chain_head. You want to buy the bundled + self-contained artifact — call GET /bundle/:chain_id/:seq on the recorder with an x402 payment ($0.001 USDC on Base); this tool returns the proof components for free but does not include the full signed envelope.",
+            "",
+            "EXAMPLE CALL:",
+            '  { "chain_id": "agent-run-2026-11-11-smoke", "seq": 7 }',
+            "",
+            "EXAMPLE RESPONSE (anchored):",
+            '  { "status": "anchored", "chain_id": "agent-run-...", "seq": 7, "epoch_id": 42, "leaf": "sha256:...", "leaf_index": 3, "merkle_root": "...", "siblings": [{"hash": "...", "side": "right"}, ...], "anchor": { "tx_hash": "0xc65349...", "block": 55369354, "explorer": "https://basescan.org/tx/0xc65349..." }, "verification_note": "..." }',
+            "",
+            "If the event exists but is not yet in a sealed epoch, returns { status: \"not_yet_anchored\", envelope_hash: ..., note: ... }; retry after the next epoch anchor. Free; no payment required.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                chain_id: {
+                    type: "string",
+                    description: "Chain identifier. Required.",
+                },
+                seq: {
+                    type: "integer",
+                    minimum: 0,
+                    description: "Sequence number of the event within the chain (0-indexed). Required.",
+                },
+            },
+            required: ["chain_id", "seq"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "sheaf_verify_bundle",
+        description: [
+            "Verify a Sheaf receipt bundle end-to-end: signature, Merkle inclusion, and on-chain anchor. Pure read; makes one RPC call to Base to confirm the anchor transaction, no payment required.",
+            "",
+            "WHEN TO USE: A counterparty, auditor, or upstream agent gave you a Sheaf bundle (version sheaf-bundle/1 from the paid /bundle endpoint, or the legacy {envelope, inclusion_proof, anchor_tx_hash} shape) and you need to confirm it is authentic and intact BEFORE acting on its contents. Common uses: gate agent workflows on independently verified evidence; log a receipt into your own audit trail only after validation; reject counterfeit or tampered bundles before they influence downstream decisions.",
+            "",
+            "WHEN NOT TO USE: You just want to look up what events exist — use sheaf_chain_head. You want a proof but don't have a bundle — use sheaf_get_proof_for. You want to CREATE a bundle for one of your own events — call GET /bundle/:chain_id/:seq on the recorder with an x402 payment.",
+            "",
+            "EXAMPLE CALL:",
+            '  { "bundle": { "version": "sheaf-bundle/1", "envelope": {...}, "envelope_hash": "...", "anchor": {...}, "issuer": {...}, ... } }',
+            "",
+            "EXAMPLE RESPONSE:",
+            '  { "valid": true, "checks": { "anchor_on_chain": true, "anchor_from_authorized_wallet": true, "merkle_root_matches_on_chain": true, "inclusion_proof_reproduces_root": true, "envelope_hash_matches_leaf": true, "recorder_signature_verifies": true, "chain_prev_hash_matches": null }, "anchor_block": 55369354, "recorder": "https://sheaf-recorder.goldencalf.workers.dev", "anchorer_checked": "0x08A22c..." }',
+            "",
+            "If any check fails, returns { valid: false, checks: {...}, reason: \"...\" } with the specific invariant that failed. Treat valid=false as evidence of tampering, forgery, or wrong-issuer verification — do not use the bundle's contents.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                bundle: {
+                    type: "object",
+                    description: "The Sheaf bundle to verify. Accepts the sheaf-bundle/1 shape (preferred) or the legacy { envelope, inclusion_proof, anchor_tx_hash } shape. Required.",
+                },
+                anchorer_address: {
+                    type: "string",
+                    description: "Optional. 0x-prefixed Ethereum address expected to have sent the anchor tx. Defaults to the canonical sheaf-recorder anchorer. Only override this if verifying against a non-default Sheaf deployment.",
+                },
+            },
+            required: ["bundle"],
+            additionalProperties: false,
+        },
+    },
+];
+function ok(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function err(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+}
+async function handle(req, ctx) {
+    const id = req.id ?? null;
+    switch (req.method) {
+        case "initialize":
+            return ok(id, {
+                protocolVersion: "2025-03-26",
+                capabilities: { tools: {} },
+                serverInfo: { name: "sheaf-mcp-tools", version: "0.1.0" },
+            });
+        case "tools/list":
+            return ok(id, { tools: TOOL_DEFS });
+        case "tools/call": {
+            const params = (req.params ?? {});
+            const args = params.arguments ?? {};
+            try {
+                let data;
+                switch (params.name) {
+                    case "sheaf_chain_head":
+                        data = await chainHead(ctx, args);
+                        break;
+                    case "sheaf_get_proof_for":
+                        data = await getProofFor(ctx, args);
+                        break;
+                    case "sheaf_verify_bundle":
+                        data = await verifyBundle(ctx, args);
+                        break;
+                    default:
+                        return ok(id, {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `unknown tool: ${params.name}`,
+                                },
+                            ],
+                            isError: true,
+                        });
+                }
+                return ok(id, {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                    isError: false,
+                });
+            }
+            catch (e) {
+                return ok(id, {
+                    content: [
+                        {
+                            type: "text",
+                            text: `error: ${e.message}`,
+                        },
+                    ],
+                    isError: true,
+                });
+            }
+        }
+        case "notifications/initialized":
+        case "notifications/cancelled":
+            // Notifications have no response.
+            return null;
+        default:
+            return err(id, -32601, `method not found: ${req.method}`);
+    }
+}
+export function runServer(ctx) {
+    const rl = createInterface({ input: process.stdin });
+    rl.on("line", (line) => {
+        if (!line.trim())
+            return;
+        let req;
+        try {
+            req = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        // Do not await inline — concurrent in-flight requests are allowed.
+        handle(req, ctx)
+            .then((res) => {
+            if (res)
+                process.stdout.write(JSON.stringify(res) + "\n");
+        })
+            .catch((e) => {
+            process.stdout.write(JSON.stringify(err(req.id ?? null, -32603, e.message)) +
+                "\n");
+        });
+    });
+}

package/dist/tools.d.ts

@@ -0,0 +1,15 @@
+export type ToolContext = {
+    recorderUrl: string;
+    baseRpc: string;
+};
+export declare function chainHead(ctx: ToolContext, args: {
+    chain_id: string;
+}): Promise<unknown>;
+export declare function getProofFor(ctx: ToolContext, args: {
+    chain_id: string;
+    seq: number;
+}): Promise<unknown>;
+export declare function verifyBundle(ctx: ToolContext, args: {
+    bundle: unknown;
+    anchorer_address?: string;
+}): Promise<unknown>;

package/dist/tools.js

@@ -0,0 +1,142 @@
+// Tool implementations. Each returns either a plain object (serialized to
+// JSON text content for the MCP response) or throws, in which case the
+// server translates it to an MCP error response.
+//
+// All three tools are READ-only against the Sheaf recorder. No wallet, no
+// settlement, no mutation. Safe to expose to any agent.
+import { verify } from "@sheafhq/verify";
+export async function chainHead(ctx, args) {
+    if (!args.chain_id || typeof args.chain_id !== "string") {
+        throw new Error("chain_id (string) is required");
+    }
+    const url = `${ctx.recorderUrl}/chains/${encodeURIComponent(args.chain_id)}/head`;
+    const r = await fetch(url);
+    if (r.status === 404) {
+        return {
+            chain_id: args.chain_id,
+            head: null,
+            note: "No events have been recorded on this chain yet.",
+        };
+    }
+    if (!r.ok) {
+        throw new Error(`recorder returned HTTP ${r.status}`);
+    }
+    const body = (await r.json());
+    return {
+        chain_id: body.chain_id,
+        head_seq: body.head_seq,
+        head_hash: body.head_hash,
+        event_count: body.event_count,
+        created_at_unix: body.created_at,
+        updated_at_unix: body.updated_at,
+        source_url: url,
+    };
+}
+export async function getProofFor(ctx, args) {
+    if (!args.chain_id || typeof args.chain_id !== "string") {
+        throw new Error("chain_id (string) is required");
+    }
+    if (!Number.isInteger(args.seq) || args.seq < 0) {
+        throw new Error("seq (non-negative integer) is required");
+    }
+    // First find out which epoch the event is in.
+    const evUrl = `${ctx.recorderUrl}/events/${encodeURIComponent(args.chain_id)}/${args.seq}`;
+    const evRes = await fetch(evUrl);
+    if (evRes.status === 404) {
+        throw new Error(`no event at ${args.chain_id}/${args.seq}`);
+    }
+    if (!evRes.ok) {
+        throw new Error(`recorder returned HTTP ${evRes.status} on event lookup`);
+    }
+    const ev = (await evRes.json());
+    if (ev.epoch_id === null) {
+        return {
+            status: "not_yet_anchored",
+            chain_id: args.chain_id,
+            seq: args.seq,
+            envelope_hash: ev.envelope_hash,
+            note: "Event is signed and chained but not yet included in an on-chain anchor. Call again after the next epoch anchor to get a Merkle inclusion proof.",
+        };
+    }
+    const proofUrl = `${ctx.recorderUrl}/epoch/${ev.epoch_id}/proof/${encodeURIComponent(args.chain_id)}/${args.seq}`;
+    const proofRes = await fetch(proofUrl);
+    if (!proofRes.ok) {
+        throw new Error(`recorder returned HTTP ${proofRes.status} on proof fetch`);
+    }
+    const proof = (await proofRes.json());
+    return {
+        status: "anchored",
+        chain_id: proof.chain_id,
+        seq: proof.seq,
+        epoch_id: proof.epoch_id,
+        leaf: proof.leaf,
+        leaf_index: proof.leaf_index,
+        merkle_root: proof.merkle_root,
+        siblings: proof.siblings,
+        anchor: proof.anchor,
+        verification_note: proof.verification_note,
+        source_url: proofUrl,
+    };
+}
+export async function verifyBundle(ctx, args) {
+    if (!args.bundle || typeof args.bundle !== "object") {
+        throw new Error("bundle (object) is required");
+    }
+    const b = args.bundle;
+    // Normalize both shapes to the one @sheafhq/verify expects.
+    let verifyInput;
+    if (b.version === "sheaf-bundle/1" && b.envelope && b.anchor && b.envelope_hash) {
+        verifyInput = {
+            envelope: b.envelope,
+            inclusion_proof: {
+                leaf: b.envelope_hash,
+                leaf_index: b.anchor.leaf_index ?? 0,
+                merkle_root: b.anchor.merkle_root ?? "",
+                siblings: b.anchor.siblings ?? [],
+            },
+            anchor_tx_hash: b.anchor.tx_hash ?? "",
+        };
+    }
+    else if (b.envelope && b.inclusion_proof && b.anchor_tx_hash) {
+        verifyInput = {
+            envelope: b.envelope,
+            inclusion_proof: b.inclusion_proof,
+            anchor_tx_hash: b.anchor_tx_hash,
+        };
+    }
+    else {
+        throw new Error("bundle shape not recognized; expected sheaf-bundle/1 or legacy {envelope, inclusion_proof, anchor_tx_hash}");
+    }
+    // Pull recorder public key. Prefer the key embedded in the bundle so the
+    // verification is self-contained; fall back to /.well-known if missing.
+    let recorderKey = b.issuer?.public_key_base64 ?? "";
+    if (!recorderKey) {
+        const r = await fetch(`${ctx.recorderUrl}/.well-known/sheaf-public-key`);
+        if (!r.ok) {
+            throw new Error(`could not fetch recorder public key: HTTP ${r.status}`);
+        }
+        const pk = (await r.json());
+        const active = pk.keys.find((k) => k.key_id === pk.active_key_id);
+        if (!active)
+            throw new Error("recorder public key not found in keyring");
+        recorderKey = active.public_key_base64;
+    }
+    // Anchorer address: caller may override; else default to the canonical
+    // sheaf-recorder anchorer. (Kept hardcoded here rather than exposing it
+    // as another remote fetch — any mismatch means the caller is verifying
+    // against the wrong issuer, which is itself a useful failure mode.)
+    const anchorer = args.anchorer_address ?? "0x08A22c6899a8b2eccA4b2B752a89eD498d7b2100";
+    const result = await verify(verifyInput, {
+        base_rpc: ctx.baseRpc,
+        recorder_public_key_base64: recorderKey,
+        expected_anchorer_address: anchorer,
+    });
+    return {
+        valid: result.valid,
+        checks: result.checks,
+        reason: result.reason,
+        anchor_block: result.anchor_block,
+        recorder: ctx.recorderUrl,
+        anchorer_checked: anchorer,
+    };
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@sheafhq/mcp-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP server exposing Sheaf read tools (chain_head, get_proof_for, verify_bundle). Lets any MCP-compatible agent query the Sheaf recorder and verify receipts offline. Pairs with @sheafhq/mcp-recorder (transparent event capture) but ships as a separate, opt-in tool surface so the recorder stays purely transparent.",
+  "type": "module",
+  "main": "./dist/cli.js",
+  "bin": {
+    "sheaf-mcp-tools": "dist/cli.js"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sheaf",
+    "mcp",
+    "mcp-server",
+    "audit",
+    "attestation",
+    "agent",
+    "verification",
+    "receipt",
+    "merkle-proof",
+    "evidence"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sheafhq/sheaf.git",
+    "directory": "packages/mcp-tools"
+  },
+  "homepage": "https://github.com/sheafhq/sheaf/tree/main/packages/mcp-tools",
+  "bugs": {
+    "url": "https://github.com/sheafhq/sheaf/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sheafhq/verify": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0",
+    "@anthropic-ai/sdk": "^0.33.0"
+  }
+}