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)에 따라 관리됩니다.

계층 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, 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). 모든 계층 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에 기록되어 있습니다.

서비스는 src/가 아닌 dist/를 실행하므로, 빌드되지 않은 변경은 배포되지 않은 변경입니다.

도구 추가

1. src/tools/<category>/<name>.ts를 생성합니다. credit/yield-curve.ts를 템플릿으로 복사하세요 — 가장 깔끔한 작업 예제입니다.

2. 모든 필드에 .describe()를 사용하여 입력용 Zod 스키마를 정의합니다. 그 설명은 도구 발견 중 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. 모든 권리 보유.