zapper-mcp

Zapper DeFiポートフォリオAPIを、LLMクライアント向けに考え抜かれたツールインターフェースとして公開するMCPサーバーです。Claude DesktopやMCP互換ホストに接続し、あらゆるウォレットについて自然言語で質問できます。「このウォレットの価値は？」「Aaveのポジションはある？」「Base上の主要な保有銘柄を見せて」など。

21日間のAIエンジニアリングスプリントの9日目に構築。10日目には、このサーバーをMastraエージェントに組み込みます。

ツールインターフェース

各プリミティブの設計根拠は DESIGN.md にあります。要約は以下の通りです。

なぜ「すべてを取得する」大きなツールを1つにしないのか？ ツールを統合すると、モデルは質問のたびに（焦点を絞った質問であっても）混合スキーマの大きなレスポンスを受け取り、解析することを強制されます。ツールの境界はスコープの宣言です。適切なツールは、推論ステップが必要とするものを正確に返します。

なぜ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を再起動します。3つのツール、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. Mastra MCPクライアントをstdioトランスポート、サーバー名 zapper-mcp で設定

3. エージェントはMCPを通じてのみZapperデータを消費します。エージェントリポジトリ内の 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

インデックス化された全ネットワークの { name, chainId } のJSON配列。コンテキスト構築時にホストによって読み取られます。

プロンプト：analyze-wallet

ポートフォリオ分析の会話を事前準備します。address 引数を取ります。

エラーハンドリング

各ツールは、以下の場合にモデルが対処可能なメッセージと共に isError: true を返します：

• HTTP 401 / 無効なAPIキー

• HTTP 429 / レート制限超過

• HTTP 5xx / Zapperサーバーエラー

• ネットワークタイムアウト（15秒）

• 不正なレスポンス

空のウォレット（totalUSD: 0, tokens: []）は isError: false を返します。空であることはエラーではありません。

既知の制限

• シングルキー信頼モデル：サーバーは1つの ZAPPER_API_KEY を保持し、1人の所有者にサービスを提供します。マルチテナント展開には、ユーザーごとの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データを消費し、ツールインターフェースがエージェントフレームワークから機能を実際に分離できることを検証します。