sagrada-mcp

Model Context Protocol (MCP) server for Sagrada — track and verify reasoning state for AI systems, and read attested repo-history records.

Sagrada gives Claude Code (and any MCP-capable client) durable, content-addressed memory of design decisions, claim revisions, contradictions, and the cryptographically verifiable chain of edits that produced the current knowledge state.

Installation

Mode 1: pip install (clean venv, no repo checkout)

pip install sagrada-mcp        # once published; from a checkout:
pip install ./sagrada_mcp

This installs the server plus vendored copies of its not-yet-published dependencies (see _vendor/README.md). One server, 21 tools:

• The 3 preflight-gate tools (preflight_action, list_beliefs, verify_receipt) gate consequential tool calls against the repo's typed beliefs and emit Ed25519-signed action receipts to .sagrada/receipts.jsonl, each independently verifiable offline with uvx er1-verify (1.0.1 or later — an unpinned install against a version constraint is a declared coverage gap the verifier recomputes, a receipt shape 1.0.0 predated). Deterministic and engine-free — refusal does not depend on the binary wheel.

  Receipts are signed with a keypair created for your repo on first use: the private half lives at .sagrada/operator_key (mode 0600 on POSIX, gitignored, never leaving your machine), the public half at .sagrada/operator_key.pub is meant to be committed. verify_receipt checks a receipt's signer against that committed key and the signed succession chain behind it, so a receipt from a key that was never this repo's comes back foreign rather than passing quietly. Earlier versions minted a key per process, which made every signature unpinnable — "signed by X" where X existed for one run.

  What that establishes is continuity, not identity: if you pinned this repo's fingerprint out of band, and the private key has never left the machine, then a swap of the signing key shows up. Each clause matters — a signature proves possession of a file, and files copy.

  For Claude Code there is also an ENFORCED layer: the sagrada-preflight-hook console script registers as a PreToolUse hook and blocks HALTed calls in-band (see preflight_hook.py for the one-line registration).

• The 6 repo-record (crux) tools are fully functional given a .crux artifact (SAGRADA_CRUX). Without one they return a helpful error string.

• The 12 reasoning-tracker tools additionally need the compiled sagrada-engine wheel (a hard dependency as of 0.3.0; installed automatically on platforms with wheels). If the engine is somehow absent they return a clear JSON error naming the missing piece — never a traceback.

Mode 2: repo checkout

From the parent repository root (all packages importable in place):

python -m sagrada_mcp.server

The server always prefers the repo's real sagrada_tracker and scripts/ert/ask_grammar.py over the vendored copies, so a checkout behaves exactly as before.

Configure in Claude Code / Claude Desktop

{
  "mcpServers": {
    "sagrada": {
      "command": "sagrada-mcp",
      "env": { "SAGRADA_PROJECT": "/path/to/your/project" }
    }
  }
}

(In a repo checkout use "command": "python", "args": ["-m", "sagrada_mcp.server"].)

Tools provided (21)

Preflight gate (3) — deterministic, no engine required

Recognition is a finite, best-effort vocabulary. The gate maps a tool call to beliefs by reading the forms an agent actually emits — imports, package-manager installs, deploy targets, env assignments. An action expressed in a form it does not recognise is not mapped, and an unmapped action does not conflict with anything, so it is ALLOWed. Treat HALT as an enforced policy check on recognised actions, not as containment.

Reasoning tracker (12) — require the compiled sagrada engine

Repo-record / crux (6) — work anywhere, given a .crux artifact

Deterministic reads of a transformed repo-history record — no model, no network, no clock. Every answer carries the record reference (artifact, state_root, receipt) for offline verification.

No artifact? Each crux tool returns a pointer instead of failing: no .crux artifact found — set SAGRADA_CRUX to the artifact path (build one with: python -m scripts.ert.distill transform <repo>).

Resources provided (3)

Environment variables

License

Apache-2.0. Published by Cruxia-Labs.