MCP Provenance Capsules\n\nPortable, privacy-first evidence for every MCP tool call.\n\nMCP gives models access to powerful tools. Provenance Capsules answer the hard question that follows: what ran, exactly, and can anyone verify the record later?\n\nThis project is a tiny, dependency-free Node.js MCP server and embeddable library that emits cryptographically linked evidence without storing raw prompts, arguments, or results.\n\n## Why this is not another audit log\n\n- Privacy by default: only SHA-256 digests leave the call boundary; raw payloads stay in the caller.\n- Tamper evident: each capsule carries an HMAC signature and the previous capsule hash.\n- Portable: JSON capsules and JSONL streams work with object storage, SIEMs, test fixtures, or a database.\n- MCP-native: use it as a stdio server with any compatible client, or import the core class into an existing server.\n- Verifiable later: anyone holding the capsule stream and verification secret can detect edits, deletion, and reordering.\n- Small surface: Node.js 20+, no runtime dependencies, no hosted service required.\n\n## Quick start\n\nRequires Node.js 20+.\n\n npm start\n\nConfigure an MCP client with command node and argument /absolute/path/to/mcp-provenance-capsules/src/server.js. Set MCP_RECEIPT_SECRET outside source control.\n\nThe server exposes create_receipt and verify_receipt tools.\n\n## Capsule anatomy\n\nA capsule contains a version, sequence number, UTC timestamp, server and tool identity, argument and result hashes, duration, previous hash, HMAC signature, and its own hash. The canonical schema lives at schema/capsule.schema.json.\n\nThe chain is storage-agnostic: write JSONL to object storage, a database, or your existing audit pipeline. The library never persists data itself.\n\n## Verify a stream\n\nSet the same secret used when creating capsules, then run MCP_RECEIPT_SECRET='your-secret' npx verify-capsule capsules.jsonl.\n\nThe command prints one machine-readable verification result per capsule and exits non-zero if any signature, hash, or chain link fails.\n\n## Embed it\n\nImport ReceiptChain from src/receipts.js, construct it with your secret, and call create with server, tool, arguments, result, and durationMs.\n\n## Security notes\n\nUse a high-entropy secret from your deployment secret manager. Rotate secrets by starting a new chain and recording the rotation boundary in storage. HMAC proves integrity to parties that possess the secret; it is not a public, non-repudiable signature.\n\n## Product boundary\n\nThis project is not a hosted compliance platform, payload recorder, or replacement for authorization. It is the evidence layer underneath those systems.\n\n## Development\n\n npm test\n\nMIT licensed. Contributions are welcome, especially durable sinks, key rotation, OpenTelemetry export, and adapters for additional MCP transports—while preserving the no-raw-payload default.\n