hosannaith-mcp

Hosannaith

基于 x402、按调用付费的可靠性预言机——已在 Algorand 主网运行。

🔗 在线应用： hosannaith.com · API： api.hosannaith.com · 代码仓库： github.com/cameron4316/x402-oracle-server

问题

随着 x402 将 API 变为按请求付费的服务，Agent 越来越常需要向自己并未构建的端点付费——却无法在发送真实 USDC 前判断端点是否可靠。失效或行为异常的端点会悄无声息地浪费资金，并导致自动化流程中断。

功能

Hosannaith 本身就是一个 x402 端点。它会独立、持续地监控其他 x402 端点，并按需出售经过验证的可靠性评分：正常运行时间、正确的 402 行为以及延迟百分位数；评分由真实累积的历史记录支撑——每个响应都会标示其置信度（"history" 表示评分有历史记录支撑，"one-shot" 表示首次查询该目标）。这是 x402 对 x402 的监控。

GET https://api.hosannaith.com/reliability?target=<x402-endpoint-url>

未付款的请求会收到 402 Payment Required 响应和付款说明；已付款请求会通过 GoPlausible facilitator 在 Algorand 上以 USDC 结算，并返回类似以下内容的 JSON：

可在链上验证： 首笔主网结算 — 3F2ATV3NCRVOI45IEL6OUKAWED3NQX246WJADESJB5CFR6LIXGCQ

{
  "target": "https://x402.example.com/api",
  "status": "pass",
  "score": 98.7,
  "detail": {
    "observations": 1439,
    "windowHours": 24,
    "uptimePct": 100,
    "correct402Pct": 100,
    "p50LatencyMs": 88,
    "p95LatencyMs": 127,
    "confidence": "history"
  }
}

在你自己的代码中使用

一个精简的 TypeScript SDK 封装了完整的 x402 按调用付费握手流程（402 → 签署 USDC 付款 → 重试），无需自行实现：

import { getReliability } from 'hosannaith-client';

const result = await getReliability('https://some-x402-endpoint/api', {
  mnemonic: process.env.AVM_MNEMONIC!, // 25-word Algorand mnemonic, funded with USDC
});

console.log(result.score, result.detail.confidence);

参见 sdk/typescript/，了解客户端、可运行示例和完整使用文档。

从任意 MCP Agent（Model Context Protocol）使用

本代码仓库还提供了一个 MCP 服务，位于 mcp/——已发布到 npm，名称为 hosannaith-mcp，并列入官方 MCP Registry，名称为 io.github.cameron4316/hosannaith-mcp。 它让任何 Model Context Protocol 客户端（Claude Desktop、Cursor 和其他 MCP Agent）都能在为 x402 端点付款前，评估其可靠性。

该服务基于官方 MCP TypeScript SDK（@modelcontextprotocol/sdk）构建，提供三个 MCP 工具：

• get_hosannaith_info — 免费；说明评分结构以及如何使用评分。
• check_x402_reliability — 付费；查询单个端点的可靠性评分，并通过 x402 在 Algorand 上以 USDC 小额付款结算。
• check_x402_reliability_batch — 付费；单次调用最多评估 50 个端点。

将其添加到 MCP 客户端的配置中：

{
  "mcpServers": {
    "hosannaith": {
      "command": "npx",
      "args": ["-y", "hosannaith-mcp"],
      "env": { "AVM_MNEMONIC": "<25-word Algorand mnemonic, funded with USDC>" }
    }
  }
}

参见 mcp/，了解 MCP 服务、其工具和完整设置文档。

架构与愿景

该架构刻意设计为可插拔：每个付费产品都实现 Check 契约（参见 src/checks/types.ts）。可靠性功能率先推出；面向代币化的合规/证明产品——这是机构将现实世界资产引入链上所需的信任层——计划作为第二个 Check 加一条路由推出，无需重写支付流程。

监控器（pnpm monitor，在生产服务器上持续运行）会按间隔为每个目标记录一次观测结果，以仅追加的方式写入 data/observations.jsonl。这些历史记录会不断累积，且之后无法重建——以上每项评分都有真实、持续的观测记录支撑，而非合成估算。

---

开发者指南

以下内容均为在本地运行 Hosannaith（默认使用测试网）的设置和参考资料，或用于了解代码库——使用上文的在线 API 无需这些内容。

---

1. 安装

pnpm install
# runtime deps (exact packages from the official Algorand tutorial):
pnpm add @x402/core @x402/avm @x402/hono @x402-avm/extensions hono @hono/node-server dotenv

2. 配置

cp .env.example .env

然后编辑 .env：

• AVM_ADDRESS — 一个测试网账户，需存入 ALGO 并选择加入测试网 USDC。
• 目前保持 NETWORK=testnet 和 GoPlausible 的 FACILITATOR_URL 不变。
• MONITOR_TARGETS 已指向 Foundation 的公开示例端点。

测试网设置（账户、水龙头、USDC 选择加入）请参照官方教程： https://dev.algorand.co/resources/x402-on-algorand/

3. 运行（两个终端）

pnpm monitor   # terminal 1 — starts collecting observations immediately
pnpm dev       # terminal 2 — starts the paid resource server on :4021

完整性检查：

curl http://localhost:4021/health                 # -> {"ok":true,...}  (free)
curl -i "http://localhost:4021/reliability?target=https://x402.goplausible.xyz/examples/weather"
#  -> HTTP 402 Payment Required  (correct: it's a PAID route)

如需付款并获取返回的 JSON，请将教程中的客户端指向 http://localhost:4021/reliability?target=...（客户端代码： https://dev.algorand.co/resources/x402-on-algorand/#part-1-build-the-client）。

---

文件结构

src/
  index.ts              Hono app + x402 wiring (edit sparingly)
  monitor.ts            Standalone monitor process (pnpm monitor)
  config.ts             Network/asset/facilitator config; testnet<->mainnet switch
  routes.config.ts      Paid routes + Bazaar discovery metadata  <-- add compliance route here
  checks/
    types.ts            The pluggable Check contract (shared by all products)
    registry.ts         Maps check id -> implementation
    reliability/
      monitor.ts        probe() + startMonitor()
      store.ts          Observation type + append-only JSONL store (swappable)
      score.ts          Turns observations into a 0-100 score
      index.ts          The reliability Check (reads store, computes score)
data/
  observations.jsonl    Append-only history (git-ignored; compounding)

主网已上线——准确说明 CAIP-2 覆盖项

src/config.ts 中的 FACILITATOR_TESTNET_CAIP2 和 MAINNET_CAIP2 是硬编码的，并非从 @x402/avm 导入——这是有意为之，并非疏忽。实际情况如下：

@x402/avm 导出的 ALGORAND_TESTNET_CAIP2 / ALGORAND_MAINNET_CAIP2 是符合规范的截断版 CAIP-2 格式（依据 Algorand CAIP-2 命名空间配置文件；已在上游 x402-foundation/x402 issue #2904 / PR #2931 中修复）。问题不在这个包。在线的 GoPlausible facilitator（facilitator.goplausible.xyz）运行的是 GoPlausible/x402-avm，这是一个比上游落后数百次提交的分支，早于该修复——因此，其 /supported 端点在测试网和主网上仍会公布旧版、不符合规范的完整创世哈希格式。本服务硬编码了 facilitator 实际要求的值，这些值已通过 curl https://facilitator.goplausible.xyz/supported 在线验证，并非猜测，也不是包中的常量。

如果 GoPlausible 将其分支同步到上游修复，则必须将这两个常量恢复为从 @x402/avm 导入——完整说明请参阅 src/config.ts 中各常量旁的注释。我们已向上游 x402-foundation/x402 提交跟踪报告（GoPlausible 自己的分支限制创建 issue，因此无法在该处提交）。

如需自行在主网上运行此服务：设置 NETWORK=mainnet，并将 AVM_ADDRESS 设为已选择加入主网 USDC 的固定收款地址（ASA 31566704，已在 src/config.ts 中设置）。routes.config.ts 的 extra 属性中的 tag 字段用于将活动归属到 Algorand Global x402 Challenge。

注意事项

• 跟踪 x402 协议 2.26.0（package.json 为 @x402/core、@x402/avm 和 @x402/hono 固定了 ^2.26.0；Algorand discovery/Bazaar 包 @x402-avm/extensions 的版本单独管理，目前为 ^2.6.1——运行 pnpm ls 查看确切解析版本）。
• 在 pnpm install 后运行 pnpm typecheck，以便在升级依赖版本时检查 API 是否发生变化。