hosannaith-mcp

Hosannaith

Algorand Mainnet で稼働中の、呼び出しごとに支払う x402 信頼性オラクルです。

🔗 ライブアプリ： hosannaith.com · API： api.hosannaith.com · リポジトリ： github.com/cameron4316/x402-oracle-server

問題

x402 によって API がリクエストごとの従量課金サービスになるにつれ、エージェントが自分で構築していないエンドポイントに支払う機会が増えています。しかし、実際の 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 を返します。

オンチェーンで検証可能： Mainnet での最初の決済 — 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 エージェント（Model Context Protocol）から使う

このリポジトリには mcp/ に MCP サーバー も含まれています。npm では hosannaith-mcp として公開され、公式の MCP Registry には io.github.cameron4316/hosannaith-mcp として登録されています。あらゆる Model Context Protocol クライアント（Claude Desktop、Cursor、その他の MCP エージェント）が、x402 エンドポイントに支払う前にその信頼性を確認できます。

公式 MCP TypeScript SDK（@modelcontextprotocol/sdk）を基盤とし、3 つの MCP ツール を公開します。

• get_hosannaith_info — 無料。スコアの形式とその活用方法を説明します。
• check_x402_reliability — 有料。単一のエンドポイントの信頼性スコアを、Algorand 上で x402 による USDC のマイクロペイメントとして決済します。
• check_x402_reliability_batch — 有料。1 回の呼び出しで最大 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 を参照）を実装します。最初に提供するのは信頼性チェックです。トークン化向けの コンプライアンス／証明 製品、つまり機関が実世界の資産をオンチェーンに移行するために必要な信頼レイヤーは、2 つ目の Check とルートエントリー 1 つを追加する形で計画しており、決済処理を作り直す必要はありません。

モニター（本番環境の droplet で pnpm monitor を継続実行）は、各対象について、各間隔で 1 件の観測結果を data/observations.jsonl に追記専用で記録します。この履歴は時間とともに積み重なり、後から再構築することはできません。上記のスコアはすべて、合成推定値ではなく、実際の継続的な観測に基づいています。

---

開発者向け

以下は、Hosannaith をローカルで実行する（デフォルトでは testnet）ため、またはコードベースを理解するためのセットアップ／リファレンスです。上記のライブ 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 を保有し、testnet USDC のオプトインを済ませた testnet アカウント。
• ここでは NETWORK=testnet と GoPlausible の FACILITATOR_URL はそのままにします。
• MONITOR_TARGETS はすでに Foundation の公開サンプルエンドポイントを参照しています。

testnet のセットアップ（アカウント、フォーセット、USDC のオプトイン）については、公式チュートリアルをご覧ください。 https://dev.algorand.co/resources/x402-on-algorand/

3. 実行（ターミナルを2つ使用）

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)

Mainnet は稼働中 — CAIP-2 のオーバーライドを正確に解説

src/config.ts の FACILITATOR_TESTNET_CAIP2 と MAINNET_CAIP2 は、@x402/avm からインポートせず、ハードコードされています。これは意図的なものであり、見落としではありません。実際の経緯は次のとおりです。

@x402/avm がエクスポートする ALGORAND_TESTNET_CAIP2 / ALGORAND_MAINNET_CAIP2 は、Algorand CAIP-2 名前空間プロファイルに準拠した、仕様どおりの短縮形式の CAIP-2です（x402-foundation/x402 の Issue #2904 / PR #2931 で上流に修正が取り込まれました）。問題はこのパッケージではありません。稼働中の GoPlausible ファシリテーター（facilitator.goplausible.xyz）は、上流より数百コミット遅れており、この修正より前の状態のフォークである GoPlausible/x402-avm を実行しています。そのため、/supported エンドポイントはテストネットとメインネットの両方で、レガシーな非準拠の完全なジェネシスハッシュ形式を引き続き公開しています。このサーバーでは、推測やパッケージ内の定数ではなく、curl https://facilitator.goplausible.xyz/supported で実稼働環境から確認した、ファシリテーターが実際に期待する値をハードコードしています。

GoPlausible がフォークを同期して上流の修正を取り込んだ場合は、両方の定数を @x402/avm からインポートする形に戻す必要があります。詳細な理由については、src/config.ts の各定数のコメントを参照してください。上流の x402-foundation/x402 に追跡用の報告を提出済みです（GoPlausible 自身のフォークでは Issue の作成が制限されていたため、そちらへの報告はできませんでした）。

このサーバーを自分でメインネットに接続して実行するには、NETWORK=mainnet を設定し、メインネットの USDC にオプトイン済みの固定の payTo アドレスを AVM_ADDRESS に設定してください（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 のディスカバリー／Bazaar パッケージ @x402-avm/extensions は別のバージョン管理となっており、現在は ^2.6.1 です。正確な解決済みバージョンは pnpm ls を実行して確認してください）。
• 依存関係のバージョンを更新した場合は、API の差異を検出するため、pnpm install の後に pnpm typecheck を実行してください。