chainlens

chainlens

chainlens 通过 Blockscout 查看 EVM 区块链：地址持有什么、做过什么，区块或交易中包含什么，钱包中有哪些代币和 NFT，以及已验证合约的 ABI 和源代码说明了什么。内置支持六条链——Ethereum、Optimism、Gnosis、Polygon、Base 和 Arbitrum One——所有回答均来自对应链的公开 Blockscout API v2 实例。

此软件包是对原始 Blockscout MCP 服务 README 中记录的 16 个工具进行的干净室重建。已涵盖所有记录的工具；下文说明了线上的映射方式，包括重建的部分。

与服务的通信方式

无需 API 密钥——公开的 Blockscout 实例不需要密钥：

# Optional: send a key as an x-api-key header
export BLOCKSCOUT_API_KEY="your key"
# Optional: override the per-chain base URL for any chain
export BLOCKSCOUT_API_URL="https://eth.blockscout.com/api/v2"

根据 chain_id 从内置映射中选择基础 URL： 1 对应 Ethereum，10 对应 Optimism，100 对应 Gnosis，137 对应 Polygon，8453 对应 Base，42161 对应 Arbitrum One。未知的 chain_id 会报错并列出已知链（除非设置了 BLOCKSCOUT_API_URL，此时无论链为何，都会优先使用该覆盖值）。

线上格式说明。 原始服务通过其 PRO 网关路由大多数数据工具；此重建版本将它们映射到公开的 Blockscout API v2（/addresses/...、/blocks/...、/transactions/...、/smart-contracts/...、/search）。部分参数转换属于记录在案的重建内容，首次实时冒烟测试如下：

• ENS 解析使用主网 /search?q=<name>，并选取第一个包含地址的结果。
• read_contract 会向 /smart-contracts/{address}/methods/read 发送 POST 请求，内容为 {function_name, args, abi}——这是依据最不充分的映射。
• cursor 参数会作为 cursor 查询参数转发；Blockscout v2 分页通常使用 next_page_params，因此对 cursor 的支持存在偏移风险。
• age_from / age_to（以及 methods / token）筛选条件在客户端对获取的第一页数据应用，不会转发到上游。

两个工具不会访问网络：__unlock_blockchain_analysis__ 会返回本地指南和链列表；get_chains_list 会在本地按名称、链 ID 或货币子串筛选该列表。

安装

npx @reneturcios/chainlens get_block_number '{"chain_id":"1"}'

也可以运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/chainlens

容器默认启动 MCP 服务。传入 CLI 参数即可将其用作 CLI。

CLI

CLI 与工具一一对应：每个工具都有一个子命令，参数以单个 JSON 对象的形式传入。

chainlens get_chains_list '{"query":"base"}'
chainlens get_address_info '{"chain_id":"1","address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'
chainlens get_transactions_by_address '{"chain_id":"1","address":"0x...","age_from":"2026-10-01T00:00:00Z","age_to":"2026-10-26T23:59:59Z"}'
chainlens get_block_info '{"chain_id":"8453","number_or_hash":"latest"}'
chainlens --version

退出码：成功时为 0；API 或验证错误时为 1（错误信息会指出问题）；用法错误时为 2。

MCP 服务

一个可执行文件支持两种用法。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/chainlens mcp

MCP 客户端配置：

{
  "mcpServers": {
    "chainlens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/chainlens", "mcp"]
    }
  }
}

工具

工具	输入	功能说明
__unlock_blockchain_analysis__	—	本地：返回状态、指南和支持的链列表。
get_chains_list	query	本地：按名称、ID 或货币子字符串筛选 6 条链的列表。
get_address_by_ens_name	name（必填）	通过主网搜索解析 ENS 名称；返回第一个包含地址的结果。
lookup_token_by_symbol	chain_id、symbol（必填）	搜索链；返回代币类型的条目（回退：所有条目）。
get_contract_abi	chain_id、address（必填）	已验证合约的 ABI。
inspect_contract_code	chain_id、address（必填）、file_name	已验证合约的源代码和创建状态。
get_address_info	chain_id、address（必填）	地址余额、类型和元数据。
get_tokens_by_address	chain_id、address（必填）、cursor	地址持有的代币余额。
get_block_number	chain_id（必填）、datetime	最新区块编号和时间戳；回显请求的日期时间。
get_transactions_by_address	chain_id、address、age_from、age_to（必填）、methods、cursor	地址交易；在客户端对第一页应用时长和方法筛选。
get_token_transfers_by_address	chain_id、address、age_from、age_to（必填）、token、cursor	ERC-20 转账；在客户端对第一页应用时长和代币筛选。
nft_tokens_by_address	chain_id、address（必填）、cursor	地址持有的 NFT 代币（ERC-721、ERC-1155）。
get_block_info	chain_id、number_or_hash（必填）、include_transactions	按编号或哈希查询区块详情。
get_transaction_info	chain_id、hash（必填）、include_raw_input	按哈希查询交易详情。
read_contract	chain_id、address、abi、function_name（必填）、args（JSON 字符串，默认值为 []）、block	读取合约函数（重建的线缆映射，见备注）。
direct_api_call	chain_id、endpoint_path（必填）、query_params、method、json_body、cursor	直接调用任意 Blockscout API v2 端点路径。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。