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 전송 및 서버 이름 zapper-mcp로 Mastra 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를 반환합니다. 비어 있는 것은 오류가 아닙니다.

알려진 제한 사항

• 단일 키 신뢰 모델: 서버는 하나의 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 데이터를 소비하게 되며, 도구 인터페이스가 에이전트 프레임워크로부터 기능을 실제로 분리하는지 검증합니다.