bitcoincreditstack

gavel-mcp-server

Aletheia Analytics MCP サーバー — Gavel データプロダクトに対するエージェントネイティブなインターフェースです。

api.thegavel.io を利用する薄い TypeScript ラッパーです。Gavel のクレジットデータと Bitcoin のオンチェーン指標を MCP ツールとして公開することで、LLM 駆動のエージェント（Claude Desktop、IDE クライアント、カスタムエージェント）が、REST の接続処理を独自に実装せずにデータプロダクトを読み取れるようにします。

ステータス

AI コンシェルジュ仕様（aletheia-docs data/specs/mcp/ai_concierge.md）の 3 つのレイヤーすべてが、指標サーフェスと実際のキーからティアへの解決に加えて稼働しています。Runbook R18 によって実現され、決定事項は data/specs/mcp/tier_and_scope_decisions_v1.md（MD1–MD12）にまとめられています。

レイヤー A — 状態の読み取り

ツール	上流
check_wallet_status	直接 RPC（残高、使用許可、利用準備を妨げる要因）
find_auctions_matching_criteria	/v1/auctions
get_user_positions	/v1/user/:address/positions
get_loan_status	/v1/loans/:id/status

レイヤー B — ファクトリーモデル（未署名の設計データ。ユーザーが署名します）

ツール	エンコード内容
prepare_bid_calldata	placeBid ＋使用許可が不足している場合は承認
prepare_create_auction_calldata	createAuction ＋担保の承認
prepare_repay_loan_calldata	repayLoan ＋返済の承認
prepare_claim_collateral_calldata	claimCollateral
prepare_claim_refund_calldata	claimRefund

レイヤー C — カタログ

ツール	備考
list_wallet_options	静的カタログ。ランキングなし
recommend_fiat_onramp	静的カタログ。2 回の購入が必要なガス要件を含みます

データサーフェス

ツール	上流
list_gavel_indicators	32 個の指標を含む静的カタログ
get_gavel_indicator	/v1/credit/*、/v1/onchain/*、/v1/market/*
get_yield_curve	/v1/yield-curve
get_mvrv	/v1/onchain/mvrv
get_protocol_reference	静的 — アドレス、シグネチャ、規約
list_onchain_indicators	静的カタログ

不変条件

Aletheia が構築し、ユーザーが署名します。 このコードベースには署名機能がありません。ウォレットクライアント、アカウント、鍵素材は存在しません。viem は encodeFunctionData のみを目的にインポートされています。これにより、「Aletheia は決して署名しない」ことがポリシー上の約束ではなく、アーキテクチャ上の事実となります。この状態を維持する必要があります。

同様に重要な点として、ユーザーに代わってランキング、スコア付け、選択を行うツールはありません。 ユーザーが指定した基準による絞り込みは情報サービスですが、内部モデルによるランキングは投資助言にあたります。find_auctions_matching_criteria という名前は意図的に付けられており、単なる見た目の問題ではありません。

アーキテクチャ

LLM Client → mcp.thegavel.io (this server) → api.thegavel.io (REST) → PostgreSQL
              [tool catalog, descriptions,        [authoritative endpoints]
               response shaping, auth, limits]

単一の信頼できる情報源は REST API です。MCP サーバーが Postgres を直接クエリすることは決してありません。ツールは LLM が利用しやすいようにレスポンスを整形します（JSON 文字列化したテキストコンテンツ）が、ビジネスロジックを再実装することはありません。REST API がアップグレードされると、MCP にも自動的に反映されます。

ローカル開発

# Install deps (Node 20+)
npm install

# Copy and edit env file
cp .env.example .env
nano .env  # set GAVEL_API_BASE_URL etc.

# Dev mode (tsx watch)
npm run dev

# Type check
npm run typecheck

# Build to dist/
npm run build

開発用 MCP クライアント（MCP Inspector、HTTP コネクターを使用する Claude Desktop）から http://localhost:3002/mcp に接続して、ツールを試してください。

デプロイ

デプロイ先：gavel-api と同じ gavel-btc Hetzner ホストです。

# Local — build and stage
npm install
npm run build

# Copy to server
scp -r dist/ package.json package-lock.json deployment/ \
    root@gavel-btc:/root/gavel-mcp/

# On server — install runtime deps (not the full dev set)
ssh root@gavel-btc
cd /root/gavel-mcp
npm install --omit=dev

# Configure
cp .env.example .env
nano .env
# Set:
#   GAVEL_API_BASE_URL=https://api.thegavel.io  (public API, for tool reads)
#   GAVEL_API_INTERNAL_URL=http://127.0.0.1:4012  (loopback, for tier lookup)
#   INTERNAL_API_SECRET=<must match gavel-indexer/.env.mainnet>
#   PORT=3002
#   NODE_ENV=production

# Install systemd unit
cp deployment/gavel-mcp.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable gavel-mcp.service
systemctl start gavel-mcp.service

# Verify
journalctl -u gavel-mcp -n 50 --no-pager
curl http://localhost:3002/health

# Reverse proxy
cp deployment/nginx-mcp.conf /etc/nginx/sites-available/mcp.thegavel.io
ln -s /etc/nginx/sites-available/mcp.thegavel.io \
      /etc/nginx/sites-enabled/mcp.thegavel.io
nginx -t && systemctl reload nginx

# TLS (Let's Encrypt)
certbot --nginx -d mcp.thegavel.io

# End-to-end check
curl https://mcp.thegavel.io/health

設定

すべての設定項目は .env にあります。

変数	デフォルト値	用途
PORT	3002	HTTP の待ち受けポート
NODE_ENV	—	JSON ログの場合は production
LOG_LEVEL	info	pino のログレベル（trace／debug／info／warn／error）
GAVEL_API_BASE_URL	http://localhost:3001	上流 REST のベース URL
RATE_LIMIT_ANONYMOUS_PER_MINUTE	60	匿名ユーザー用バケットのサイズ
RATE_LIMIT_PAID_PER_MINUTE	300	有料ユーザー用バケットのサイズ
CORS_ALLOWED_ORIGINS	空	カンマ区切り。空の場合は CORS 無効
HEALTH_CHECK_SECRET	空	設定すると、/health に ?secret=... が必要になります
GAVEL_API_INTERNAL_URL	http://127.0.0.1:4012	キーからティアへの照合。ループバックアドレスを指定してください。/internal/resolve-tier は X-Forwarded-For を含むリクエストを拒否するため、公開ホスト api.thegavel.io は使用できません
INTERNAL_API_SECRET	空	ティア照合に使う共有シークレット。gavel-indexer/.env.mainnet と一致させる必要があります。未設定の場合 ⇒ すべての呼び出し元が free と判定されます
MCP_TIER_ENFORCEMENT	false	ツールごとのティアを適用します。Gate B までは false のままにしてください。ティアモデルを参照
ARBITRUM_RPC_URL	公開 RPC	Layer A/B のチェーン読み取り。本番環境では有料エンドポイントを指定してください
ARBITRUM_SEPOLIA_RPC_URL	公開 RPC	テストネット用の同等項目

ティアモデル

ティアは free / pro / enterprise です。これはプロダクト（gavel-indexer/lib/tiers.js）および Stripe が販売するティアと同一です。スキャフォールドの元の anonymous / developer / professional / enterprise は、1 つの利用権限に対する別の語彙であり、廃止されています（MD1）。

キーのティアを判断する権威は、gavel-indexer/lib/api-keys.js のみです。MCP は独自のデータベース接続プールを開かず、ループバック経由で GET /internal/resolve-tier を呼び出し、その結果を 60 秒間キャッシュします。また、エラーが発生した場合は安全側に倒して free と判定します。キーのデータベースに一時的な問題が起きたために 500 を返すデータ MCP より、一時的に匿名ユーザー向けのサービスを提供する方が望ましいためです。

適用機能は実装済みですが、無効です

MCP_TIER_ENFORCEMENT のデフォルトは false で、現時点ではこれが正しい状態です。収益化は Gate B（D16～D18）まで保留されています。支払いを希望する人が現れるまでは、ペイウォールを構築しないでください。 Runbook A2 で商用機能を取り下げており、現在 www.thegavel.io/pricing ではデータアクセスは無料かつオープンだと明記されています。そのため、ツールの利用を拒否し、ティアの存在を否定するページにユーザーを誘導するのは、自己矛盾した体験になります。

このフラグがオフの場合でも、requireTier は呼び出し元の実際のティアを照会し、拒否していたであろう内容をログに記録します。このログが、ゲート条件 M6「実際に支払いを希望した人はいるのか？」の根拠となります。

有効にする前に、MD2 を読んでください。有料 MCP の意味について、互換性のない解釈が 2 つあります。サーフェス全体を有料にする方式（lib/tiers.js で free に mcp: false を設定）と、深さに応じて有料にする方式（推奨されている MD3）です。これはまったく異なるプロダクトです。

無料で利用できるものとその理由

MD3 に基づき、D5 のルート／深さのマップを継承すると、オンチェーンの生データ、オークションの検索、ウォレットのステータス、コモディティのオンチェーン指標、Gavel による評価の現在の値、および履歴はすべて無料です。D9 で REST の 30 日間の上限が廃止されたため、履歴も無料です。MCP は、参照先のサーフェスが撤廃した制限を再導入してはなりません。有料となる境界は一括配信ですが、このサーバーは提供していません。

参加が制限されることはありません（D3）。Layer A/B/C のすべてのツールは free です。入札しようとするユーザーが、入札を決めてから実際に参加できるまでの間にペイウォールに遭遇してはなりません。

レート制限はインフラストラクチャを保護するものであり、課金の計測器ではありません（D2）。また、適用機能のフラグの状態にかかわらず適用されます。

変更の再デプロイ

npm run build            # tsc -> dist/ ; must be clean
systemctl restart gavel-mcp
systemctl is-active gavel-mcp
journalctl -u gavel-mcp -n 30 --no-pager

このサービスは systemd で動作しており、pm2 ではありません。 このホスト上の pm2 が管理しているのは quorum-mcp-testnet という別のサービスです。pm2 restart gavel-mcp は、デプロイに成功したように見えるだけで、何も行いません。R18 v1 ではこの点を誤っていたため、該当する Runbook の §8 に記録されています。

このサービスは src/ ではなく dist/ を実行するため、ビルドされていない変更はデプロイされません。

ツールの追加

1. src/tools/<category>/<name>.ts を作成します。テンプレートとして credit/yield-curve.ts をコピーします。最もすっきりした実例です。
2. 入力用の Zod スキーマを定義し、すべてのフィールドに .describe() を付けます。この説明を LLM がツールの検出時に参照します。
3. ツールの説明を複数行の文字列として記述します。指標の説明から始め、解釈のための背景情報（何かを推奨することなく）を示し、レスポンスの形式を記載します。MCP SDK はこの内容をカタログでそのまま使用します。
4. 本文では、requireTier(...) → upstreamGet(...) の順に実行し、{ content: [{ type: 'text', text: JSON.stringify(...) }] } を返します。
5. src/tools/index.ts にツールを登録します。
6. src/tools/discovery/list-onchain.ts（または、そのドメインに対応する検出カタログ）に項目を追加します。

手動テスト

# 1. Health
curl -s http://localhost:3002/health | jq

# 2. MCP Inspector
npx @modelcontextprotocol/inspector
# Connect to http://localhost:3002/mcp
# Verify: tools/list returns 3 tools, get_yield_curve returns live data,
# get_mvrv returns a structured McpError "not found".

ライセンス

プロプライエタリ © 2026 Aletheia Analytics SASU. All rights reserved.