zapper-mcp

Un servidor MCP que expone la API de portafolio DeFi de Zapper como una superficie de herramientas cuidadosamente diseñada para clientes LLM. Conéctalo a Claude Desktop o a cualquier host compatible con MCP y haz preguntas en lenguaje natural sobre cualquier billetera: "¿cuánto vale esta billetera?", "¿tiene alguna posición en Aave?", "muéstrame las principales tenencias en Base".

Construido en el día 9 de un sprint de ingeniería de IA de 21 días. El día 10 conecta este servidor a un agente de Mastra.

Superficie de herramientas

La justificación del diseño para cada primitiva se encuentra en DESIGN.md. La versión corta:

¿Por qué no una gran herramienta get_everything? Colapsar las herramientas obligaría al modelo a recibir y analizar una respuesta de esquema mixto grande para cada pregunta, incluso las enfocadas. Un límite de herramienta es una declaración de alcance: la herramienta correcta devuelve exactamente lo que el paso de razonamiento necesita.

¿Por qué la clave API está en la configuración del servidor y no como argumento de herramienta? Las credenciales pertenecen a la capa del host (variables de entorno inyectadas al iniciar el proceso), no al protocolo MCP. Si api_key fuera un parámetro de herramienta, fluiría a través del razonamiento del LLM y aparecería en el historial de la conversación. Para un despliegue multi-inquilino, el mecanismo correcto es la autenticación en la capa de transporte (token Bearer sobre HTTP transmitible) o OAuth por usuario; ambos fuera del alcance aquí. Ver Limitaciones conocidas.

Requisitos

• Node.js 20+

• pnpm

• Una clave API de Zapper

Instalación

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

Configuración

Copia .env.example a .env y añade tu clave:

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

El servidor falla rápidamente al arrancar si falta ZAPPER_API_KEY: verás el error inmediatamente, no en la primera llamada a la herramienta.

Ejecución

Prueba de humo independiente (confirma que todo funciona sin Claude Desktop):

ZAPPER_API_KEY=your_key pnpm client

Salida: enumera herramientas/recursos/prompts, luego llama a cada herramienta contra vitalik.eth.

Inicio directo del servidor:

ZAPPER_API_KEY=your_key pnpm start

Conexión con Claude Desktop

Añade a ~/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"
      }
    }
  }
}

Reinicia Claude Desktop. Las tres herramientas, el recurso zapper://supported-networks y el prompt analyze-wallet estarán disponibles.

Registros (si el servidor no logra cargar):

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

Integración con Mastra (Día 10)

Para conectar este servidor a un agente de Mastra a través del cliente MCP de Mastra:

1. Inicia el servidor: node /path/to/build/server.js

2. Configura el cliente MCP de Mastra con transporte stdio, nombre del servidor zapper-mcp

3. El agente consume datos de Zapper exclusivamente a través de MCP: lib/zapper.ts en el repositorio del agente queda sin uso

No todas las herramientas necesitan estar expuestas al agente de Mastra; esa es una decisión de diseño del Día 10.

Referencia de herramientas

get_portfolio(address, networks?)

Desglose completo del portafolio: USD total, todas las tenencias de tokens, todas las posiciones DeFi.

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

get_token_balances(address, networks?)

Solo saldos de tokens al contado (sin posiciones DeFi).

get_app_positions(address, networks?, app_slug?)

Solo posiciones de aplicaciones DeFi (Aave, Uniswap, Sablier, etc.).

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

Recurso: zapper://supported-networks

Matriz JSON de { name, chainId } para todas las redes indexadas. Leído por el host al momento de ensamblar el contexto.

Prompt: analyze-wallet

Pre-configura una conversación de análisis de portafolio. Toma un argumento address.

Manejo de errores

Cada herramienta devuelve isError: true con un mensaje procesable por el modelo en caso de:

• HTTP 401 / clave API inválida

• HTTP 429 / límite de tasa excedido

• HTTP 5xx / error del servidor de Zapper

• Tiempo de espera de red (15s)

• Respuesta mal formada

Una billetera vacía (totalUSD: 0, tokens: []) devuelve isError: false: estar vacío no es un error.

Limitaciones conocidas

• Modelo de confianza de una sola clave: el servidor mantiene una ZAPPER_API_KEY y sirve a un propietario. Un despliegue multi-inquilino necesita OAuth por usuario o autenticación en la capa de transporte (HTTP transmitible con tokens Bearer).

• Sin caché: cada llamada a la herramienta golpea la API de Zapper. Un servidor de producción añadiría una caché de TTL corto (las posiciones cambian lentamente) y respetaría los límites de tasa de forma proactiva.

• Sin resources/subscribe: zapper://supported-networks es una lista estática. Las actualizaciones en vivo requerirían que el servidor anuncie la capacidad de suscripción y emita notifications/resources/updated.

• Solo transporte stdio: el transporte HTTP transmitible se pospuso para una iteración futura.

• Límite de paginación: las herramientas devuelven hasta 50 tokens y 20 posiciones de aplicaciones por solicitud.

¿Qué sigue?

Día 10: conectar este servidor al agente de billetera de Mastra en ../day1-wallet-agent/ a través del cliente MCP de Mastra. El agente consumirá datos de Zapper exclusivamente a través de MCP, validando que la superficie de herramientas realmente desacople la capacidad del marco de trabajo del agente.