zapper-mcp

MCP-сервер, который предоставляет API портфелей DeFi Zapper в качестве продуманного набора инструментов для клиентов LLM. Подключите его к Claude Desktop или любому другому хосту, совместимому с MCP, и задавайте вопросы на естественном языке о любом кошельке — «сколько стоит этот кошелек?», «есть ли у него позиции в Aave?», «покажи мне основные активы в сети Base».

Создан на 9-й день 21-дневного спринта по AI-инжинирингу. На 10-й день этот сервер будет интегрирован в агент Mastra.

Набор инструментов

Обоснование дизайна для каждого примитива находится в DESIGN.md. Краткая версия:

Почему не один большой инструмент get_everything? Объединение инструментов заставило бы модель получать и парсить большой ответ со смешанной схемой для каждого вопроса, даже для узкоспециализированных. Граница инструмента — это декларация области видимости: правильный инструмент возвращает именно то, что нужно для этапа рассуждения.

Почему API-ключ находится в конфигурации сервера, а не в аргументах инструмента? Учетные данные должны находиться на уровне хоста (переменные окружения, внедряемые при запуске процесса), а не в протоколе MCP. Если бы api_key был параметром инструмента, он проходил бы через рассуждения LLM и появлялся бы в истории диалога. Для многопользовательского развертывания правильным механизмом является аутентификация на транспортном уровне (Bearer-токен через Streamable HTTP) или OAuth для каждого пользователя — и то, и другое выходит за рамки данного проекта. См. Известные ограничения.

Требования

• Node.js 20+

• pnpm

• API-ключ Zapper

Установка

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

Конфигурация

Скопируйте .env.example в .env и добавьте свой ключ:

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

Сервер завершает работу при загрузке, если отсутствует ZAPPER_API_KEY — вы увидите ошибку сразу, а не при первом вызове инструмента.

Запуск

Автономный дымовой тест (подтверждает, что все работает без Claude Desktop):

ZAPPER_API_KEY=your_key pnpm client

Вывод: список инструментов/ресурсов/промптов, затем вызов каждого инструмента для vitalik.eth.

Прямой запуск сервера:

ZAPPER_API_KEY=your_key pnpm start

Настройка Claude Desktop

Добавьте в ~/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"
      }
    }
  }
}

Перезапустите Claude Desktop. Три инструмента, ресурс zapper://supported-networks и промпт analyze-wallet станут доступны.

Логи (если сервер не загружается):

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

Интеграция с Mastra (День 10)

Чтобы подключить этот сервер к агенту Mastra через MCP-клиент Mastra:

1. Запустите сервер: node /path/to/build/server.js

2. Настройте MCP-клиент Mastra с транспортом stdio, имя сервера zapper-mcp

3. Агент получает данные Zapper исключительно через MCP — lib/zapper.ts в репозитории агента становится неиспользуемым

Не все инструменты должны быть доступны агенту Mastra; это решение принимается на 10-й день проектирования.

Справочник инструментов

get_portfolio(address, networks?)

Полная разбивка портфеля: общая сумма в USD, все активы в токенах, все позиции DeFi.

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

get_token_balances(address, networks?)

Только балансы спотовых токенов (без позиций DeFi).

get_app_positions(address, networks?, app_slug?)

Только позиции в приложениях DeFi (Aave, Uniswap, Sablier и т.д.).

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

Ресурс: zapper://supported-networks

JSON-массив { name, chainId } для всех проиндексированных сетей. Считывается хостом во время сборки контекста.

Промпт: analyze-wallet

Подготавливает почву для диалога по анализу портфеля. Принимает аргумент address.

Обработка ошибок

Каждый инструмент возвращает isError: true с сообщением, понятным для модели, в следующих случаях:

• HTTP 401 / неверный API-ключ

• HTTP 429 / превышение лимита запросов

• HTTP 5xx / ошибка сервера Zapper

• Тайм-аут сети (15 с)

• Некорректный ответ

Пустой кошелек (totalUSD: 0, tokens: []) возвращает isError: false — пустота не является ошибкой.

Известные ограничения

• Модель доверия с одним ключом: сервер хранит один ZAPPER_API_KEY и обслуживает одного владельца. Для многопользовательского развертывания требуется OAuth для каждого пользователя или аутентификация на транспортном уровне (Streamable HTTP с Bearer-токенами).

• Отсутствие кэширования: каждый вызов инструмента обращается к API Zapper. Промышленный сервер добавил бы кэш с коротким TTL (позиции меняются медленно) и проактивно соблюдал бы лимиты запросов.

• Нет resources/subscribe: zapper://supported-networks — это статический список. Для обновлений в реальном времени сервер должен был бы объявлять о возможности подписки и отправлять notifications/resources/updated.

• Только транспорт stdio: транспорт Streamable HTTP отложен до будущих итераций.

• Ограничение пагинации: инструменты возвращают до 50 токенов и 20 позиций приложений за запрос.

Что дальше

День 10: подключение этого сервера к агенту кошелька Mastra в ../day1-wallet-agent/ через MCP-клиент Mastra. Агент будет потреблять данные Zapper исключительно через MCP, подтверждая, что набор инструментов действительно отделяет функциональность от фреймворка агента.