mcp-resolve

# @forestrie/mcp-resolve

An MCP server that fetches the material
[`@forestrie/mcp-verify`](https://www.npmjs.com/package/@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

```json
{
  "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 and the verifier's decoding of them                                                                                                                                                                                                         | fetched                          | none on its own: a receipt is the operator's claim                                                                                       |
| `fetch_genesis`             | `GET` the forest's genesis document; returns the bytes and the chain binding they carry                                                                                                                                                                                                                     | 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                                                                                                                                                   | 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`](https://github.com/forestrie/protocol/blob/main/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](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`](https://github.com/forestrie/mcp-verify/blob/main/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`](https://github.com/forestrie/mcp-verify/blob/main/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