@sheafhq/mcp-recorder 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @sheafhq/mcp-recorder
 
-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.
+Transparent MCP (Model Context Protocol) proxy that captures every tool call an agent makes and emits signed, hash-chained, on-chain-anchored receipts to the [Sheaf](https://github.com/sheafhq/sheaf) recorder.
+
+**Zero-code install.** Wrap any existing MCP server in Claude Desktop (or any MCP-aware client) with a one-line config change. No modifications to the wrapped server. No modifications to the agent.
+
+Receipts are verifiable offline by any third party using [`@sheafhq/verify`](https://www.npmjs.com/package/@sheafhq/verify).
+
+## Install
+
+```bash
+npm install -g @sheafhq/mcp-recorder
+```
+
+## Claude Desktop setup
+
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`; Windows: `%APPDATA%\Claude\`). Wrap the servers you want to audit:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "sheaf-mcp-recorder",
+      "args": [
+        "--wrap",
+        "npx",
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/me/Documents"
+      ],
+      "env": {
+        "SHEAF_CHAIN_ID": "claude-me-filesystem",
+        "SHEAF_ACTOR": "claude-desktop-me"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Every `tools/call`, `resources/read`, and `sampling/createMessage` through this server now flows through Sheaf and gets a signed, chained receipt — with the tool arguments and the response hashed (never sent raw).
+
+## How it works
+
+```
+Claude (MCP client)
+    │  JSON-RPC over stdio
+    ▼
+┌──────────────────────────┐
+│  sheaf-mcp-recorder       │  ← this package. Transparent stdio proxy.
+│  (zero-code wrapper)     │
+└───────────┬──────────────┘
+            │  JSON-RPC unchanged
+            ▼
+┌──────────────────────────┐
+│  wrapped MCP server      │  (filesystem, github, slack, …)
+└───────────┬──────────────┘
+            │  JSON-RPC response
+            ▼
+       (tap: build envelope, POST to Sheaf recorder)
+            │
+            ▼
+┌──────────────────────────┐
+│  Sheaf recorder           │  signs + chains + persists
+│  sheaf-recorder.*.dev     │  (anchored on-chain by Sheaf)
+└──────────────────────────┘
+```
+
+Fail-open design: if the recorder is unreachable, the agent's tool calls still work. Missed events are logged to stderr; the chain re-syncs on the next successful submission.
+
+## Environment variables
+
+| Var | Required | Default | Notes |
+|---|---|---|---|
+| `SHEAF_CHAIN_ID` | **yes** | — | Stable identifier for this agent/session's event chain |
+| `SHEAF_ACTOR` | no | = `SHEAF_CHAIN_ID` | Written into every event's `actor` field |
+| `SHEAF_RECORDER_URL` | no | `https://sheaf-recorder.goldencalf.workers.dev` | Point at your own instance if self-hosting |
+| `SHEAF_CAPTURE_METHODS` | no | `tools/call,resources/read,sampling/createMessage` | Comma-separated JSON-RPC methods to intercept |
+| `SHEAF_DEBUG` | no | — | `1` to log every event to stderr |
+
+## What gets recorded
+
+For every intercepted tool call, one hash-chained event containing:
+
+- **intent** — short description (e.g. `invoke tool write_file`)
+- **actor** — from `SHEAF_ACTOR`
+- **tool** — e.g. `mcp://tool/write_file`
+- **inputs_hash** — `sha256(canonicalize(params))` of the tool arguments (raw args are **not** sent to the recorder)
+- **outputs_hash** — same for the response, or null on error
+- **result** — `ok` / `error` / `timeout` / `cancelled`
+- **ts** — ISO 8601 UTC timestamp
+
+The envelope is hash-chained (`prev_hash` → previous envelope hash) so any tamper is detectable. The recorder co-signs with Ed25519 and anchors the Merkle root on Base L2 periodically.
+
+## Verifying a receipt later
+
+Any third party can verify a stored receipt using `@sheafhq/verify` — it reads the anchor transaction from Base and checks the Merkle inclusion + Ed25519 signature offline.
+
+See the main [Sheaf ARCHITECTURE.md](https://github.com/sheafhq/sheaf/blob/main/ARCHITECTURE.md) for the full protocol.
+
+## License
+
+MIT

package/dist/canonical.js

@@ -0,0 +1,40 @@
+// RFC 8785 JCS — identical to packages/verify/src/canonical.ts.
+export function canonicalize(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("JCS: non-finite number");
+        return JSON.stringify(value);
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map(canonicalize).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return ("{" +
+            keys
+                .map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k]))
+                .join(",") +
+            "}");
+    }
+    throw new Error(`JCS: unsupported value type: ${typeof value}`);
+}
+import { createHash } from "node:crypto";
+export function sha256Hex(data) {
+    const h = createHash("sha256");
+    if (typeof data === "string")
+        h.update(data, "utf8");
+    else
+        h.update(data);
+    return h.digest("hex");
+}
+export function hashCanonical(value) {
+    return sha256Hex(canonicalize(value));
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAChE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,OAAO,CACL,GAAG;YACH,IAAI;iBACD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;iBAC1D,IAAI,CAAC,GAAG,CAAC;YACZ,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,gCAAgC,OAAO,KAAK,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,UAAU,SAAS,CAAC,IAAkC;IAC1D,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC/B,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;;QAChD,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpB,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// CLI entry for sheaf-mcp-recorder. Usage:
+//   sheaf-mcp-recorder --wrap <command> [args...]
+//
+// Environment variables:
+//   SHEAF_RECORDER_URL   where to POST events (default: production)
+//   SHEAF_CHAIN_ID       required. Stable per-session / per-agent identifier.
+//   SHEAF_ACTOR          default: SHEAF_CHAIN_ID
+//   SHEAF_CAPTURE_METHODS  comma-separated JSON-RPC methods to capture
+//                       (default: tools/call,resources/read,sampling/createMessage)
+//   SHEAF_DEBUG=1        verbose stderr logging
+import { runProxy } from "./proxy.js";
+const argv = process.argv.slice(2);
+function die(msg, code = 2) {
+    console.error(`sheaf-mcp-recorder: ${msg}`);
+    console.error("usage: sheaf-mcp-recorder --wrap <command> [args...]\n" +
+        "       (set SHEAF_CHAIN_ID; see package README for all env vars)");
+    process.exit(code);
+}
+const wrapIdx = argv.indexOf("--wrap");
+if (wrapIdx === -1)
+    die("missing --wrap flag");
+if (wrapIdx === argv.length - 1)
+    die("no command after --wrap");
+const command = argv[wrapIdx + 1];
+const commandArgs = argv.slice(wrapIdx + 2);
+const chainId = process.env.SHEAF_CHAIN_ID;
+if (!chainId)
+    die("SHEAF_CHAIN_ID env var is required");
+const cfg = {
+    recorderUrl: process.env.SHEAF_RECORDER_URL ??
+        "https://sheaf-recorder.goldencalf.workers.dev",
+    chainId,
+    actor: process.env.SHEAF_ACTOR ?? chainId,
+    captureMethods: new Set((process.env.SHEAF_CAPTURE_METHODS ??
+        "tools/call,resources/read,sampling/createMessage")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)),
+    logDebug: process.env.SHEAF_DEBUG === "1",
+};
+if (cfg.logDebug) {
+    console.error(`[arca] wrapping: ${command} ${commandArgs.join(" ")}`);
+    console.error(`[arca] recorder=${cfg.recorderUrl} chain=${cfg.chainId} actor=${cfg.actor} capture=[${[...cfg.captureMethods].join(",")}]`);
+}
+runProxy(cfg, command, commandArgs);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,2CAA2C;AAC3C,kDAAkD;AAClD,EAAE;AACF,yBAAyB;AACzB,oEAAoE;AACpE,8EAA8E;AAC9E,iDAAiD;AACjD,uEAAuE;AACvE,oFAAoF;AACpF,gDAAgD;AAEhD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,SAAS,GAAG,CAAC,GAAW,EAAE,IAAI,GAAG,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,uBAAuB,GAAG,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,KAAK,CACX,wDAAwD;QACtD,kEAAkE,CACrE,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AACvC,IAAI,OAAO,KAAK,CAAC,CAAC;IAAE,GAAG,CAAC,qBAAqB,CAAC,CAAC;AAC/C,IAAI,OAAO,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC;IAAE,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAEhE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,GAAG,CAAC,CAAE,CAAC;AACnC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;AAE5C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AAC3C,IAAI,CAAC,OAAO;IAAE,GAAG,CAAC,oCAAoC,CAAC,CAAC;AAExD,MAAM,GAAG,GAAmB;IAC1B,WAAW,EACT,OAAO,CAAC,GAAG,CAAC,kBAAkB;QAC9B,+CAA+C;IACjD,OAAO;IACP,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO;IACzC,cAAc,EAAE,IAAI,GAAG,CACrB,CACE,OAAO,CAAC,GAAG,CAAC,qBAAqB;QACjC,kDAAkD,CACnD;SACE,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CACnB;IACD,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,GAAG;CAC1C,CAAC;AAEF,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;IACjB,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACtE,OAAO,CAAC,KAAK,CACX,mBAAmB,GAAG,CAAC,WAAW,UAAU,GAAG,CAAC,OAAO,UAAU,GAAG,CAAC,KAAK,aAAa,CAAC,GAAG,GAAG,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAC5H,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC"}

package/dist/envelope.js

@@ -0,0 +1,138 @@
+// Build an event envelope + submit to the Sheaf recorder. Submission is a
+// background best-effort operation: it must never block the MCP proxy pipeline,
+// and a recorder outage must not break the agent's tool calls.
+import { canonicalize, sha256Hex } from "./canonical.js";
+export class RecorderClient {
+    cfg;
+    state;
+    queue = Promise.resolve();
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.state = this.fetchInitialState();
+    }
+    debug(...args) {
+        if (this.cfg.logDebug)
+            console.error("[arca]", ...args);
+    }
+    async fetchInitialState() {
+        try {
+            const url = `${this.cfg.recorderUrl}/chains/${encodeURIComponent(this.cfg.chainId)}/head`;
+            const r = await fetch(url);
+            if (r.status === 404) {
+                this.debug(`chain ${this.cfg.chainId} is new; starting at seq=0`);
+                return { seq: 0, prev_hash: null };
+            }
+            if (!r.ok) {
+                this.debug(`recorder /head returned ${r.status}; assuming new chain`);
+                return { seq: 0, prev_hash: null };
+            }
+            const body = (await r.json());
+            this.debug(`chain ${this.cfg.chainId} head is seq=${body.head_seq}; resuming at seq=${body.head_seq + 1}`);
+            return { seq: body.head_seq + 1, prev_hash: body.head_hash };
+        }
+        catch (err) {
+            this.debug(`could not reach recorder for initial head (${err.message}); starting at seq=0`);
+            return { seq: 0, prev_hash: null };
+        }
+    }
+    /** Queue an event submission. Returns immediately; does not block the caller. */
+    submit(call, response) {
+        this.queue = this.queue.then(() => this.submitInternal(call, response));
+    }
+    /** Wait for all queued submissions to finish. Call before process exit. */
+    async drain() {
+        await this.queue;
+    }
+    async submitInternal(call, response) {
+        try {
+            const state = await this.state;
+            let result = "ok";
+            let outputsHash = null;
+            if (!response)
+                result = "timeout";
+            else if (response.error)
+                result = "error";
+            else if (response.result !== undefined)
+                outputsHash = "sha256:" + sha256Hex(canonicalize(response.result));
+            const inputsHash = "sha256:" + sha256Hex(canonicalize(call.params));
+            const envelope = {
+                v: "arca/1",
+                event: {
+                    intent: deriveIntent(call),
+                    actor: this.cfg.actor,
+                    authority: null,
+                    tool: deriveToolName(call),
+                    inputs_hash: inputsHash,
+                    outputs_hash: outputsHash,
+                    result,
+                    ts: new Date().toISOString(),
+                },
+                chain: {
+                    chain_id: this.cfg.chainId,
+                    seq: state.seq,
+                    prev_hash: state.prev_hash,
+                },
+                signatures: { actor: null },
+            };
+            const body = canonicalize(envelope);
+            const r = await fetch(`${this.cfg.recorderUrl}/events`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body,
+            });
+            const receipt = (await r.json());
+            if (r.status === 201 && receipt.ok && typeof receipt.seq === "number") {
+                this.state = Promise.resolve({
+                    seq: receipt.seq + 1,
+                    prev_hash: receipt.envelope_hash ?? state.prev_hash,
+                });
+                this.debug(`recorded seq=${receipt.seq} for ${envelope.event.tool} → ${envelope.event.result}`);
+                return;
+            }
+            // 409 with head info means our local state drifted. Re-sync and give up
+            // this one submission (the proxy will keep working; recorder stays
+            // consistent).
+            if (r.status === 409 &&
+                typeof receipt.current_head_seq === "number" &&
+                typeof receipt.current_head_hash === "string") {
+                this.state = Promise.resolve({
+                    seq: receipt.current_head_seq + 1,
+                    prev_hash: receipt.current_head_hash,
+                });
+                this.debug(`resynced after 409: new seq=${receipt.current_head_seq + 1} (missed this submission)`);
+                return;
+            }
+            this.debug(`submission failed (${r.status}): ${receipt.error ?? "unknown"}; event dropped`);
+        }
+        catch (err) {
+            this.debug(`submit threw: ${err.message}; event dropped`);
+        }
+    }
+}
+function deriveToolName(call) {
+    const p = call.params;
+    switch (call.method) {
+        case "tools/call":
+            return `mcp://tool/${p?.name ?? "unknown"}`;
+        case "resources/read":
+            return `mcp://resource/${p?.uri ?? "unknown"}`;
+        case "sampling/createMessage":
+            return `mcp://sampling/createMessage`;
+        default:
+            return `mcp://method/${call.method}`;
+    }
+}
+function deriveIntent(call) {
+    const p = call.params;
+    switch (call.method) {
+        case "tools/call":
+            return `invoke tool ${p?.name ?? "unknown"}`;
+        case "resources/read":
+            return `read resource ${p?.uri ?? "unknown"}`;
+        case "sampling/createMessage":
+            return `sample LLM completion`;
+        default:
+            return call.method;
+    }
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

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

package/dist/proxy.js

@@ -0,0 +1,97 @@
+// Stdio-mode MCP proxy. Spawn the wrapped server, relay JSON-RPC traffic
+// bidirectionally. Tap tools/call, resources/read, sampling/createMessage.
+// Fail open — any error in the recorder path must NOT disrupt the agent's
+// tool calls.
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { RecorderClient } from "./envelope.js";
+export function runProxy(cfg, childCmd, childArgs) {
+    const recorder = new RecorderClient(cfg);
+    const pending = new Map();
+    const child = spawn(childCmd, childArgs, {
+        stdio: ["pipe", "pipe", "inherit"],
+        env: process.env,
+    });
+    child.on("exit", (code, signal) => {
+        if (cfg.logDebug)
+            console.error(`[arca] wrapped child exited code=${code} signal=${signal}; draining recorder queue`);
+        recorder
+            .drain()
+            .catch((err) => {
+            if (cfg.logDebug)
+                console.error(`[arca] drain error: ${err.message}`);
+        })
+            .finally(() => {
+            process.exit(code ?? 0);
+        });
+    });
+    child.on("error", (err) => {
+        console.error(`[arca] failed to spawn wrapped child: ${err.message}`);
+        process.exit(127);
+    });
+    // Parent stdin → child stdin. Also tap each line as an outgoing request.
+    const parentIn = createInterface({ input: process.stdin });
+    parentIn.on("line", (line) => {
+        if (!line.trim())
+            return;
+        try {
+            const msg = JSON.parse(line);
+            if (msg &&
+                typeof msg === "object" &&
+                "method" in msg &&
+                "id" in msg &&
+                cfg.captureMethods.has(msg.method)) {
+                pending.set(msg.id, {
+                    id: msg.id,
+                    method: msg.method,
+                    params: msg.params ?? {},
+                    startedAt: Date.now(),
+                });
+            }
+        }
+        catch {
+            // Not valid JSON — just pass through.
+        }
+        child.stdin.write(line + "\n");
+    });
+    parentIn.on("close", () => {
+        try {
+            child.stdin.end();
+        }
+        catch { }
+    });
+    // Child stdout → parent stdout. Tap responses that match a pending request.
+    const childOut = createInterface({ input: child.stdout });
+    childOut.on("line", (line) => {
+        if (!line.trim()) {
+            process.stdout.write(line + "\n");
+            return;
+        }
+        try {
+            const msg = JSON.parse(line);
+            if (msg &&
+                typeof msg === "object" &&
+                "id" in msg &&
+                (msg.id || msg.id === 0) &&
+                pending.has(msg.id)) {
+                const call = pending.get(msg.id);
+                pending.delete(msg.id);
+                recorder.submit(call, { result: msg.result, error: msg.error });
+            }
+        }
+        catch {
+            // Not valid JSON — pass through.
+        }
+        process.stdout.write(line + "\n");
+    });
+    // Forward signals so Ctrl-C etc. kills the child cleanly.
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(sig, () => {
+            try {
+                child.kill(sig);
+            }
+            catch { }
+        });
+    }
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,2EAA2E;AAC3E,0EAA0E;AAC1E,cAAc;AAEd,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAQ/C,MAAM,UAAU,QAAQ,CACtB,GAAmB,EACnB,QAAgB,EAChB,SAAmB;IAEnB,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IAExD,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,SAAS,EAAE;QACvC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC;QAClC,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;QAChC,IAAI,GAAG,CAAC,QAAQ;YACd,OAAO,CAAC,KAAK,CAAC,oCAAoC,IAAI,WAAW,MAAM,2BAA2B,CAAC,CAAC;QACtG,QAAQ;aACL,KAAK,EAAE;aACP,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACb,IAAI,GAAG,CAAC,QAAQ;gBACd,OAAO,CAAC,KAAK,CAAC,uBAAwB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACnE,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;QACxB,OAAO,CAAC,KAAK,CAAC,yCAAyC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,yEAAyE;IACzE,MAAM,QAAQ,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC3D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,OAAO;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAC;YAC/C,IACE,GAAG;gBACH,OAAO,GAAG,KAAK,QAAQ;gBACvB,QAAQ,IAAI,GAAG;gBACf,IAAI,IAAI,GAAG;gBACX,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAClC,CAAC;gBACD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE;oBAClB,EAAE,EAAE,GAAG,CAAC,EAAE;oBACV,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;oBACxB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;iBACtB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,sCAAsC;QACxC,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACxB,IAAI,CAAC;YACH,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACZ,CAAC,CAAC,CAAC;IAEH,4EAA4E;IAC5E,MAAM,QAAQ,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;YAClC,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAoB,CAAC;YAChD,IACE,GAAG;gBACH,OAAO,GAAG,KAAK,QAAQ;gBACvB,IAAI,IAAI,GAAG;gBACX,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;gBACxB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAqB,CAAC,EACtC,CAAC;gBACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAqB,CAAE,CAAC;gBACrD,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAqB,CAAC,CAAC;gBAC1C,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,0DAA0D;IAC1D,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,EAAE,CAAC;QAC3D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE;YACnB,IAAI,CAAC;gBACH,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC,CAAA,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/types.js

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

package/dist/types.js.map

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

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@sheafhq/mcp-recorder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Transparent MCP (Model Context Protocol) proxy that captures every tool call an agent makes and emits signed, hash-chained, on-chain-anchored receipts via the Sheaf recorder. Zero-code install via claude_desktop_config.json.",
+  "type": "module",
+  "main": "./dist/cli.js",
+  "bin": {
+    "sheaf-mcp-recorder": "dist/cli.js"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sheaf",
+    "mcp",
+    "mcp-server",
+    "audit",
+    "attestation",
+    "agent",
+    "claude",
+    "interceptor",
+    "proxy",
+    "receipt",
+    "hash-chain"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sheafhq/sheaf.git",
+    "directory": "packages/mcp-recorder"
+  },
+  "homepage": "https://github.com/sheafhq/sheaf/tree/main/packages/mcp-recorder",
+  "bugs": {
+    "url": "https://github.com/sheafhq/sheaf/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}