zapper-mcp

Ein MCP-Server, der die Zapper DeFi-Portfolio-API als durchdachte Tool-Oberfläche für LLM-Clients bereitstellt. Verbinden Sie ihn mit Claude Desktop oder einem beliebigen MCP-kompatiblen Host und stellen Sie Fragen in natürlicher Sprache zu jedem Wallet – „Was ist dieses Wallet wert?“, „Hat es irgendwelche Aave-Positionen?“, „Zeige mir die Top-Bestände auf Base.“

Entwickelt an Tag 9 eines 21-tägigen KI-Engineering-Sprints. Tag 10 bindet diesen Server in einen Mastra-Agenten ein.

Tool-Oberfläche

Die Design-Begründung für jedes Primitive finden Sie in DESIGN.md. Die Kurzfassung:

Warum nicht ein großes get_everything-Tool? Das Zusammenfassen der Tools würde das Modell zwingen, für jede Frage eine große Antwort mit gemischtem Schema zu empfangen und zu parsen, selbst bei fokussierten Fragen. Eine Tool-Grenze ist eine Deklaration des Geltungsbereichs – das richtige Tool gibt genau das zurück, was der Argumentationsschritt benötigt.

Warum ist der API-Schlüssel in der Serverkonfiguration und nicht als Tool-Argument? Anmeldedaten gehören in die Host-Ebene (Umgebungsvariablen, die beim Prozessstart eingefügt werden), nicht in das MCP-Protokoll. Wenn api_key ein Tool-Parameter wäre, würde er durch die Argumentation des LLM fließen und im Konversationsverlauf erscheinen. Für eine Multi-Tenant-Bereitstellung ist der richtige Mechanismus eine Authentifizierung auf Transportebene (Bearer-Token über Streamable HTTP) oder OAuth pro Benutzer – beides ist hier nicht vorgesehen. Siehe Bekannte Einschränkungen.

Anforderungen

• Node.js 20+

• pnpm

• Ein Zapper API-Schlüssel

Installation

git clone https://github.com/mehdi-loup/zapper-mcp
cd zapper-mcp
pnpm install
pnpm build

Konfiguration

Kopieren Sie .env.example nach .env und fügen Sie Ihren Schlüssel hinzu:

cp .env.example .env
# edit .env and set ZAPPER_API_KEY=your_key_here

Der Server schlägt beim Start sofort fehl, wenn ZAPPER_API_KEY fehlt – Sie sehen den Fehler sofort, nicht erst beim ersten Tool-Aufruf.

Ausführen

Standalone-Smoke-Test (bestätigt, dass alles ohne Claude Desktop funktioniert):

ZAPPER_API_KEY=your_key pnpm client

Ausgabe: listet Tools/Ressourcen/Prompts auf und ruft dann jedes Tool für vitalik.eth auf.

Direkter Serverstart:

ZAPPER_API_KEY=your_key pnpm start

Claude Desktop-Anbindung

Hinzufügen zu ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zapper-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/zapper-mcp/build/server.js"],
      "env": {
        "ZAPPER_API_KEY": "your_key_here"
      }
    }
  }
}

Starten Sie Claude Desktop neu. Die drei Tools, die Ressource zapper://supported-networks und der Prompt analyze-wallet werden verfügbar sein.

Protokolle (falls der Server nicht geladen werden kann):

~/Library/Logs/Claude/mcp-server-zapper-mcp.log

Mastra-Integration (Tag 10)

Um diesen Server über den MCP-Client von Mastra in einen Mastra-Agenten einzubinden:

1. Starten Sie den Server: node /path/to/build/server.js

2. Konfigurieren Sie den Mastra MCP-Client mit stdio-Transport, Servername zapper-mcp

3. Der Agent konsumiert Zapper-Daten ausschließlich über MCP – lib/zapper.ts im Agent-Repo wird ungenutzt

Nicht alle Tools müssen für den Mastra-Agenten freigegeben werden; das ist eine Design-Entscheidung für Tag 10.

Tool-Referenz

get_portfolio(address, networks?)

Vollständige Portfolio-Aufschlüsselung: USD-Gesamtwert, alle Token-Bestände, alle DeFi-Positionen.

address   — wallet address or ENS name
networks  — optional array: ["ethereum", "base", "arbitrum", ...]

get_token_balances(address, networks?)

Nur Spot-Token-Guthaben (keine DeFi-Positionen).

get_app_positions(address, networks?, app_slug?)

Nur DeFi-App-Positionen (Aave, Uniswap, Sablier, etc.).

app_slug  — optional filter: "aave-v3", "uniswap-v3", ...

Ressource: zapper://supported-networks

JSON-Array von { name, chainId } für alle indizierten Netzwerke. Wird vom Host zur Zeit der Kontext-Erstellung gelesen.

Prompt: analyze-wallet

Initialisiert eine Portfolio-Analyse-Konversation vor. Erfordert ein address-Argument.

Fehlerbehandlung

Jedes Tool gibt isError: true mit einer für das Modell umsetzbaren Nachricht zurück bei:

• HTTP 401 / ungültiger API-Schlüssel

• HTTP 429 / Ratenbegrenzung überschritten

• HTTP 5xx / Zapper-Serverfehler

• Netzwerk-Timeout (15s)

• Fehlerhafte Antwort

Ein leeres Wallet (totalUSD: 0, tokens: []) gibt isError: false zurück – leer ist kein Fehler.

Bekannte Einschränkungen

• Single-Key-Vertrauensmodell: Der Server hält einen ZAPPER_API_KEY und bedient einen Eigentümer. Eine Multi-Tenant-Bereitstellung erfordert OAuth pro Benutzer oder eine Authentifizierung auf Transportebene (Streamable HTTP mit Bearer-Token).

• Kein Caching: Jeder Tool-Aufruf greift auf die Zapper-API zu. Ein Produktionsserver würde einen Cache mit kurzer TTL hinzufügen (Positionen ändern sich langsam) und Ratenbegrenzungen proaktiv einhalten.

• Kein resources/subscribe: zapper://supported-networks ist eine statische Liste. Live-Updates würden erfordern, dass der Server die Abonnement-Fähigkeit ankündigt und notifications/resources/updated ausgibt.

• Nur stdio-Transport: Streamable HTTP-Transport wurde auf eine zukünftige Iteration verschoben.

• Paginierungsgrenze: Tools geben bis zu 50 Token und 20 App-Positionen pro Anfrage zurück.

Was kommt als Nächstes

Tag 10: Einbindung dieses Servers in den Mastra-Wallet-Agenten unter ../day1-wallet-agent/ über den MCP-Client von Mastra. Der Agent wird Zapper-Daten ausschließlich über MCP konsumieren und damit validieren, dass die Tool-Oberfläche die Funktionalität tatsächlich vom Agent-Framework entkoppelt.