basezap-mcp

BaseZap의 팁 지급 에이전트 도구를 모든 MCP 클라이언트(Claude Desktop, Cursor, Claude Code 등)에 노출하는 MCP(Model Context Protocol) 서버입니다.

이 서버는 설계상 읽기 전용/비수탁형입니다. 절대 개인 키를 보유하지 않으며, 서명하지 않고, 트랜잭션을 브로드캐스트하지 않습니다. 플랫폼 정보를 가져오고, 수수료 견적을 계산하며, 별도의 지갑 연결 클라이언트가 서명하고 전송할 서명되지 않은 ERC-20 전송 calldata를 구축하기만 합니다.

도구

• get_platform_info — 체인, USDC 주소, 플랫폼 수수료(bps), 수수료 지갑.

• get_tip_quote — USDC 금액을 입력하면 정확한 제작자/플랫폼 수수료 분할을 반환합니다.

• build_tip_calldata — 수신자 주소와 금액을 입력하면 팁의 두 구간에 대한 서명되지 않은 calldata를 반환합니다. 절대 서명하거나 전송하지 않습니다.

• resolve_farcaster_username — Farcaster 사용자 이름을 확인하여 확인된 지갑 주소로 변환합니다(BaseZap의 /api/resolve-user 엔드포인트를 직접 사용).

Related MCP server: x402-bazaar-mcp

설치

npm install --ignore-scripts
npm run build

(--ignore-scripts는 일부 환경(예: Termux/Android)에서 네이티브 모듈 빌드 문제를 방지합니다 — 어디서든 사용해도 무해합니다.)

독립 실행(테스트용)

npm start

또는 MCP 클라이언트 없이 stdio를 통해 단일 도구 호출을 직접 테스트할 수 있습니다:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_tip_quote","arguments":{"amountUsdc":1}}}' | node build/index.js

Claude Desktop 설정

이 내용을 claude_desktop_config.json에 추가하세요(설정 → 개발자 → 구성 편집):

{
  "mcpServers": {
    "basezap": {
      "command": "node",
      "args": ["/absolute/path/to/basezap-mcp/build/index.js"],
      "env": {
        "BASEZAP_USE_X402": "false"
      }
    }
  }
}

경로를 컴퓨터의 실제 절대 경로(build/index.js)로 바꾸세요. 구성을 편집한 후 Claude Desktop을 다시 시작하십시오.

무료 vs 유료(x402) 모드

기본값(BASEZAP_USE_X402=false 또는 설정되지 않음)에서는 서버가 BaseZap의 무료 엔드포인트(/api/agent)를 호출합니다. BASEZAP_USE_X402=true로 설정하면 대신 유료 x402 엔드포인트를 통해 호출이 라우팅됩니다(호출당 $0.001 USDC).

중요: BASEZAP_USE_X402=true만 설정하면 서버가 자동으로 지불하지 않습니다 — 별도로 자동 지불을 설정하지 않았거나(아래 참조) 이미 x402 지불을 처리하는 MCP 클라이언트/게이트웨이를 사용하지 않는 한 모든 호출에서 명확한 HTTP 402 Payment Required 오류가 발생합니다.

선택 사항: x402 자동 지불

자금이 있는 지갑을 사용하여 이 서버가 자체 x402 수수료를 자동으로 지불하도록 하는 처음부터 시작하는 가이드는 AUTOPAY.md를 참조하세요. 사용하기 전에 신중히 읽으세요 — 실제 개인 키를 환경 변수에 넣는 작업이 포함되며, 잘못 구성된 자동 지불 서버는 모든 도구 호출에서 조용히 실제 돈을 소비할 수 있습니다. 기본적으로 연결되어 있지 않으며, 활성화하기 전에 정확히 무엇을 하는지 이해해야 합니다.

검증된 요청 계약

이 서버가 의존하는 정확한 요청/응답 형태는 실제 /api/agent 엔드포인트에 대해 실시간으로 확인되었습니다(문서에서 추정한 것이 아님):

{ "tool": "get_tip_quote", "args": { "amount_usdc": 1 } }

반환:

{ "total_usdc": 1, "creator_receives_usdc": 0.95, "platform_fee_usdc": 0.05, "platform_fee_bps": 500 }

API 자체는 args 내부에서 snake_case 필드 이름을 사용합니다 — 이 서버의 MCP 도구 입력은 사용자 친화적인 camelCase(amountUsdc)를 사용하고 내부적으로 변환하므로, 서버 자체를 수정하는 경우에만 관련됩니다.