zapper-mcp

一个将 Zapper DeFi 投资组合 API 作为精心设计的工具界面公开给 LLM 客户端的 MCP 服务器。将其连接到 Claude Desktop 或任何兼容 MCP 的主机，即可针对任何钱包提出自然语言问题——“这个钱包价值多少？”、“它有任何 Aave 头寸吗？”、“向我展示 Base 链上的顶级持仓。”

构建于 21 天 AI 工程冲刺的第 9 天。第 10 天将此服务器接入 Mastra 代理。

工具界面

每个原语的设计原理都在 DESIGN.md 中。简而言之：

为什么不使用一个大的 get_everything 工具？ 合并工具会迫使模型在每次提问时接收并解析一个大型的混合模式响应，即使是针对性的问题。工具边界是范围的声明——正确的工具返回推理步骤所需的精确内容。

为什么 API 密钥在服务器配置中，而不是作为工具参数？ 凭据属于主机层（在进程启动时注入的环境变量），而不是 MCP 协议。如果 api_key 是工具参数，它将流经 LLM 的推理过程并出现在对话历史中。对于多租户部署，正确的机制是传输层身份验证（通过 Streamable HTTP 的 Bearer 令牌）或每用户 OAuth——两者均超出此处范围。参见 已知限制。

要求

• Node.js 20+

• pnpm

• Zapper API 密钥

安装

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. 使用 stdio 传输配置 Mastra MCP 客户端，服务器名称为 zapper-mcp

3. 代理仅通过 MCP 使用 Zapper 数据——代理仓库中的 lib/zapper.ts 将不再使用

并非所有工具都需要向 Mastra 代理公开；这是第 10 天的设计决策。

工具参考

get_portfolio(address, networks?)

完整的投资组合分解：总美元价值、所有代币持仓、所有 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

所有已索引网络的 { name, chainId } JSON 数组。由主机在上下文组装时读取。

提示词：analyze-wallet

预先启动投资组合分析对话。接受一个 address 参数。

错误处理

每个工具在以下情况下返回 isError: true 以及模型可操作的消息：

• HTTP 401 / API 密钥无效

• HTTP 429 / 速率限制

• HTTP 5xx / Zapper 服务器错误

• 网络超时 (15s)

• 格式错误的响应

空钱包（totalUSD: 0, tokens: []）返回 isError: false——空并不代表错误。

已知限制

• 单密钥信任模型：服务器持有一个 ZAPPER_API_KEY 并服务于一个所有者。多租户部署需要每用户 OAuth 或传输层身份验证（带有 Bearer 令牌的 Streamable HTTP）。

• 无缓存：每次工具调用都会访问 Zapper API。生产服务器应添加短 TTL 缓存（头寸变化缓慢）并主动遵守速率限制。

• 无 resources/subscribe：zapper://supported-networks 是一个静态列表。实时更新需要服务器通告订阅能力并发出 notifications/resources/updated。

• 仅 stdio 传输：Streamable HTTP 传输推迟到未来迭代。

• 分页上限：工具每次请求最多返回 50 个代币和 20 个应用头寸。

下一步计划

第 10 天：通过 Mastra 的 MCP 客户端将此服务器接入 ../day1-wallet-agent/ 的 Mastra 钱包代理。代理将仅通过 MCP 使用 Zapper 数据，验证工具界面是否确实将能力与代理框架解耦。