gavel

gavel-mcp-server

Aletheia Analytics MCP 服务——Gavel 数据产品的原生 Agent 接口。

这是一个围绕 api.thegavel.io 构建的轻量 TypeScript 封装。它将 Gavel 信用数据和 Bitcoin 链上指标作为 MCP 工具公开，使由大模型驱动的 Agent（Claude Desktop、IDE 客户端、自定义 Agent）无需手动编写 REST 接口代码即可读取数据产品。

状态

AI concierge 规范（aletheia-docs data/specs/mcp/ai_concierge.md）的三个层都已上线，指标接口和真实的密钥→层级解析也已上线。由 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	静态目录；说明了两次购买的 Gas 要求

数据接口

工具	上游
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 负责构建；用户负责签名。 此代码库中没有签名接口——没有钱包客户端、没有账户，也没有密钥材料。仅为 encodeFunctionData 导入了 viem。正因如此，“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。工具会将响应整理成便于大模型使用的形式（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，即可测试工具。

部署

目标主机：Hetzner 的 gavel-btc，与 gavel-api 同机部署。

# 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	—	设置为 production 时输出 JSON 日志
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 是对同一项权益的另一套命名， 现已弃用（MD1）。

gavel-indexer/lib/api-keys.js 是密钥等级的唯一权威来源。 MCP 不会自行建立数据库连接池；它会通过环回地址请求 GET /internal/resolve-tier，缓存结果 60 秒，并在任何错误时 默认放行至 free。数据 MCP 因密钥数据库短暂故障而返回 500， 比短暂向匿名用户开放更糟。

已编写等级限制逻辑，但尚未启用

MCP_TIER_ENFORCEMENT 默认为 false，这也是目前正确的状态。 变现功能要等到 Gate B（D16–D18）才会启用：在有人表示愿意付费之前，不要构建付费墙。 Runbook A2 撤下了商业功能界面，而 www.thegavel.io/pricing 目前声明数据访问免费且开放——因此拒绝提供工具，同时把用户指向一个否认存在等级限制的页面，会让整个用户流程自相矛盾。

关闭该标志时，requireTier 仍会解析调用方的实际等级，并记录它本来会拒绝哪些请求。该日志是 M6（“是否真的有人表示愿意付费？”）这一门槛条件的证据。

启用之前，请阅读 MD2。对于付费 MCP 的含义，存在两种互不兼容的解读——整个服务界面付费（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 在这里记录有误；该问题已记录在对应运行手册的 §8 中。

此服务运行的是 dist/，而非 src/，因此未构建的变更就等于未部署的变更。

添加工具

1. 创建 src/tools/<category>/<name>.ts。以 credit/yield-curve.ts 为模板，这是最简洁的完整示例。
2. 使用 Zod 定义输入 schema，并为每个字段添加 .describe()；大模型在发现工具时会看到这些描述。
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。保留所有权利。