MCP Evm

@missionsquad/mcp-evm

用于以太坊虚拟机（EVM）RPC API的MCP服务器，由 evmdecoder.

此服务器为LLM客户端公开精心策划的EVM读取/解码工具，同时保持RPC端点对工具模式隐藏。

特性

• FastMCP stdio服务器(mcp-evm)
• 通过隐藏每个请求的RPC URL支持 context.extraArgs.rpcUrl
• 通过回退RPC URL EVM_RPC_URL
• 每个RPC解码器实例池与LRU驱逐
• 精心设计的工具表面（15个工具），以避免过大的有效载荷
• 在返回结果之前，将时间戳标准化为人类可读的UTC文本
• 具有严格TypeScript的类型安全模式
• CI构建/测试和npm发布GitHub操作

刀具表面

服务器当前公开了这些工具：

• evm_decode_function_call
• evm_decode_function_call_v2
• evm_contract_info
• evm_get_block
• evm_get_slim_block
• evm_get_slim_block_by_hash
• evm_get_full_block
• evm_get_pending_transactions
• evm_get_pending_transaction
• evm_get_transaction
• evm_get_transaction_receipt
• evm_get_internal_transaction
• evm_get_internal_transactions_by_block
• evm_get_fee_history
• evm_get_latest_block_number

笔记：

• initialize 不作为工具暴露；解码器初始化是内部的。
• 有意不暴露大批量/批量工具和原材料加工工具。
• evm_get_pending_transactions 默认为 decode: false 以减小响应大小。

样品数据

工具子集的示例有效载荷可在 sample-data/.\ 目前并非所有工具都有样本数据。

可用样本：

• evm_contract_info: sample-data/evm_contract_info.json
• evm_decode_function_call: sample-data/evm_decode_function_call.json
• evm_decode_function_call_v2: sample-data/evm_decode_function_call_v2.json
• evm_get_block:

- 解码： sample-data/evm_get_block(decode).json - 原始： sample-data/evm_get_block(raw).json

• evm_get_slim_block: sample-data/evm_get_slim_block.json
• evm_get_transaction: sample-data/evm_get_transaction.json
• evm_get_transaction_receipt: sample-data/evm_get_transaction_receipt.json
• evm_get_internal_transaction: sample-data/evm_get_internal_transaction.json
• evm_get_fee_history: sample-data/get_fee_history.json

需求

• Node.js >=20
• Yarn（项目脚本使用Yarn）

安装

本地开发

yarn install --frozen-lockfile
yarn build
yarn start

作为CLI（安装/发布后）

mcp-evm

服务器通过stdio传输运行。

RPC URL解析

每个工具调用按以下顺序解析RPC URL：

1. 隐藏的额外参数： rpcUrl （首选）
2. 环境回退： EVM_RPC_URL

如果两者都不存在，该工具将抛出面向用户的错误。

重要提示： rpcUrl 故意不属于公共工具模式。

配置

复制 .env.example 到 .env 并根据需要设置值。

环境变量

ABI目录行为

• 如果 EVM_ABI_DIRECTORY 它用于ABI发现。
• 如果配置的/default ABI目录不存在，服务器会完全回退，并继续使用内置的匿名签名支持 evmdecoder.
• abis.zip 已提交并发布，并自动提取到 ./abis 在软件包安装过程中，通过 postinstall.
• 也可手动提取：

yarn extract:abis

工具参考

evm_decode_function_call

解码EVM功能输入。

参数：

• input: string
• address?: string

样品：

• sample-data/evm_decode_function_call.json

evm_decode_function_call_v2

解码功能输入并包含合同信息。

参数：

• input: string
• address?: string

样品：

• sample-data/evm_decode_function_call_v2.json

evm_contract_info

对合同地址进行分类/检查。

参数：

• address: string

样品：

• sample-data/evm_contract_info.json

evm_get_block

默认情况下，使用解码的交易获取块。

参数：

• blockNumber: number
• decode?: boolean （默认值 true)

样品：

• 解码： sample-data/evm_get_block(decode).json
• 原始： sample-data/evm_get_block(raw).json

evm_get_slim_block

获得苗条的身材。

参数：

• blockNumber: number
• raw?: boolean （默认值 true)

样品：

• sample-data/evm_get_slim_block.json

evm_get_slim_block_by_hash

按哈希值获取瘦块。

参数：

• hash: string
• raw?: boolean （默认值 true)

evm_get_full_block

获得完整的收据块。

参数：

• blockNumber: number
• decode?: boolean （默认值 true)

evm_get_pending_transactions

获取待处理交易；默认情况下，decode处于关闭状态。

参数：

• decode?: boolean （默认值 false)

evm_get_pending_transaction

通过哈希值获取一笔待处理交易。

参数：

• hash: string
• decode?: boolean （默认值 true)

evm_get_transaction

按哈希值获取交易。

参数：

• hash: string
• decode?: boolean （默认值 true)

样品：

• sample-data/evm_get_transaction.json

evm_get_transaction_receipt

获取交易收据。

参数：

• hash: string
• decode?: boolean （默认值 true)

样品：

• sample-data/evm_get_transaction_receipt.json

evm_get_internal_transaction

获取一笔交易的内部跟踪。

参数：

• hash: string
• decode?: boolean （默认值 true)

样品：

• sample-data/evm_get_internal_transaction.json

evm_get_internal_transactions_by_block

按块号获取内部痕迹。

参数：

• blockNumber: number
• decode?: boolean （默认值 true)

evm_get_fee_history

获取费用历史记录。

参数：

• blockCount: number
• blockTarget: number

样品：

• sample-data/get_fee_history.json

evm_get_latest_block_number

获取最新的区块编号。

参数：

• 无

时间戳规范化

在返回工具结果之前，任何名为 timestamp 递归地归一化为人类可读的UTC文本：

• 支持数字纪元秒数
• 支持数字纪元毫秒
• 支持数字字符串和十六进制字符串（例如 0x...)
• 输出格式： YYYY-MM-DD HH:mm:ss.sss UTC

所有非-timestamp 字段将原封不动地返回。

响应格式

工具处理程序返回确定性JSON文本（字符串化有效载荷）。在MCP响应中，这显示为文本内容，应由需要结构化访问的客户端解析。

响应规范化还应用了两个令牌优化/丰富规则：

• 如果格式化交易包含解码 call，生 input 字段已删除。
• 如果解码的事务/日志丢失 call/event，服务器在返回之前尝试丰富它们。

使用示例

JSON-RPC tools/call 带有隐藏的RPC URL

{
  "method": "tools/call",
  "params": {
    "name": "evm_get_block",
    "arguments": {
      "blockNumber": 19000000,
      "decode": true,
      "rpcUrl": "https://mainnet.infura.io/v3/"
    }
  }
}

JSON-RPC tools/call 使用 EVM_RPC_URL 后备方案

{
  "method": "tools/call",
  "params": {
    "name": "evm_get_latest_block_number",
    "arguments": {}
  }
}

FastMCP风格的客户端调用

await client.callTool('evm_get_transaction', {
  hash: '0x...',
  decode: true,
  rpcUrl: 'https://mainnet.infura.io/v3/',
})

发展

脚本

• yarn build -清理+编译TypeScript+使CLI可执行
• yarn start -运行内置服务器
• yarn dev -观看编译和运行
• yarn inspect -使用FastMCP检查器检查MCP服务器
• yarn test -运行单元测试
• yarn test:watch -在监视模式下运行测试
• yarn test:coverage -使用V8覆盖率报告运行测试
• yarn format -检查Prettier格式
• yarn format:write -应用格式

覆盖

yarn test:coverage

Vitest在 coverage/.

CI/CD

工作流位于 .github/workflows/:

• build.yaml：构建+测试拉取请求
• publish.yaml：构建+测试+发布到npm main 推送（忽略仅标记的更改）

发布作业需要存储库机密：

• NPM_TOKEN （用作 NODE_AUTH_TOKEN)

npm发布

包已配置为作用域公共发布：

• 姓名： @missionsquad/mcp-evm
• publishConfig.access: public
• prepublishOnly：在发布之前运行测试和生成

手动发布（如果需要）：

npm publish --access public

故障排除

RPC URL is required...

提供隐藏 rpcUrl 在工具参数或集合中 EVM_RPC_URL.

找不到ABI目录

如果您想进行本地ABI匹配，请设置 EVM_ABI_DIRECTORY 转到现有文件夹或运行 yarn extract:abis.

大量回应

使用苗条/单项工具，并有意保留解码标志。 evm_get_pending_transactions 默认为 decode: false 出于这个原因。

关于任务小队

任务小队 提供了一个平台，用于构建和运行具有生产就绪工具的AI代理，包括像这样的MCP服务器集成。\ 您可以快速配置MCP服务器、连接外部系统和创建专用代理，而无需每次重建核心基础设施。

许可证

麻省理工学院