evernode-mcp

# evernode-mcp — Evernode AI Builder

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI agent **build,
check, cost, and deploy HotPocket dApps** on [Evernode](https://evernode.org) /
[Xahau](https://xahau.network). Point any MCP-capable agent (Claude, etc.) at it and ask for a
dApp — it scaffolds a contract from templates written to avoid the known consensus-breakers,
lints contract code for non-deterministic patterns, estimates the EVR lease, ranks **live**
Evernode hosts, generates the deploy commands, and — when the dApp moves value on Xahau — emits
the commands to install a spend-limit Hook and prove its invariant with the Hooks toolchain.

> HotPocket is Evernode's contract runtime: it runs your Node.js/WASM contract on **every node**
> of a cluster and puts the output + state through **consensus**. The single biggest beginner
> mistake is non-deterministic code (`Date.now()`, `Math.random()`, `fetch()`, …) — two nodes
> compute different results and the ledger **stalls**. This server is built around catching the
> common causes of that before deploy (heuristically — see [what it does / doesn't catch](#why-the-determinism-check-matters-and-exactly-what-it-does--doesnt-catch)).

It is **advisory and read-only**: it generates files + guidance, **never holds keys, never spends
EVR, never acquires a lease, never signs or submits**, and it **connects to** the Offledger
Cluster Manager rather than replacing its orchestration. No API keys or accounts are needed; the
only network calls are read-only HTTPS GETs to the public OnLedger API from two tools (see
[Network access](#network-access)).

## Where it fits — the layer-2 companion to the Hooks trifecta

The Hooks pipeline secures *layer-1* Hooks — **write → simulate one tx → prove all inputs → watch live**:

| stage | tool | what it does |
|---|---|---|
| **write** | [xahc](https://github.com/Hugegreencandle/xahc) | author + compile a safe Hook to clean, lint-passed WASM |
| **simulate one** | [xahau-mcp](https://github.com/Hugegreencandle/xahau-mcp) | run the real bytecode against one live transaction |
| **prove all** | [xahc-prover](https://github.com/Hugegreencandle/xahc-prover) | prove an invariant holds for every input in scope — or return the counterexample |
| **watch live** | [xahc-watch](https://github.com/Hugegreencandle/xahc-prover/tree/main/src/watch) | bind a proof to the deployed hook and continuously attest it (alerts on a `SetHook` swap or a live verdict break) |

**evernode-mcp** is the *layer-2* companion: it builds the **HotPocket dApps** that run on
Evernode hosts. Whenever a dApp settles value on Xahau through a Hook-guarded account, it hands
off to the trifecta — it never re-asserts settlement safety itself (`check_hook_compat` /
`generate_settlement` emit the trifecta's prove/install commands, not a safety verdict).

## Tools

All twelve tools are **read-only / advisory**. Every tool sets `readOnlyHint: true`; only the two
live OnLedger tools (`recommend_hosts`, `host_diagnostics`) set `openWorldHint: true` (they may reach
a live external endpoint, OnLedger). Each tool publishes an **output schema**, so an agent gets a
validated `structuredContent` shape (not just text) — no guessing field names.

| tool | open world? | returns |
|---|---|---|
| `list_templates` | no | `{ templates }` — the 10 available dApp template names. |
| `generate_contract` | no | `{ template, files, notes }` — a complete, lint-clean (no HIGH `check_determinism` findings) HotPocket file set (contract + state helper + `hp.cfg.override` + `package.json` + client) for a template. |
| `check_determinism` | no | `{ findings, summary }` — a heuristic linter for contract source: flags known non-deterministic patterns (wall-clock, randomness, network I/O, env/host reads, timers/races, filesystem outside the state file, unordered iteration/serialization, locale/timezone formatting, floating-point literals) that can break cluster consensus. Each finding has `line/column/rule/severity/why/fix`. HIGH findings are likely consensus breakers. A clean result means none of these patterns were found — **not** that the contract is proven deterministic. |
| `check_contract_api` | no | `{ findings, summary }` — **sibling to `check_determinism`** (same honest framing — guidance, **not a proof**). A heuristic static check that a HotPocket Node.js contract uses the contract API correctly: an `hpc.init(...)` entry point, reading `ctx` (`users`/`lclSeqNo`), persisting ONLY through the consensused state mechanism (no arbitrary `fs` writes to non-state paths), handling `ctx.users` I/O, using `ctx.lclSeqNo` for time (not `Date.now`), and awaiting async consensus ops. Each finding has `line/column/rule/severity/why/fix`. |
| `recommend_pattern` | no | `{ pattern, nodes, notes }` — given a plain-English use-case, the HotPocket pattern: node count, state model, oracle/NPL usage, Xahau settlement, and the determinism caveats that matter. |
| `check_hook_compat` | no | `{ involvesHook, workflow, repos }` — returns the recommended **write → simulate → prove → install** workflow for a dApp that settles via a Xahau Hook (xahc · xahau-mcp · xahc-prover). It does not analyze a Hook itself. |
| `generate_settlement` | no | `{ template, limitDrops, files, install, prove, notes }` — starter cluster-side Xahau payout code + an unsigned `xahc install-tx` command for the `agent_guardrail` Hook (per-tx `LIM` + optional `DST` lock) + the `xahc prove` command to check it. Emits commands only, no safety verdict. Accepts `escrow` / `subscription` / `payment_splitter` / `streaming_payment` / `multisig_treasury`. |
| `estimate_lease_cost` | no | `{ inputs, perNodeEVR, totalEVR, approxDurationHours, notes }` — tenant EVR lease = `evrPerMoment × moments × nodes`. Honest: rates are **host-set** (no network standard); host-side registration fees are excluded. |
| `recommend_hosts` | **yes** | `{ mode, ranked, prefer, note, source?, query? }` — fetch + rank **live** Evernode hosts from the public [OnLedger](https://api.onledger.net) API (an index of the Evernode registry on Xahau) by `cheap` / `capacity` / `reputation`, with filters (min reputation/slots/RAM, country) passed to the live query — or rank a `hosts` list you supply (filters not applied; top 10). **Real data only — never invents hosts**; honest empty + note on fetch failure. |
| `host_diagnostics` | **yes** | `{ found, address, source, note?, registration?, reputation?, slots?, lease?, specs?, redFlags }` — health view of a single Evernode host by r-address: registration status, reputation, active/total/available slots, lease terms (rate/drops if available), specs, and red-flags (flagged, marked inactive, low or zero reputation, full capacity). Fetches **live** from OnLedger — or diagnose a `host` object you supply. **Real data only**: numeric fields are **soundly coerced** (a string-typed numeric like `"252"` becomes a real number; garbage / non-finite values are **omitted**, never a fabricated `0`); unknown fields are **omitted** (never invented); honest `found:false` + note on not-found / fetch failure. |
| `generate_deploy_commands` | no | `{ steps, notes }` — command sequences for `local` (hpdevkit dev cluster) · `single` (evdevkit acquire one host) · `cluster` (evdevkit N-node) · `cluster-manager` (connect to the Offledger Cluster Manager). |
| `explain_error` | no | `{ matched, explanations? / message? }` — map a HotPocket/Evernode error to cause + fix (connection, consensus stall, no hosts, insufficient EVR, lease expiry, docker/Sashimono, Hook rejection). |

## Templates

`generate_contract` ships 10 templates. Each is written to avoid the known non-determinism
sources (no wall-clock, no randomness, no network in the contract path; time is the consensus
ledger seq `ctx.lclSeqNo`; state persists only through the contract's own consensused state file)
and is **lint-clean**: the smoke test and the suite run every template through `check_determinism`
(no HIGH findings) and `check_contract_api`. That is a heuristic check, not a proof of
determinism — test on a multi-node cluster before mainnet.

| template | what it is | determinism note |
|---|---|---|
| `blank` | minimal echo contract — a starting point. | echoes input + `ctx.lclSeqNo`. |
| `escrow` | depositor locks an amount-claim for a beneficiary, released after a deadline. | deadlines are **ledger sequences**, not timestamps. |
| `subscription` | users subscribe for N ledger-rounds; access granted while `lclSeqNo < expiry`. | pure ledger-seq accounting. |
| `game_backend` | turn-based per-user scores + leaderboard. | leaderboard sorts with a **code-point** pubkey tiebreaker (not `localeCompare` — host ICU collation diverges) so ordering is deterministic. |
| `voting` | one-vote-per-pubkey poll with tally. | tally iterates a **sorted** key view; votes keyed by pubkey dedupe. |
| `token_gated` | gated access via an admin-maintained allowlist. | **does not read an on-chain balance** from contract logic (non-deterministic) — uses a consensused allowlist/oracle attestation. |
| `payment_splitter` | records deposits, computes weighted splits in integer drops. | remainder to the last recipient so payouts **sum exactly** (no rounding leak); actual payout is a separate Xahau multisig step (see `generate_settlement`). |
| `oracle_consumer` | the canonical hard pattern: brings external data in via **NPL agreement** (nodes agree on the value before acting), never a direct fetch. | nodes PROPOSE their observation over the Node Party Line and only ACT on a strict-majority **agreed** value (a primitive, so its canonical form is byte-identical); disagreement is a deterministic no-op; the agreed datum is stamped with `ctx.lclSeqNo`. |
| `streaming_payment` | per-ledger-seq vesting: releasable amount is `release = f(ctx.lclSeqNo)`. | pure function of the consensus clock, integer drops only (no float divergence); the contract RECORDS the release — the actual transfer is **deferred**