etherscan-v2-mcp-server

## Etherscan V2 MCP Server 概述 Etherscan V2 MCP Server 将一组精选的 Etherscan V2 端点作为 Model Context Protocol (MCP) 工具公开。它可以作为可流式传输的 HTTP MCP 端点或作为 stdio MCP 服务器运行。整个项目中使用原生 ESM。 主要文件： * __Server__: `src/index.ts` * __Tools__: `src/tools.ts` * __Schemas__: `src/schemas.ts` * __MCP Resources__: `src/resources.ts` 要求 * __Node.js__: 20+ (推荐 22+) * __Package manager__: npm, yarn, or pnpm 安装 ```bash npm i ``` 环境 将 `.env.example` 复制到 `.env` 并设置值： * __ETHERSCAN_API_KEY__: 你的 Etherscan（或支持的浏览器）API 密钥。 * __ETHERSCAN_PRO__: 可选，如果可用，启用 pro 功能。 * __OPENAI_API_KEY__: 可选，为 `ethv2_nl_query` 启用简单的 NL 路由。 * __REDIS_HOST__, __REDIS_PORT__, __REDIS_PASSWORD__: 可选；如果设置，服务器使用 Redis 支持的缓存；否则使用内存缓存。 * __PORT__: 默认 5009。 * __HOST__: 默认 0.0.0.0。 脚本 * __build__: `tsc` * __dev__: `tsx src/index.ts` * __start__: `node dist/index.js` * __test__: `jest --passWithNoTests` 运行 (HTTP MCP 和 REST 信息) ```bash # Development (tsx) npm run dev # Production build npm run build && npm start # Stdio mode for MCP-aware clients node dist/index.js --stdio ``` HTTP 端点 (non-MCP) * __GET `/health`__: 基本的活动有效负载。 * __GET `/api/tools`__: 返回带有输入 JSON Schemas 的工具目录。 * __`/mcp`__: 用于 MCP 的可流式传输 HTTP 传输。首先使用 POST 初始化会话；在同一会话的后续请求中保留 `mcp-session-id` 标头。 MCP 资源 这些可以通过 MCP 请求发现（不是普通的 REST）： * __`etherscanv2://guide`__: 关于选择工具和分页策略的 Markdown 指南。 * __`etherscanv2://api-map`__: 类别 ➜ 工具名称的 JSON 映射。 缓存 响应按工具缓存，TTL 较小（例如，通常为 5–300 秒，静态元数据的时间更长）。如果设置了 `REDIS_HOST`，则使用 Redis；否则，使用内存后备缓存。有关每个工具应用的 TTL，请参见 `src/tools.ts`。 约定 * 始终包括 __`chainid`__ (EVM 链 ID，例如，1/Ethereum, 10/Optimism, 42161/Arbitrum, 8453/Base)。 * 对列表端点使用 __pagination__: `page` 和 `offset`。不要在单个调用中聚合多个页面。 * 对于日志，请使用地址/主题过滤器和 `fromBlock`/`toBlock` 窗口。 工具目录 以下是工具名称、用途和简洁的输入模式（有关权威定义，请参见 `src/schemas.ts`）。 账户 * __ethv2_account_balance__ – 获取标签上的帐户余额。 - Input: `{ chainid: number, address: string, tag?: 'latest'|'earliest'|'pending' }` * __ethv2_account_txlist__ – 地址的普通 txs（分页）。 - Input: `{ chainid, address, startblock?, endblock?, sort?: 'asc'|'desc', page?, offset? }` * __ethv2_account_txlistinternal__ – 地址的内部 txs（分页）。 - Input: 与 `ethv2_account_txlist` 相同 * __ethv2_account_tokentx__ – 地址的 ERC-20 转移（分页；可选的合约过滤器）。 - Input: `{ chainid, address, contractaddress?, sort?, page?, offset? }` 区块 & 交易 * __ethv2_block_by_time__ – 最接近时间戳的区块号。 - Input: `{ chainid, timestamp: number, closest?: 'before'|'after' }` * __ethv2_tx_receipt_status__ – tx 哈希的收据状态。 - Input: `{ chainid, txhash: string }` * __ethv2_tx_status__ – tx 哈希的交易状态。 - Input: `{ chainid, txhash: string }` 合约 * __ethv2_contract_getabi__ – 经过验证的合约 ABI。 - Input: `{ chainid, address }` * __ethv2_contract_getsourcecode__ – 经过验证的合约源代码。 - Input: `{ chainid, address }` 日志 * __ethv2_logs_getLogs__ – 按地址/主题的日志（分页；窗口化）。 - Input: `{ chainid, address?, fromBlock?, toBlock?, topic0?, topic1?, topic2?, topic3?, page?, offset? }` 代币 * __ethv2_token_supply__ – 按合约的代币供应量。 - Input: `{ chainid, contractaddress }` * __ethv2_token_balance__ – 地址的代币余额。 - Input: `{ chainid, contractaddress, address, tag?: 'latest'|'earliest'|'pending' }` * __ethv2_token_holderlist__ – 代币的持有者列表（分页）。 - Input: `{ chainid, contractaddress, page?, offset? }` * __ethv2_account_tokennfttx__ – 地址的 ERC‑721 转移（分页；可选的合约过滤器）。 - Input: `{ chainid, address, contractaddress?, sort?, page?, offset? }` * __ethv2_account_token1155tx__ – 地址的 ERC‑1155 转移（分页；可选的合约过滤器）。 - Input: `{ chainid, address, contractaddress?, sort?, page?, offset? }` Gas & 统计 * __ethv2_gas_oracle__ – 每个链的 Gas oracle（基本/快速/安全）。 - Input: `{ chainid }` * __ethv2_stats_ethprice__ – 每个链的 ETH 价格。 - Input: `{ chainid }` * __ethv2_stats_ethsupply__ – 每个链的 ETH 供应量。 - Input: `{ chainid }` 代理 (JSON‑RPC) * __ethv2_proxy_blockNumber__ – `eth_blockNumber`。 - Input: `{ chainid }` * __ethv2_proxy_getBlockByNumber__ – `eth_getBlockByNumber`。 - Input: `{ chainid, tag: string /* hex or 'latest' */, boolean?: boolean /* include tx objects */ }` * __ethv2_proxy_getTransactionByHash__ – `eth_getTransactionByHash`。 - Input: `{ chainid, txhash }` 名称标签 * __ethv2_nametag_by_address__ – 地址名称标签（如果支持）。 - Input: `{ chainid, address }` 自然语言（可选） * __ethv2_nl_query__ – 用于常见意图的轻量级 NL 路由器。 - Input: `{ chainid: number, query: string }` - Notes: 查找简单的意图，如 gas、tx 状态、余额、日志；否则返回指导。 例子 列出工具 (REST): ```bash curl http://localhost:5009/api/tools | jq ``` 通过 MCP 获取 gas oracle（带有 `node --stdio` 的 stdio 示例需要 MCP 客户端）。对于普通的 HTTP 健全性检查，您可以从一次性脚本中快速调用底层客户端，或使用定制的 MCP 客户端。 ESM 注意 此项目是原生 ESM (`"type": "module"`)。本地导入在源中包含显式的 `.js` 扩展名，以便在 `dist/` 中的编译输出在 Node ESM 下运行而不会出现解析错误。 许可 MIT