@forestrie/mcp-resolve

@forestrie/mcp-resolve

An MCP server that fetches the material @forestrie/mcp-verify verifies: a receipt, a genesis document, an accumulator snapshot, a registration status, a service configuration. Every result says where its bytes came from and which of the four questions of the trust model they can support. Listed in the MCP registry as dev.forestrie/resolve.

This package is the courier, not the verifier. The verifier runs entirely in your process with no network, no account, no key and no backend, and its own rule is that installing it can never imply a network dependency. So anything that fetches lives here, under a separate name, and depends on the verifier's published core at an exact version pin. The verifier never depends on this package.

Use

{
  "mcpServers": {
    "forestrie-resolve": {
      "command": "npx",
      "args": ["-y", "@forestrie/mcp-resolve"],
      "env": {
        "FORESTRIE_BASE_URL": "https://api-a.forest-2.forestrie.dev",
        "FORESTRIE_RPC_URL": "https://<your-chain-rpc-endpoint>"
      }
    }
  }
}

Both environment variables are optional and both are yours. baseUrl is any SCRAPI base URL and rpcUrl is your own chain access; a call may pass either explicitly, and the environment values are used only when a call omits them. The package ships no default operator and no default chain provider, and names none.

Two public lanes exist and are examples, not defaults:

Lane	Base URL	Service id
A	https://api-a.forest-2.forestrie.dev	canopy-dev-1
B	https://api-b.forest-2.forestrie.dev	canopy-prod-1

Requires Node 20.11 or later.

The seven tools

Tool	What it does	Provenance	Supports
fetch_scitt_configuration	GET {baseUrl}/.well-known/scitt-configuration	fetched	none: operator self-description
query_registration	one GET of the registration-status URL for a statement's content hash; returns pending or the receipt location, never polls	fetched	none: registration status
fetch_receipt	GET a receipt by URL or by log coordinates; returns the bytes, the verifier's decoding of them, and the log id its delegation certificate names	fetched	none on its own: a receipt is the operator's claim
fetch_genesis	GET the forest's genesis document; returns the bytes, the chain binding they carry and, for an ES256 forest, the bootstrap public key decoded from them	fetched	sealing, as known-log-key with the key this copy carries, and only if you keep the copy
fetch_accumulator	reads the log's published accumulator from the univocity contract at your RPC URL and returns the snapshot the known-accumulator root consumes; given a receipt whose peak later growth has buried, looks back through published checkpoint history, within your budget, for the newest one that holds it	chain-read	split-view against the chain; sealing and append-authority by inheritance from the contract's publish-time checks
fetch_checkpoint_history	reads the log's published checkpoints back from the contract's CheckpointPublished events at your RPC URL, newest first, within the block budget you set; returns each as a snapshot you can keep	chain-read	as fetch_accumulator; a kept checkpoint answers split-view later, without another chain read, for any receipt whose peak it contains
verify_fetched_receipt	fetches a receipt and verifies it with the verifier's core under a root you supply as bytes, or under an accumulator read from the chain in the same call; the log you name always wins over the one the receipt's certificate names	fetched + supplied or chain-read	the verifier's own answers, passed through unaltered

Every tool is annotated read-only, idempotent and open-world, because every one of them talks to something outside your process.

What a fetched thing proves

A receipt fetched from the operator is the operator's claim until it is verified under a trust root you hold. The public trust model, spec/receipt-trust-model.md in forestrie/protocol, names four questions a receipt can answer (sealing, split-view, append-authority, attribution) and four trust roots a caller can verify under (genesis, known-log-key, known-accumulator, checkpoint-chain). The roots are not ordered. Which one is right depends on what you hold, and fetching changes what you hold.

That is why every result here carries provenance (for each artefact: fetched from a URL, read from a chain, or supplied by you, and when) and supports (which questions the material can serve as evidence for, under which root, with a one-line note). The notes are fixed strings the tests assert verbatim; they are listed and explained in docs/what-fetching-proves.md.

Two consequences are built into the tool surface rather than left to documentation:

• A fetched genesis is never a root. verify_fetched_receipt takes its root as bytes you supply or as an accumulator read from the chain; its schema has no form that fetches a genesis and verifies under it in the same call. A genesis obtained from the operator at check time makes the operator the supplier of both the receipt and the root, which proves consistency with a document the operator chose to serve today and nothing more. fetch_genesis exists so you can obtain the document once, keep it, and pass it as bytes from then on.
• The chain binding is the forest's, never the operator's. The univocity contract address and chain id are bound in a forest's genesis document. fetch_accumulator and the chain path of verify_fetched_receipt take them from a genesis you hold, or explicitly, never from a default, never from a genesis fetched inside the call, and never from an environment variable.
• Buried peaks are answered from published history, under the same root. The contract keeps only the latest state; later growth folds a receipt's peak into a bigger one. The chain path then looks back through CheckpointPublished events, one eth_getLogs per window within the budget you set, for the newest checkpoint that still holds the peak, and says so (root_read_from_chain_history). Running out of range is a structured problem, never an unbounded scan.

The verifier's own TRANSPARENCY.md (shipped in its tarball) explains what a transparency log is and what a receipt contains; this package does not repeat it. Its docs/trust-roots.md explains the roots in depth.

What this package never does

• Never writes: no registration, no grants, no keys.
• Never polls: query_registration is one request, and you decide whether to call it again. An HTTP 429 comes back as a structured problem with retryAfterMs, not as an error.
• Never chooses an operator or a chain provider for you.
• Never caches a fetched genesis or accumulator across calls: every result carries a fresh at.
• Never edits the verifier's answers. verify_fetched_receipt returns the verifier's stages, questions and diagnostics unaltered and appends two diagnostics of its own that say where the bytes came from. not_answered_by_this_root is a real answer and reaches you unchanged.

Layout and gates

src/core/   pure over bytes: URL construction, response classification,
            provenance and supports labelling, the compose logic.
            No node:*, no fetch, no fs. Exported as ".".
src/net/    the ONLY place fetch is called; every function takes fetchImpl.
            Exported as "./net".
src/node/   the MCP adapter: SDK, stdio, {path}/base64 inputs, env defaults.
            Exported as "./server".

CI blocks on: src/core bundling for the browser with no Node builtin; the unit project running under a fetch that throws (the network layer is tested only through injected fakes, replaying recorded exchanges frozen under test/fixtures/ with a sha256 manifest and a PROVENANCE.md); one copy of @forestrie/encoding and @forestrie/receipt-verify in the repo and in a scratch install of the packed tarball; the real bin writing nothing to stdout but MCP frames; and server.json agreeing with package.json. A live project against a real lane exists, is opt-in by environment variable, and is never a required check.

pnpm test        # purity gates + unit tests
pnpm typecheck
pnpm build
pnpm test:live   # FORESTRIE_LIVE=1 plus FORESTRIE_BASE_URL, FORESTRIE_RPC_URL and the chain values

Conventions, invariants and the release path are in AGENTS.md.

Dependencies

Exact pins, bumped deliberately: @forestrie/mcp-verify (core export only), @forestrie/scrapi-client, @forestrie/receipt-verify, @forestrie/encoding, @modelcontextprotocol/sdk. The chain read is three JSON-RPC calls made locally through the injected fetchImpl.

License

MIT.