neo-mcp

[](https://mseep.ai/app/r3e-network-neo-mcp) # Neo MCP 服务器 `@r3e/neo-mcp` 是一个用于 Neo N3 区块链查询和受控、可审计的交易提交的 MCP 服务器。它提供了三个入口点： | 入口点 | 命令 | 协议 | | --- | --- | --- | | MCP 标准输入/输出 | `npm start` | MCP over 标准输入/输出，用于本地客户端，如 Claude Desktop 和 Cursor | | MCP 可流式 HTTP | `npm run start:mcp-http` | MCP over HTTP，用于远程 MCP 客户端 | | REST API | `npm run start:http` | 特制 REST/JSON；不是 MCP 传输 | 两个 HTTP 服务器是无关的，配置是分开的。参见 [远程 MCP over 流式 HTTP](#远程-mcp-over-流式-http) 和 [docs/remote-mcp-transport.md](./docs/remote-mcp-transport.md)。 当前版本：`3.1.0`。需要 Node.js `>=22`。 ## 快速入门 安装并运行 MCP 标准输入/输出服务器： ```bash npm install -g @r3e/neo-mcp neo-mcp ``` 或在不进行全局安装的情况下运行： ```bash npx -y @r3e/neo-mcp ``` Claude Desktop 或 Cursor 配置示例： ```json { "mcpServers": { "neo-n3": { "command": "npx", "args": ["-y", "@r3e/neo-mcp"], "env": { "NEO_NETWORK": "testnet", "NEO_TESTNET_RPC": "https://testnet1.neo.coz.io:443", "LOG_LEVEL": "info" } } } } ``` ## 程序 API 包根目录导出 MCP 服务器、HTTP 服务器、服务、网络枚举和验证配置： ```ts import { NeoNetwork, NeoService } from '@r3e/neo-mcp'; const neo = new NeoService( 'https://testnet1.neo.coz.io:443', NeoNetwork.TESTNET, ); const blockCount = await neo.getBlockCount(); console.log({ blockCount, height: Math.max(0, blockCount - 1) }); ``` `NeoMcpServer` 公开 `run()` 和 `close()`，适用于自行管理标准输入/输出传输生命周期应用程序。 ## 配置 | 变量 | 目的 | 默认值 | | --- | --- | --- | | `NEO_NETWORK` | `mainnet`、`testnet` 或 `both`；HTTP 需要一个网络 | `both` | | `NEO_MAINNET_RPC` | 主网 RPC 端点 | `https://mainnet1.neo.coz.io:443` | | `NEO_TESTNET_RPC` | 测试网 RPC 端点 | `https://testnet1.neo.coz.io:443` | | `NEO_RPC_TIMEOUT_MS` | 每个操作的 Neo RPC 超时（毫秒） | `15000` | | `NEO_ALLOW_INSECURE_RPC` | 允许远程纯文本 HTTP RPC URL | `false` | | `NEO_MAX_TRANSACTION_FEE_GAS` | 签名交易的最高综合系统和网络费用（GAS） | `20` | | `NEO_ENABLE_WRITES` | 注册状态变更工具和 HTTP 路由 | `false` | | `NEO_SIGNER_WIF_FILE` | 仅所有者常规文件，包含单个服务器签名者 WIF | 需要写入 | | `NEO_WRITE_STATE_DIR` | 持久幂等性日志目录 | `$WALLETS_DIR/.write-operations` | | `HTTP_WRITE_APPROVAL_API_KEY` | 独立的 HTTP 写入批准承载令牌 | 需要写入 | | `NEO_ENABLE_WALLET_ADMIN` | 启用 HTTP 钱包创建/导入管理 | `false` | | `N3INDEX_API_BASE_URL` | 远程合约名称查找基准 URL | `https://api.n3index.dev` | | `N3INDEX_ENABLED` | 启用 N3Index 支持的名称解析 | `true` | | `HTTP_HOST` | REST API 监听地址 | `127.0.0.1` | | `HTTP_API_KEY` | REST API 路由的承载令牌 | 未设置 | | `HTTP_CORS_ORIGINS` | 逗号分隔的精确 HTTP/HTTPS 来源 | 空 | | `HTTP_MAX_BODY_BYTES` | 最大 HTTP 请求正文大小 | `1048576`（1 MiB） | | `MCP_HTTP_PORT` | 远程 MCP 传输监听端口 | `3001` | | `MCP_HTTP_HOST` | 远程 MCP 传输监听地址 | `127.0.0.1` | | `MCP_HTTP_PATH` | 远程 MCP 端点路径 | `/mcp` | | `MCP_HTTP_BEARER` | 远程 MCP 端点的承载令牌；除非 `MCP_HTTP_HOST` 是环回地址 | 未设置 | | `MCP_HTTP_ALLOWED_ORIGINS` | 允许从浏览器连接的逗号分隔的精确来源 | 空 | | `MCP_HTTP_MAX_SESSIONS` | 并发远程 MCP 会话上限 | `128` | | `MCP_HTTP_SESSION_TTL_MS` | 空闲远程 MCP 会话过期时间 | `1800000`（30 分钟） | | `WALLETS_DIR` | 持久加密钱包记录目录 | `./wallets` | | `RATE_LIMITING_ENABLED` | 启用请求速率限制 | 在测试环境外部启用 | | `MAX_REQUESTS_PER_MINUTE` | 每个客户端每分钟限制 | `60` | | `MAX_REQUESTS_PER_HOUR` | 每个客户端每小时限制 | `1000` | | `LOG_LEVEL` | `debug`、`info`、`warn` 或 `error` | `info` | | `LOG_CONSOLE` | 启用控制台日志记录 | 在测试环境外部启用 | | `LOG_FILE` | 日志文件路径；设置它启用文件日志记录 | `./logs/neo-mcp.log` | | `LOG_FILE_ENABLED` | 在不设置 `LOG_FILE` 的情况下启用文件日志记录 | `false` | | `PORT` | HTTP 监听端口 | `3000` | 别名 `NEO_MAINNET_RPC_URL`、`NEO_TESTNET_RPC_URL` 和 `NEO_NETWORK_MODE` 仍然受支持。 远程 RPC 端点必须使用 HTTPS。纯 HTTP 仅在环回 RPC 端点中被接受；设置 `NEO_ALLOW_INSECURE_RPC=true` 显式允许远程纯文本 HTTP 并且应该仅限于受控的开发环境。 当 `NEO_NETWORK=both` 时，无明确网络的只读 MCP 调用使用主网。每个状态变更调用都需要明确的网络和幂等键。HTTP 入口点拒绝 `both`；设置 `NEO_NETWORK=mainnet` 或 `NEO_NETWORK=testnet`。 默认情况下，写入是禁用的。要启用写入，请创建所有者专用的签名者文件，并在外部配置持久状态： ```bash install -m 0600 /dev/stdin /run/secrets/neo-signer-wif export NEO_ENABLE_WRITES=true export NEO_SIGNER_WIF_FILE=/run/secrets/neo-signer-wif export NEO_WRITE_STATE_DIR=/var/lib/neo-mcp/write-operations export HTTP_WRITE_APPROVAL_API_KEY="$(openssl rand -hex 32)" ``` MCP 和 HTTP 请求模式永远不会接受 WIF、私钥或密码。MCP 写入需要表单诱导和精确指纹批准。HTTP 写入返回待批准的意图，需要通过 `HTTP_WRITE_APPROVAL_API_KEY` 进行单独的批准请求。 ## HTTP API 这是特制的 REST/JSON API，而不是 MCP 传输。MCP 客户端无法连接到它；它们使用标准输入/输出入口点或 [远程 MCP 传输](#远程-mcp-over-流式-http)。 构建并启动 HTTP 入口点： ```bash npm ci npm run build export HTTP_API_KEY="$(openssl rand -hex 32)" NEO_NETWORK=mainnet npm run start:http ``` 服务器默认监听 `127.0.0.1:3000`。非环回 `HTTP_HOST` 需要 `HTTP_API_KEY`，并且每个配置的 API 密钥必须至少包含 32 个字节。当配置密钥时，在除 `GET /live` 和 `GET /health` 之外的每个路由上发送它作为承载令牌： ```bash curl http://127.0.0.1:3000/live curl http://127.0.0.1:3000/health curl -H "Authorization: Bearer $HTTP_API_KEY" \ http://127.0.0.1:3000/api/blockchain/height ``` HTTP 监听器不终止 TLS。纯 HTTP 仅在环回或受信任的主机本地代理网络上受支持。远程客户端必须通过 TLS 终止的反向代理或负载均衡器使用 HTTPS。 高度端点区分节点的块计数和最新的块索引： ```json { "blockCount": 12346, "height": 12345 } ``` `HTTP_CORS_ORIGINS` 是一个可选的精确来源允许列表。例如： ```bash HTTP_CORS_ORIGINS=https://console.example.com,https://admin.example.com ``` 来源必须使用 HTTP 或 HTTPS，不能包含路径、凭证、查询字符串或片段。通配符 CORS 不受支持。 POST 和 PUT 正文必须是 JSON 对象。默认正文限制为 1 MiB，可以使用 `HTTP_MAX_BODY_BYTES` 更改。写入请求会创建一个不可变的待处理意图： ```bash curl -X POST http://127.0.0.1:3000/api/transfers \ -H "Authorization: Bearer $HTTP_API_KEY" \ -H "Idempotency-Key: transfer-2026-07-11-001" \ -H 'Content-Type: application/json' \ -d '{"network":"mainnet","toAddress":"Nb...","asset":"NEO","amount":"1"}' ``` 仅在比较返回的指纹与预期的请求后才批准： ```bash curl -X POST http://127.0.0.1:3000/api/write-intents/INTENT_ID/approve \ -H "Authorization: Bearer $HTTP_WRITE_APPROVAL_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"fingerprint":"RETURNED_64_HEX_FINGERPRINT"}' ``` 参见 [API.md](./docs/API.md) 获取工具和路由参考。 ## 远程 MCP over 流式 HTTP 流式 HTTP 传输为远程 MCP 客户端提供与标准输入/输出入口点相同的 MCP 工具。它是一个独立于上述 REST API 的进程，监听自己的端口，并具有自己的配置和承载令牌。 ```bash npm ci npm run build export MCP_HTTP_BEARER="$(openssl rand -hex 32)" NEO_NETWORK=mainnet npm run start:mcp-http ``` 服务器默认监听 `127.0.0.1:3001` 并公开： | 方法 | 路径 | 目的 | | --- | --- | --- | | `POST` | `MCP_HTTP_PATH`（默认为 `/mcp`） | JSON-RPC 消息：`initialize`、`tools/list`、`tools/call` | | `GET` | `MCP_HTTP_PATH` | 服务器发起的消息的服务器发送事件流 | | `DELETE` | `MCP_HTTP_PATH` | 终止由 `Mcp-Session-Id` 指定的会话 | | `GET` | `/healthz` | 无身份验证的活动探测 | 非环回 `MCP_HTTP_HOST` 需要 `MCP_HTTP_BEARER` 并且拒绝长度小于 32 个字节的令牌，镜像 `HTTP_API_KEY` 规则为 REST 入口点。当配置令牌时，客户端在每个请求到 `MCP_HTTP_PATH` 时发送 `Authorization: Bearer <token>`；`/healthz` 保持无身份验证，以便探针可以访问它。 使用 MCP TypeScript SDK 连接： ```js import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; const transport = new StreamableHTTPClientTransport(new URL('http://127.0.0.1:3001/mcp'), { requestInit: { headers: { Authorization: `Bearer ${process.env.MCP_HTTP_BEARER}` } }, }); const client = new Client({ name: 'my-client', version: '1.0.0' }, { capabilities: {} }); await client.connect(transport); const { tools } = await client.listTools(); ``` 与 REST 监听器一样，此监听器提供纯 HTTP 服务并且不终止 TLS。远程客户端必须通过 TLS 终止的反向代理访问它。会话存储在内存中，因此多副本部署需要 `Mcp-Session-Id` 头的粘性路由。 参见 [remote-mcp-transport.md](./docs/remote-mcp-transport.md) 获取完整的配置参考、端到端本地运行对抗 Neo Explorer 代理、生产部署指导和故障排除。 ## Docker 生产 Compose 文件是 `docker/docker-compose.yml`。它定义了两个服务，从同一个镜像：`neo-mcp` 在端口 3000 上运行 REST API，`neo-mcp-http` 在端口 3001 上运行远程 MCP 传输。每个都需要自己的令牌，默认绑定主机端口到 `127.0.0.1`，并在其自己的卷中持久化钱包记录： ```bash export HTTP_API_KEY="$(openssl rand -hex 32)" export MCP_HTTP_BEARER="$(openssl rand -hex 32)" docker compose -f docker/docker-compose.yml up -d ``` 仅启动远程 MCP 服务。Compose 插值整个文件，然后选择服务，因此 REST 服务的必填 `HTTP_API_KEY` 必须设置为任意非空占位符，即使在此处永远不会启动其容器（“>= 32 字节”的检查仅在该容器实际启动时运行）： ```bash HTTP_API_KEY=unused-when-starting-only-the-mcp-service \ MCP_HTTP_BEARER="$(openssl rand -hex 32)" \ docker compose -f docker/docker-compose.yml up -d neo-mcp-http ``` 要运行已发布的镜像而不是构建检出，请使用镜像仓库和发布工件的 64 个字符小写十六进制哈希： ```bash NEO_MCP_IMAGE_REPOSITORY=r3enetwork/neo-mcp \ NEO_MCP_IMAGE_DIGEST=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \ HTTP_API_KEY="$HTTP_API_KEY" \ MCP_HTTP_BEARER="$MCP_HTTP_BEARER" \ docker compose -f docker/docker-compose.yml \ -f docker/docker-compose.registry.yml up -d ``` 将 `HTTP_BIND_ADDRESS=0.0.0.0`（REST）或 `MCP_HTTP_BIND_ADDRESS=0.0.0.0`（远程 MCP）仅在服务必须可被 TLS 终止的反向代理或负载均衡器访问时设置。不要将任一纯文本监听器直接暴露给远程客户端。 开发 Compose 文件绑定本地并默认提供本地开发令牌。它定义了 `neo-mcp-dev` 用于 REST API 和 `neo-mcp-http-dev` 用于远程 MCP 传输： ```bash docker compose -f docker/docker-compose.dev.yml up -d ``` 这些默认令牌仅适用于本地开发。覆盖 `HTTP_API_KEY` 和 `MCP_HTTP_BEARER` 以获取任何共享环境。 构建并在不使用 Compose 的情况下运行： ```bash npm run docker:build export HTTP_API_KEY="$(openssl rand -hex 32)" npm run docker:run -- --detach ``` 参见 [DOCKER.md](./docs/DOCKER.md) 获取镜像、卷和帮助脚本的详细信息。 ## MCP 工具和资源 默认 MCP 接口公开 32 个只读工具。每个工具都接受一个必需的 `chain` 区分符，`n3` 或 `neox`，无默默默认值；单链工具拒绝它们不服务的链。`network` 参数始终为 `mainnet` 或 `testnet`；注册表为 Neo X 内部重写它，因此调用者永远不会拼出链限定的网络名称。 - 服务器：`get_network_mode`、`get_wallet` - 链，两条链：`get_chain_info`、`get_block_height`、`get_block`、`get_transaction`、`get_transaction_status`、`get_balance` - 合约，两条链：`call_contract`、`get_contract_info`、`simulate_call` - 构造，两条链：`build_transfer`、`build_contract_call` - 浏览器，两条链：`explorer_get_address`、`explorer_list_address_transactions`、`explorer_list_address_transfers`、`explorer_list_token_holders`、`explorer_search`、`query_explorer` - Neo N3 专用：`get_application_log`、`wait_for_transaction`、`get_unclaimed_gas`、`get_nep17_transfers`、`get_nep11_balances`、`get_nep11_transfers`、`get_contract_status`、`list_famous_contracts`、`estimate_transfer_fees`、`estimate_invoke_fees`、`explorer_list_address_assets`、`query_explorer_find` - Neo X 专用：`query_explorer_graphql` `call_contract` 严格只读：N3 上的 `invokefunction`，Neo X 上的 `eth_call`。`build_*` 工具返回 UNSIGNED 交易提议，供钱包审查和签名；此接口上的任何工具都不持有密钥、签名或广播。 本地启动的标准输入/输出服务器，启用 `NEO_ENABLE_WRITES` 和 `NEO_SIGNER_WIF_FILE`，注册另外四个 Neo N3 工具，这些工具使用提供的密钥签名：`transfer_assets`、`invoke_contract_write`、`claim_gas`、`deploy_contract`。它们需要 `idempotencyKey`、显式 `network`、具有表单诱导的 MCP 客户端和接受确切返回的意图指纹。MCP HTTP 传输由于设计原因而只读。 精选的合约列表在每个条目具有当前网络哈希和已验证的链上清单之前为空。通用合约工具接受脚本哈希、Neo 地址、精确的 N3Index 名称或从实时清单中学习的名称。 `estimate_transfer_fees` 和 `estimate_invoke_fees` 以 `networkFeeDatos` 和 `systemFeeDatos` 返回确切的整数十进制字符串，以及 `networkFeeGas` 和 `systemFeeGas` 中的格式化 GAS 字符串。在任何交易被签名或广播之前，综合系统和网络费用不得超过 `NEO_MAX_TRANSACTION_FEE_GAS`。 `deploy_contract` 接受编译器输出作为完整的序列化 NEF 对象，`nef: { encoding: "hex" | "base64", data: string }`，以及其清单。原始 VM 字节码不是可部署的 NEF 工件。 `get_block_height` 返回 `blockCount` 和 `height`，其中 `height` 为 `max(0, blockCount - 1)`。 资源： - `neo://network/status` - `neo://mainnet/status` - `neo://testnet/status` - `neo://block/{height}` ## 安全注意事项 - 将两个 HTTP 监听器绑定到环回地址，除非需要远程访问。 - 为每个远程 HTTP 连接终止 TLS；在传输过程中，承载令牌验证请求但不加密。 - 为 `HTTP_API_KEY` 和 `MCP_HTTP_BEARER` 使用随机生成的至少 32 个字节的令牌。 - 在任何远程可达的 MCP 监听器上保持 `NEO_ENABLE_WRITES=false`；远程传输仅用于服务只读查询。 - 仅在所有者专用 `NEO_SIGNER_WIF_FILE` 中保存签名者 WIF；永远不要通过 MCP 或 HTTP 发送。 - 将 `WALLETS_DIR` 持久存储在具有限制性权限的受控存储中。 - 状态变更的 MCP 工具需要明确的 `network`、稳定的幂等键和精确的表单诱导的批准。 - 除非 `NEO_ALLOW_INSECURE_RPC=true`，否则拒绝远程纯文本 HTTP RPC 端点；优先使用 HTTPS。 - 当综合系统和网络费用超过 `NEO_MAX_TRANSACTION_FEE_GAS` 时，拒绝签名交易。 - 默认情况下，在类似测试的环境外部启用速率限制。 ## 测试 ```bash # 确定性单元测试；排除 tests/mcp-*.test.ts npm run test:unit # 编译，然后运行确定性构建服务器的烟雾和生命周期检查 npm run build npm run test:mcp # 单元测试 + 构建 + 确定性 MCP 检查 npm run test:all # 选择加入公共 RPC 检查；需要构建和网络访问 npm run build npm run test:mcp:live # 显式压力套件；需要构建 npm run test:mcp:stress ``` `npm run test:integration` 是额外的构建服务器集成脚本，它调用公共 RPC 端点；它不是 `test:all` 的一部分。 ## 发布和依赖检查 `npm audit` 和 `npm audit --omit=dev` 应该通过。包使用作用域的 `lodash@4.18.1` 覆盖传递的 `@cityofzion/neon-core` 依赖。 `./scripts/prepare-release.sh` 安装锁定文件，运行类型检查，确定性测试，构建，两个审计，包验证，Compose 验证和容器构建。它在验证后更新版本并且不创建提交或标签。 GitHub Actions 测试 Node.js 22 和 24。当所需的存储库机密配置好后，发布的 GitHub 版本可以发布 npm 包和 Docker 镜像；存储库中没有定义生产部署目标。 ## 文档 - [API 参考](./docs/API.md) - [远程 MCP 传输](./docs/remote-mcp-transport.md) - [部署指南](./docs/DEPLOYMENT.md) - [Docker 指南](./docs/DOCKER.md) - [测试指南](./docs/TESTING.md) - [生产检查清单](./docs/PRODUCTION_CHECKLIST.md) - [版本管理](./docs/VERSION_MANAGEMENT.md) - [架构](./docs/ARCHITECTURE.md) - [网络](./docs/NETWORKS.md) - [更新日志](./docs/CHANGELOG.md) ## 故障排除 - 安装失败：验证 `node --version` 报告 Node.js 22 或更新，然后重试 `npm ci` 或包安装。 - `HTTP_API_KEY is required`：HTTP 进程正在监听非环回主机。设置一个至少包含 32 个字节的密钥或将 `HTTP_HOST` 绑定到环回地址。 - HTTP `401`：在除 `/live` 和 `/health` 之外的所有路由上发送 `Authorization: Bearer <HTTP_API_KEY>`。 - HTTP `413`：减小请求大小或将 `HTTP_MAX_BODY_BYTES` 增加到正整数。 - 远程 MCP `401`：发送 `Authorization: Bearer <MCP_HTTP_BEARER>`；`/healthz` 是唯一未经身份验证的路由。 - 远程 MCP `404` 在成功 `initialize` 后：会话已过期、被逐出或代理剥离了 `Mcp-Session-Id` 头。参见 [remote-mcp-transport.md](./docs/remote-mcp-transport.md#troubleshooting)。 - RPC 错误：验证所选 RPC URL 是否可达并且支持请求的 Neo RPC 方法。 ## 许可证 MIT。参见 [LICENSE](./LICENSE)。