gavel-mcp-server

Aletheia Analytics MCP-сервер — агент-нативный интерфейс к продуктовым данным Gavel.

Тонкая TypeScript-обёртка вокруг api.thegavel.io. Предоставляет кредитные данные Gavel и ончейн-индикаторы Bitcoin как 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).

Слой A — чтение состояния

Слой B — фабричная модель (неподписанные чертежи; подписывает пользователь)

Слой 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, Claude Desktop с HTTP-коннектором) на 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:

Модель уровней

Лестница: 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 через loopback, кэширует ответ на 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 несёт mcp: false на free) против платы за глубину (MD3, одобренная). Это очень разные продукты.

Что бесплатно и почему

Согласно MD3, наследуя карту маршрутов/глубины D5: сырое ончейн-состояние, обнаружение аукционов, статус кошелька, товарные ончейн-индикаторы, текущее значение любой оценки, производной от Gavel, и история — всё бесплатно. История бесплатна, потому что D9 отменил 30-дневный REST-лимит, и MCP не должен вводить заново забор, который отказалась от поверхности, которую он отражает. Платная граница — пакетная доставка, которую этот сервер не предлагает.

Участие никогда не ограничивается (D3). Каждый инструмент слоёв 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 — это no-op, который выглядит как успешное развёртывание. В R18 v1 это было неправильно; это записано в §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. Все права защищены.