gavel-mcp-server

Aletheia Analytics MCP-Server – agenten-native Schnittstelle zum Gavel-Datenprodukt.

Dünner TypeScript-Wrapper um api.thegavel.io. Stellt Gavel-Kreditdaten und Bitcoin-On-Chain-Indikatoren als MCP-Tools bereit, sodass LLM-gesteuerte Agenten (Claude Desktop, IDE-Clients, benutzerdefinierte Agenten) das Datenprodukt lesen können, ohne REST-Kleber selbst zu bauen.

Status

Alle drei Ebenen der AI-Concierge-Spezifikation (aletheia-docs data/specs/mcp/ai_concierge.md) sind live, plus die Indikatoroberfläche und die echte Schlüssel→Stufen-Auflösung. Geliefert durch Runbook R18 und geregelt durch die Entscheidungsnotiz data/specs/mcp/tier_and_scope_decisions_v1.md (MD1–MD12).

Ebene A – Zustand lesen

Ebene B – Fabrikmodel (unsignierte Blaupausen; der Benutzer signiert)

Ebene C – Kataloge

Datenoberfläche

Die Invariante

Aletheia baut; der Benutzer signiert. Es gibt keine Signaturoberfläche in dieser Codebasis – kein Wallet-Client, kein Konto, kein Schlüsselmaterial. viem wird nur für encodeFunctionData importiert. Das macht „Aletheia signiert nie" zu einer architektonischen Tatsache statt zu einem Politikversprechen, und das muss so bleiben.

Ebenso tragend: Kein Tool bewertet, bewertet oder wählt im Namen des Benutzers. Das Filtern nach benutzerdefinierten Kriterien ist ein Informationsdienst; das Bewerten durch ein internes Modell ist Anlageberatung. find_auctions_matching_criteria ist bewusst so benannt, und die Benennung ist nicht kosmetisch.

Related MCP server: Stelar Signals MCP

Architektur

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

Einzige Quelle der Wahrheit: die REST-API. Der MCP-Server fragt niemals Postgres direkt ab. Tools formen Antworten für den LLM-Konsum (JSON-stringifizierter Textinhalt), implementieren aber niemals Geschäftslogik neu. Wenn die REST-API aktualisiert wird, übernimmt MCP das Upgrade automatisch.

Lokale Entwicklung

# 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

Richten Sie einen Entwicklungs-MCP-Client (MCP Inspector, Claude Desktop mit HTTP-Connector) auf http://localhost:3002/mcp aus, um Tools zu testen.

Bereitstellung

Ziel: gavel-btc Hetzner-Host, neben 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

Konfiguration

Alle Einstellungen leben in .env:

Stufenmodell

Die Leiter ist free / pro / enterprise – identisch mit dem Produkt (gavel-indexer/lib/tiers.js) und dem, was Stripe verkauft. Das ursprüngliche anonymous / developer / professional / enterprise des Gerüsts war ein zweites Vokabular für eine Berechtigung und ist zurückgezogen (MD1).

gavel-indexer/lib/api-keys.js ist die Autorität dafür, welche Stufe ein Schlüssel hat. Der MCP öffnet keinen eigenen Datenbank-Pool; er fragt GET /internal/resolve-tier über Loopback, cached die Antwort für 60 s und fällt bei jedem Fehler offen auf free zurück. Ein Daten-MCP, das mit 500 antwortet, weil die Schlüsseldatenbank einen Aussetzer hatte, ist schlechter als eines, das kurzzeitig anonym bedient.

Durchsetzung ist geschrieben, aber AUS

MCP_TIER_ENFORCEMENT ist standardmäßig false, und das ist heute der korrekte Zustand. Monetarisierung ist bis Gate B (D16–D18) gesperrt: bauen Sie keine Bezahlschranke, bis jemand zu zahlen gebeten hat. Runbook A2 hat die kommerzielle Oberfläche zurückgezogen, und www.thegavel.io/pricing sagt derzeit, dass der Datenzugriff kostenlos und offen ist – einem Tool zu verweigern und den Benutzer auf eine Seite zu verweisen, die die Existenz von Stufen leugnet, wäre eine selbstwiderlegende Reise.

Bei deaktiviertem Flag löst requireTier dennoch die echte Stufe des Aufrufers auf und protokolliert, was es verweigert hätte. Dieses Log ist der Beleg für M6, die „Hat tatsächlich jemand zu zahlen gebeten?"-Gate-Bedingung.

Bevor Sie es einschalten, lesen Sie MD2. Es gibt zwei unvereinbare Lesarten dessen, was ein bezahltes MCP bedeutet – ganze Oberfläche bezahlt (lib/tiers.js trägt mcp: false auf free) versus Tiefe bezahlt (MD3, die befürwortete). Das sind sehr unterschiedliche Produkte.

Was kostenlos ist und warum

Gemäß MD3, das die D5-Routen-/Tiefenkarte erbt: roher On-Chain-Zustand, Auktionserkennung, Wallet-Status, Rohstoff-On-Chain-Indikatoren, der aktuelle Wert jeder Gavel-abgeleiteten Bewertung und Historie sind alle kostenlos. Historie ist kostenlos, weil D9 die 30-Tage-REST-Begrenzung zurückgezogen hat und der MCP keinen Zaun wieder einführen darf, den die Oberfläche, die er spiegelt, aufgegeben hat. Die bezahlte Grenze ist Massenlieferung, die dieser Server nicht anbietet.

Teilnahme ist nie gesperrt (D3). Jedes Tool der Ebene A/B/C ist free: Ein potenzieller Bieter darf niemals zwischen der Entscheidung zu bieten und der Möglichkeit dazu auf eine Bezahlschranke treffen.

Ratenbegrenzungen sind Infrastrukturschutz, kein Abrechnungszähler (D2), und gelten unabhängig vom Durchsetzungsflag.

Erneutes Bereitstellen einer Änderung

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

Dieser Dienst ist systemd, nicht pm2. pm2 auf diesem Host trägt quorum-mcp-testnet, einen anderen Dienst – pm2 restart gavel-mcp ist ein No-op, das wie eine erfolgreiche Bereitstellung aussieht. R18 v1 hatte das falsch; es ist in §8 dieses Runbooks festgehalten.

Der Dienst läuft dist/, nicht src/, also ist eine Änderung, die nicht gebaut ist, eine Änderung, die nicht bereitgestellt ist.

Hinzufügen eines Tools

1. Erstellen Sie src/tools/<category>/<name>.ts. Kopieren Sie credit/yield-curve.ts als Vorlage – es ist das sauberste ausgearbeitete Beispiel.

2. Definieren Sie ein Zod-Schema für Eingaben mit .describe() auf jedem Feld; diese Beschreibung ist das, was der LLM während der Tool-Erkennung sieht.

3. Schreiben Sie die Tool-Beschreibung als mehrzeiligen String. Beginnen Sie mit dem, was der Indikator ist, geben Sie interpretativen Kontext (ohne etwas zu empfehlen) und dokumentieren Sie die Antwortform. Das MCP-SDK verwendet dies wörtlich im Katalog.

4. Körper: requireTier(...) → upstreamGet(...) → geben Sie { content: [{ type: 'text', text: JSON.stringify(...) }] } zurück.

5. Registrieren Sie das Tool in src/tools/index.ts.

6. Fügen Sie einen Eintrag in src/tools/discovery/list-onchain.ts hinzu (oder den entsprechenden Erkennungskatalog für diese Domäne).

Manuelles Testen

# 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".

Lizenz

Proprietär © 2026 Aletheia Analytics SASU. Alle Rechte vorbehalten.