gavel-mcp-server

Aletheia Analytics MCP 服务器 — 面向 Gavel 数据产品的代理原生接口。

围绕 api.thegavel.io 的轻量 TypeScript 封装。将 Gavel 信用数据和比特币链上指标作为 MCP 工具暴露，使 LLM 驱动的代理（Claude Desktop、IDE 客户端、自定义代理）无需手动编写 REST 胶水代码即可读取数据产品。

状态

AI 礼宾规范（aletheia-docs data/specs/mcp/ai_concierge.md）的所有三层均已上线，此外还有指标表面和真实的密钥→层级解析。由 Runbook R18 交付，并受决策说明 data/specs/mcp/tier_and_scope_decisions_v1.md（MD1–MD12）约束。

Layer A — 读取状态

Layer B — 工厂模型（未签名的蓝图；用户签名）

Layer C — 目录

数据表面

不变式

Aletheia 构建；用户签名。 此代码库中没有签名表面 — 没有钱包客户端、没有账户、没有密钥材料。viem 仅用于导入 encodeFunctionData。这正是使“Aletheia 永不签名”成为架构事实而非政策承诺的原因，并且必须保持这种状态。

同样重要：没有工具代表用户进行排名、评分或选择。 按用户提供的条件进行过滤是一种信息服务；按内部模型进行排名则是投资建议。find_auctions_matching_criteria 的命名是刻意的，并非装饰性的。

Related MCP server: Stelar Signals MCP

架构

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-btc Hetzner 主机，与 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 中：

层级模型

阶梯是 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。一个因密钥数据库故障而返回 500 的数据 MCP 比一个短暂提供匿名服务的更糟糕。

强制已编写但处于关闭状态

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 取消了 30 天 REST 上限，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 中。

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

添加工具

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。保留所有权利。