Evernode MCP

evernode-mcp — Evernode AI Builder

一个 模型上下文协议 服务，可让 AI Agent 在 Evernode / Xahau 上构建、检查、估算成本并部署 HotPocket dApp。让任何兼容 MCP 的 Agent（如 Claude 等）连接到它，并提出构建 dApp 的需求——它会从模板生成合约，这些模板经过编写，可避免已知的共识破坏因素；它会检查合约代码中的非确定性模式，估算 EVR 租约费用，为 在线 Evernode 主机排序，生成部署命令；当 dApp 在 Xahau 上转移价值时，还会生成安装支出限额 Hook 的命令，并使用 Hooks 工具链证明其不变量。

HotPocket 是 Evernode 的合约运行时：它会在集群的每个节点上运行你的 Node.js/WASM 合约，并对输出和状态进行共识。初学者最常犯的错误是编写非确定性代码（Date.now()、Math.random()、fetch() 等）——两个节点会计算出不同结果，导致账本停滞。这个服务旨在帮助你在部署前捕获常见原因（通过启发式方法——参见它能检查和不能检查的内容）。

它仅提供建议且为只读：生成文件和指导，绝不持有密钥、花费 EVR、获取租约、签名或提交，并且它连接到 Offledger Cluster Manager，而不是取代其编排功能。无需 API 密钥或账号；唯一的网络调用是两个工具对公开 OnLedger API 发起只读 HTTPS GET 请求（参见网络访问）。

定位——Hooks 三件套的二层搭档

Hooks 流水线用于保护一层 Hooks——编写 → 模拟一笔交易 → 证明所有输入 → 实时监控：

阶段	工具	功能
编写	xahc	编写并编译安全的 Hook，生成整洁且通过 lint 检查的 WASM
模拟一笔交易	xahau-mcp	针对一笔在线交易运行真实字节码
证明所有输入	xahc-prover	证明不变量对范围内的每个输入都成立，或返回反例
实时监控	xahc-watch	将证明绑定到已部署的 Hook，并持续验证（在 SetHook 被替换或实时验证结果失效时发出警报）

evernode-mcp 是二层搭档：用于构建运行在 Evernode 主机上的 HotPocket dApp。每当 dApp 通过受 Hook 保护的账户在 Xahau 上结算价值时，它都会交由这套三件套处理——它绝不会自行再次判断结算是否安全（check_hook_compat / generate_settlement 会生成三件套的证明和安装命令，而不是给出安全判定）。

工具

全部十二个工具均为只读／建议性。每个工具都设置了 readOnlyHint: true；只有两个在线 OnLedger 工具（recommend_hosts、host_diagnostics）设置了 openWorldHint: true（它们可能访问在线外部端点 OnLedger）。每个工具都提供输出架构，因此 Agent 可以获得经过验证的 structuredContent 结构（而不仅仅是文本），无需猜测字段名。

工具	开放世界？	返回内容
list_templates	否	{ templates } — 10 个可用 dApp 模板名称。
generate_contract	否	{ template, files, notes } — 为指定模板生成完整且通过 lint 检查的 HotPocket 文件集（合约 + 状态辅助文件 + hp.cfg.override + package.json + 客户端），且不存在 HIGH check_determinism 发现项。
check_determinism	否	{ findings, summary } — 对合约源码进行启发式 lint 检查：标记可能破坏集群共识的已知非确定性模式（墙上时钟、随机性、网络 I/O、环境变量/主机读取、计时器/竞态、状态文件以外的文件系统操作、无序迭代/序列化、区域设置/时区格式化、浮点数字面量）。每条发现都包含 line/column/rule/severity/why/fix。HIGH 级别的发现很可能会破坏共识。结果干净表示未发现这些模式，并不代表已证明合约具有确定性。
check_contract_api	否	{ findings, summary } — 与 check_determinism 同类（同样如实说明：这是指导，不是证明）。通过启发式静态检查，验证 HotPocket Node.js 合约是否正确使用合约 API：包含 hpc.init(...) 入口、读取 ctx（users/lclSeqNo）、仅通过共识状态机制持久化（不得使用 fs 任意写入非状态路径）、处理 ctx.users I/O、使用 ctx.lclSeqNo 获取时间（而非 Date.now），并等待异步共识操作完成。每条发现都包含 line/column/rule/severity/why/fix。
recommend_pattern	否	{ pattern, nodes, notes } — 根据通俗英文描述的使用场景，推荐 HotPocket 模式：节点数量、状态模型、预言机/NPL 用法、Xahau 结算方式，以及相关的确定性注意事项。
check_hook_compat	否	{ involvesHook, workflow, repos } — 返回通过 Xahau Hook 结算的 dApp 所推荐的 编写 → 模拟 → 证明 → 安装 工作流（xahc · xahau-mcp · xahc-prover）。不会分析 Hook 本身。
generate_settlement	否	{ template, limitDrops, files, install, prove, notes } — 生成集群侧 Xahau 付款代码起始模板 + 用于 agent_guardrail Hook 的未签名 xahc install-tx 命令（每笔交易设 LIM + 可选的 DST 锁定）+ 用于检查该 Hook 的 xahc prove 命令。仅输出命令，不提供安全判定。接受 escrow / subscription / payment_splitter / streaming_payment / multisig_treasury。
estimate_lease_cost	否	{ inputs, perNodeEVR, totalEVR, approxDurationHours, notes } — 租户 EVR 租赁费用 = evrPerMoment × moments × nodes。如实说明：费率由主机设置（没有网络标准）；不含主机端注册费。
recommend_hosts	是	{ mode, ranked, prefer, note, source?, query? } — 从公开的 OnLedger API（Xahau 上 Evernode 注册表的索引）获取实时 Evernode 主机并按 cheap / capacity / reputation 排序，筛选条件（最低信誉度/插槽数/RAM、国家）会传入实时查询；也可对你提供的 hosts 列表排序（不应用筛选条件；返回前 10 个）。仅使用真实数据 — 绝不虚构主机；获取失败时如实返回空结果并附注。
host_diagnostics	是	{ found, address, source, note?, registration?, reputation?, slots?, lease?, specs?, redFlags } — 根据 r 地址查看单个 Evernode 主机的健康状况：注册状态、信誉度、活动/总数/可用插槽、租赁条款（费率/滴数，如有）、规格和风险标记（已标记、标记为不活跃、信誉度低或为零、容量已满）。从 OnLedger 获取实时数据，也可诊断你提供的 host 对象。仅使用真实数据：对数值字段进行可靠类型转换（数字字符串，如 "252"，会转换为真正的数字；垃圾值/非有限值会被省略，绝不伪造为 0）；未知字段会被省略（绝不虚构）；未找到/获取失败时如实返回 found:false 并附注。
generate_deploy_commands	否	{ steps, notes } — 为 local（hpdevkit 开发集群）· single（evdevkit 获取一个主机）· cluster（evdevkit N 节点）· cluster-manager（连接到 Offledger Cluster Manager）生成命令序列。
explain_error	否	{ matched, explanations? / message? } — 将 HotPocket/Evernode 错误映射到原因和修复方法（连接、共识停滞、无可用主机、EVR 不足、租赁到期、docker/Sashimono、Hook 拒绝）。

模板

generate_contract 提供 10 个模板。每个模板都经过编写，以避免已知的非确定性 来源（合约路径中没有墙上时钟、随机数或网络访问；时间使用共识账本序列号 ctx.lclSeqNo；状态仅通过合约自身的共识状态文件持久化），并且通过 lint 检查：冒烟测试和测试套件都会对每个模板运行 check_determinism （没有 HIGH 级发现）和 check_contract_api。这是启发式检查，并非确定性的证明 —— 在主网上部署前，请先在多节点集群上测试。

template	含义	确定性说明
blank	最简回显合约 — 一个起点。	回显输入和 ctx.lclSeqNo。
escrow	存款人锁定一笔金额索取权，供受益人在期限后领取。	期限使用账本序列号，而不是时间戳。
subscription	用户订阅 N 个账本轮次；当 lclSeqNo < expiry 时授予访问权限。	纯账本序列号计量。
game_backend	基于回合制的用户分数和排行榜。	排行榜使用代码点公钥作为平局判定条件进行排序（不使用 localeCompare — 主机 ICU 排序规则会产生偏差），以确保排序具有确定性。
voting	每个公钥限投一票的投票，并统计票数。	统计时遍历已排序的键视图；以公钥为键的投票可去重。
token_gated	通过管理员维护的允许列表控制访问。	合约逻辑不会读取链上余额（非确定性）— 而是使用共识允许列表／预言机证明。
payment_splitter	记录存款，并以整数 drops 计算加权分账。	余数分配给最后一位收款人，确保付款总额完全相等（不会因舍入而产生差额）；实际付款是独立的 Xahau 多签步骤（参见 generate_settlement）。
oracle_consumer	经典的困难模式：通过NPL 协议引入外部数据（节点在行动前就数值达成一致），绝不直接抓取。	节点通过 Node Party Line 提议各自的观测结果，并且只对严格多数达成一致的值执行操作（该基元可确保其规范形式逐字节相同）；意见不一致时会确定性地不执行任何操作；达成一致的数据会附上 ctx.lclSeqNo。
streaming_payment	按账本序列号归属：可释放金额为 release = f(ctx.lclSeqNo)。	仅由共识时钟决定，只使用整数 drops（不会出现浮点数偏差）；合约仅记录释放金额 — 实际转账会延后到 generate_settlement。
multisig_treasury	记录支出提案和 M-of-N 批准（阈值）。	批准以签署者公钥为键，并在已排序的视图中计数；达到阈值时会向 generate_settlement 发出结算步骤（串起完整流程）— 合约从不签名／支出。

每组生成的文件都附有说明，包括“部署前：在 src/index.js 上运行 check_determinism — HIGH 级发现会破坏共识。”

为什么确定性检查很重要（以及它究竟能／不能发现什么）

HotPocket 会对每个节点上的合约输出进行共识。如果两个节点的执行结果不同 —— 因为你调用了 Date.now()、Math.random()、fetch()，或读取了 process.env，又或是遍历了以非共识顺序构建的无序集合 —— 共识就会破坏，账本也会停滞。 check_determinism 会在部署前标记这些问题。

它是启发式 lint 检查器，不是证明器— 扫描源码（主要逐行使用正则表达式，另加一轮小规模的跨行别名检查），因此它只是指导，绝不构成保证。设计取向（有意为之）： 对于此工具，漏报（未能提示真实的共识破坏因素）是最糟糕的结果。因此，如果某个结构可能遍历／序列化无序集合，但无法证明其已排序，就会被标记。误报（标记安全代码）只会让你多做一项说明。

目前涵盖的内容（每项都附有 why 和具体的 fix）：

• 墙上时钟 — Date.now、performance.now、process.hrtime[.bigint]、new Date()（高）。
• 随机性 — Math.random、crypto.randomBytes/randomUUID/randomInt/randomFill[Sync]/getRandomValues（高）。
• 网络 I/O — fetch/axios/got/node-fetch、require('https'|'net'|'dns')（高）。
• 每个节点的环境 — process.env/process.pid、os.hostname/networkInterfaces/cpus/freemem/loadavg/uptime/userInfo/platform/arch/tmpdir/endianness（高）。
• 定时器 / 竞态 — setTimeout/setInterval/setImmediate、Promise.race/any（中）。
• 文件系统 — 对已批准状态文件之外的文件执行 fs.read*/write*/stat/readdir（中）。
• 无序迭代 — for..in，以及 Object.keys/values/entries + Map/Set for..of（低）。已排序的视图（Object.keys(o).sort()、Object.entries(o).sort(...)）可被识别，不会触发标记。
• 别名 Map/Set（低）— 绑定到 new Map()/new Set() 的变量或成员（this.m = new Map()、state.m = new Set()），在后续行中进行迭代 / 展开 / 调用 forEach / Array.from / .entries()/.keys()/.values()（跨行别名检查现在也涵盖成员表达式别名，不再仅限普通标识符）。
• 成员表达式 for..of（低）— for (const x of this.m / state.m / obj.m)，即使没有 Map/Set 证据也会触发标记：无法证明顺序。已知确定性的数组成员（user.inputs/outputs）和调用表达式（ctx.users.list()）可被识别，不会触发标记。
• 展开 / Array.from 物化（低）— [...map]、[...Object.values(o)]、Array.from(set) 等会将插入顺序物化为数组的写法；若紧接着调用 .sort()，则不会触发标记。
• .forEach（低）— 对 Object 视图或 new Map/Set 调用；若先进行排序，则不会触发标记。
• 对无序对象调用 JSON.stringify（低）— 裸对象标识符，或键顺序无法证明一致的展开 / 合并（序列化输出 / 状态需逐字节一致）。固定键对象字面量、数组、原始值、已排序的 replacer 数组以及已调用 .sort() 的参数都可被识别为安全，不会触发标记。
• 区域设置 / 时区 / ICU（中）— toLocaleString / toLocaleDateString / toLocaleTimeString、localeCompare 和 Intl.*。这些操作依赖主机的区域设置以及 ICU 排序 / 格式数据（和时区），而这些因节点而异，因此生成的字符串或排序顺序会出现差异。解决方法：使用与区域设置无关的格式化方式和码点比较（a < b ? -1 : a > b ? 1 : 0），切勿使用 localeCompare。
• 浮点数字面量（低）— 输入合约运算的非整数浮点数字面量（例如 0.1 或负指数科学计数法字面量 1.5e-3 / 1e-3）或 parseFloat(：不同引擎 / 主机的浮点舍入 / NaN / -0 可能不同。解决方法：只使用整数运算（以 drops 为单位计算，使用 Math.floor(a*n/d)）。整数数字面量、结果为整数的正指数数字面量（1.5e3 = 1500）以及整数除法 / 向下取整不会触发标记。

仍不在范围内（如实说明——以下情况不会被捕获）：

• 纯浮点运算／无类型除法——两个类型未知的变量执行 a / b（没有浮点数字面量／parseFloat 信号）时，噪声过大，无法可靠地标记，因此不会标记。只有浮点字面量和 parseFloat 才会被标记。
• 更深层的数据流——通过多跳别名（const n = m）、函数返回值（const m = makeMap()）、作为参数传入的 Map、跨多个语句合并的对象展开、动态构建的调用表达式，或通过单独语句重新赋值而获得的 Map（let m; m = new Map()）导致的顺序分歧。别名检查覆盖直接的 const x = new Map() 和直接成员 this.m = new Map() 情况，不覆盖任意数据流。
• 已知可接受的误报——例如，[...Object.keys(o)].sort() 仍会触发基础 iteration-order 规则（展开操作会使该规则无法检测到 .sort()）；仅用于本地日志的 Date.now()；对 Map 进行与顺序无关的归约；以及诚实的数组通过 for (const x of this.list) 迭代（这是没有数组允许名单条目的成员）。这些会标记安全代码（可接受的方向）——请说明理由或重构。

因此：它能捕获初学者容易遇到的问题，并倾向于对迭代／序列化类别多报一些——但它不能证明确定性。结算的安全性由三重机制（xahc-prover）单独证明。主网上线前，务必在真实的多节点集群上测试。

结算 → 三重机制交接

在 Xahau 上，转移价值的 dApp（托管／订阅付款／payment_splitter）进行付款时，资金来自集群的多重签名账户。generate_settlement 会生成一个三部分的捆绑包：

1. 集群侧付款代码（xahau/settle.js，起始示例）——合约在共识下决定金额；签名在共识之外进行，由集群的阈值／多重签名签名者完成。生成的文件使用单个密钥签名作为占位示例；请替换为多重签名聚合。
2. 在集群账户上安装参考 agent_guardrail Hook（来自 xahc-prover；已在 Xahau 测试网上验证），并设置每笔交易的 LIM（支出上限，8 字节大端序 HookParameter）以及可选的 DST（目的地锁定）——生成一个未签名的 xahc install-tx SetHook，供离线签名。
3. 用于证明你的已构建 WASM 满足防护栏不变量的精确 xahc prove 命令。

该捆绑包**会生成证明／安装命令，但不会自行给出安全性判定。**安装 Hook 期间，超过 LIM 或发往非允许的 DST 的传出 Payment 会被账本拒绝，即使付款代码或签名者有误也是如此。**限制：**Hook 只会在 Payment 上触发，因此无法阻止账户签名者移除它（SetHook），也无法阻止通过其他交易类型转移价值——请保护签名者法定人数。xahc prove 给出的 PROVEN 判定只在证明器建模范围内有效；只有你的构建版本通过 PROVEN 后才能部署。

安装

需要 Node.js 20+。此服务通过 stdio 使用 MCP；由你的 MCP 客户端启动。

从 npm 安装

npx -y evernode-mcp --help      # run without installing (prints usage and exits)
npm install -g evernode-mcp     # or install the `evernode-mcp` command globally
evernode-mcp --smoke            # offline self-test (templates lint-clean, checker + math work)

不带参数运行时，evernode-mcp 会在标准输入／标准输出上等待 MCP 客户端——它不是交互式命令行工具。

将其添加到 MCP 客户端

Claude Code：

claude mcp add evernode -- npx -y evernode-mcp

Claude Desktop（claude_desktop_config.json），或任何接受 mcpServers 区块的客户端：

{
  "mcpServers": {
    "evernode": { "command": "npx", "args": ["-y", "evernode-mcp"] }
  }
}

如果你是全局安装的，也可以只设置 "command": "evernode-mcp"，不带 args。不需要环境变量、API 密钥或钱包。

从 GitHub／源代码安装

npm install -g github:Hugegreencandle/evernode-mcp   # builds on install via `prepare`

或者克隆并构建：

git clone https://github.com/Hugegreencandle/evernode-mcp && cd evernode-mcp
npm install        # the `prepare` script compiles dist/ automatically
npm run smoke      # offline self-test
npm test           # the full Vitest suite (offline)

网络访问

12 个工具中有 10 个完全离线。只有 recommend_hosts 和 host_diagnostics 会发起网络请求，而且仅当你未自行提供主机数据时才会请求：

工具	请求	说明
recommend_hosts	GET https://api.onledger.net/hosts?active=true&sort=…&limit=…[&minSlots&minRep&country&minRam]	公开，无需密钥；超时 10 s；内存缓存 30 s
host_diagnostics	GET https://api.onledger.net/hosts/<r-address>	公开，无需密钥；超时 10 s；内存缓存 30 s

OnLedger 是第三方服务，并非由本项目运营；其数据的时效性取决于自身索引。发生任何故障时，工具都会返回空结果并附上说明，绝不会伪造主机信息。任何内容都不会写入账本。（生成的 xahau/settle.js 文件会在你运行时连接到 wss://xahau-test.net；服务本身绝不会连接。）

用法

让任何支持 MCP 的 Agent 连接到服务，然后直接提问，例如：

• “为名为 vault 的 HotPocket dApp 搭建脚手架。” → generate_contract
• “这个合约对集群共识来说安全吗？”（粘贴源代码）→ check_determinism
• “这个合约是否正确使用了 HotPocket API？”（粘贴源代码）→ check_contract_api
• “搭建一个通过 NPL 就价格达成共识的预言机 dApp。” → generate_contract（oracle_consumer）
• “主机 rHostAddr… 的运行状态是否足以进行租用？” → host_diagnostics（实时）
• “令牌门控论坛应该使用哪种模式？” → recommend_pattern
• “帮我找出德国最便宜的 5 台活跃 Evernode 主机。” → recommend_hosts（实时）
• “估算以每个时刻 2 EVR 的费率运行 3 节点集群 720 个时刻需要多少 EVR。” → estimate_lease_cost
• “为我的拆分器生成安全的 Xahau 结算，金额上限为 50 XAH。” → generate_settlement → 然后运行生成的 xahc prove 命令。

开发 / 测试 / CI

npm run build      # tsc → dist/
npm test           # build + Vitest (offline; mocks the live OnLedger fetch)
npm run smoke      # node dist/index.js --smoke — offline self-test
node dist/index.js # run as a stdio MCP server

• 测试（tests/）：determinism（规则覆盖，包括回归下限和新增缺口）、contractApi（正常合约无误报，并标记每种 API 误用）、advisor（租赁计算、主机排序、错误映射、模式 / 部署分支）、templates（逐模板构建、确定性检查通过、逐模板不变量）、settlement（LIM 编码和 trifecta 交接结构）、outputSchemas（每个处理程序的实际输出均符合已发布的架构）、index（端到端：通过内存 MCP 客户端驱动每个工具，并拒绝不符合输入架构的内容）、hostDiagnostics（模拟获取，验证运行正常 / 风险标记 / 未找到 / 获取失败时的准确性），以及 fetch（模拟请求，强化实时路径）。
• CI（.github/workflows/ci.yml）：推送到 main 和向 main 提交 PR 时，在 Node 20 上运行 npm ci、npm run build、npm test 和 npm run smoke。
• createServer()`` 从 src/index.ts` 导出，因此测试可以通过内存传输驱动服务，而无需启动 stdio 传输。

诚实的适用范围（回顾）

• 生成代码和指导；不会获取租约、签名或转移 EVR/XAH。不托管密钥。
• recommend_hosts 会从 OnLedger 获取实时数据（或为你提供的列表排序）——它绝不会编造主机地址或规格；获取失败时会返回空主机列表和解释原因的说明，绝不会提供编造的备用数据。
• check_determinism 和 check_contract_api 是启发式源代码扫描（主要使用逐行正则表达式）——提供指导，并非证明；check_determinism 倾向于对迭代／序列化类别过度标记，且存在已记录的盲点（裸浮点运算、多跳数据流）。在主网上线前，先在真实的多节点集群上测试。
• 结算安全性（Hook 支出限额）由 Hooks 工具链负责（xahc prove）——此服务会生成证明／安装命令，但绝不作出判定。防护 Hook 仅覆盖出站 Payment。
• generate_deploy_commands 和 explain_error 提供静态指导。命令语法已根据 evdevkit 0.7.22 和 hpdevkit 0.6.9（npm，2026-10-01）进行核对；如果你的版本不同，请查阅 Evernode 文档 或运行 --help。
• estimate_lease_cost 根据你提供的费率进行算术计算；主机自行设定费率。

许可证

MIT © 2026 Dane Brown。 开源；详见 LICENSE。与 Evernode Labs 或 Xahau 项目无关联。check_determinism 的发现仅为启发式指导，不构成保证——请务必 在多节点集群上测试，并在主网上线前进行审查。