Neo N3 MCP Server

Neo MCP 服务

@r3e/neo-mcp 是一个用于 Neo N3 区块链查询以及受控、可审计交易提交的 MCP 服务。它提供三个入口：

入口	命令	协议
MCP stdio	npm start	通过 stdin/stdout 使用 MCP，适用于 Claude Desktop 和 Cursor 等本地客户端
MCP HTTP	npm run start:mcp-http	MCP 2026-07-28 无状态 HTTP，适用于远程 MCP 客户端
REST API	npm run start:http	专用 REST/JSON；不是 MCP 传输方式

这两个 HTTP 服务互不相关，且分别配置。请参阅 远程 MCP 2026 HTTP 和 docs/remote-mcp-transport.md。

当前版本：4.2.1。要求使用 Node.js >=22。4.x 版本仅支持 MCP 2026-07-28；使用已移除的初始化／会话协议的客户端将被拒绝，而不会降级。

快速开始

安装并运行 MCP stdio 服务：

npm install -g @r3e/neo-mcp
neo-mcp

或者无需全局安装即可运行：

npx -y @r3e/neo-mcp

Claude Desktop 或 Cursor 配置示例：

{
  "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 服务、服务模块、网络枚举和经过验证的配置：

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()，供自行管理 stdio 传输生命周期的应用使用。

配置

变量	用途	默认值
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
NEO_MCP_REQUEST_STATE_KEY	用于 MCP 多轮审批状态的独立 HMAC 密钥	写入操作必需
HTTP_WRITE_APPROVAL_API_KEY	用于 HTTP 写入审批的独立 bearer 令牌	写入操作必需
NEO_ENABLE_WALLET_ADMIN	启用 HTTP 钱包创建／导入管理功能	false
N3INDEX_API_BASE_URL	远程合约名称查询的基础 URL	https://api.n3index.dev
N3INDEX_ENABLED	启用由 N3Index 支持的名称解析	true
EXPLORER_ACCOUNT_WATCH_ENABLED	启用需双重确认的 Explorer 账户 Watch 请求工具	false
EXPLORER_ACCOUNT_WATCH_API_URL	固定的 Explorer Watch API 端点	https://www.neo3scan.com/api/account-watches
EXPLORER_ACCOUNT_WATCH_API_TOKEN	Explorer Watch API 专用 bearer 令牌；必须与 MCP／REST bearer 令牌不同	启用时必需
HTTP_HOST	REST API 监听地址	127.0.0.1
HTTP_API_KEY	REST API 路由的 bearer 令牌	未设置
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 端点的 bearer 令牌；除非 MCP_HTTP_HOST 是环回地址，否则必需	未设置
MCP_HTTP_ALLOWED_ORIGINS	以逗号分隔的允许浏览器连接的精确来源	空
MCP_HTTP_MAX_CONCURRENT_REQUESTS	并发处理中 MCP 请求数上限	128
MCP_HTTP_MAX_SUBSCRIPTIONS	并发 subscriptions/listen 流数量上限	128
MCP_HTTP_MAX_BODY_BYTES	MCP POST 正文大小上限	1048576（1 MiB）
MCP_HTTP_BODY_TIMEOUT_MS	接收 MCP 请求正文的截止时间	30000
MCP_HTTP_HEADERS_TIMEOUT_MS	接收 MCP 标头的截止时间	30000
MCP_HTTP_REQUEST_TIMEOUT_MS	MCP HTTP 请求的总截止时间	300000
MCP_HTTP_KEEP_ALIVE_MS	SSE 保活间隔；0 表示禁用	15000
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 仍受支持。

MCP 工具参数的数组元素与对象成员合计上限为 10,000。HTTP 传输会在构建应用服务前强制执行此限制；stdio 则由 MCP SDK 执行相同的限制。 远程 RPC 端点必须使用 HTTPS。环回 RPC 端点可以使用普通 HTTP；设置 NEO_ALLOW_INSECURE_RPC=true 可明确允许远程明文 HTTP，但仅应在受控开发环境中使用。

当 NEO_NETWORK=both 时，未明确指定网络的只读 MCP 调用使用主网。每个会更改状态的调用都必须明确指定网络并提供幂等键。HTTP 入口点会拒绝 both；请设置 NEO_NETWORK=mainnet 或 NEO_NETWORK=testnet。

默认情况下会禁用写入。若要启用写入，请在仓库外创建仅限所有者访问的签名文件，并配置持久化状态：

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 NEO_MCP_REQUEST_STATE_KEY="$(openssl rand -hex 32)"
export HTTP_WRITE_APPROVAL_API_KEY="$(openssl rand -hex 32)"

MCP 和 HTTP 请求架构均不接受 WIF、私钥或密码。 MCP 写入使用 2026-07-28 的 input_required 流程。服务会对 不透明的 requestState 签名，将其绑定到 tools/call，十分钟后使其过期， 且仅当重新输入的响应接受确切的意图指纹后才会执行。 HTTP 写入会返回待处理意图，并要求使用 HTTP_WRITE_APPROVAL_API_KEY 验证的 单独审批请求。

账户情报始终以证据为先：analyze_account_graph 仅公开可重放、按网络限定的转账图 和精选元数据。后端的确定性交易所归集、协同签名者、 社区关联性和图相似度检测器队列不会作为公开身份数据 公开；待处理候选项必须经人工审核后，才能成为精选元数据。

截至 2026-08-01，两个生产网络的检测器定时任务均已成功完成 检测器重新运行。由此产生的待处理队列仅作为运营审核证据， 不会由 analyze_account_graph 返回。

HTTP API

这是专用的 REST/JSON API，不是 MCP 传输方式。MCP 客户端无法连接到它；它们使用 stdio 入口点或远程 MCP 传输。

构建并启动 HTTP 入口点：

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 外，每个路由都必须通过 bearer token 发送该密钥：

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；不支持直接通过远程明文 HTTP 连接，因为 bearer token 会在请求中传输。

高度端点会区分节点的区块数量与最新区块索引：

{
  "blockCount": 12346,
  "height": 12345
}

HTTP_CORS_ORIGINS 是可选的精确来源允许列表。例如：

HTTP_CORS_ORIGINS=https://console.example.com,https://admin.example.com

来源必须使用 HTTP 或 HTTPS，且不得包含路径、凭据、查询字符串或片段。不支持通配符 CORS。

POST 和 PUT 请求正文必须是 JSON 对象。默认正文大小上限为 1 MiB，可通过 HTTP_MAX_BODY_BYTES 更改。写入请求会创建不可变的待处理意图：

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"}'

仅在将返回的指纹与预期请求进行比较后才进行审批：

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。

远程 MCP 2026 HTTP

无状态 MCP 2026-07-28 HTTP 传输为远程客户端提供与 stdio 入口相同的非托管 MCP 接口。它是独立于 REST API 的进程，监听自己的端口，并拥有自己的配置和持有者令牌。默认情况下，唯一的外部副作用是 request_account_watch，除非显式配置，否则该功能处于禁用状态；它只能发送双重确认验证消息，无法激活订阅。

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）	无状态 MCP 2026-07-28 请求，例如 server/discover、tools/list 和 tools/call
OPTIONS	MCP_HTTP_PATH	CORS 预检
GET	/healthz	无需身份验证的存活探针

如果 MCP_HTTP_HOST 不是回环地址，则必须设置 MCP_HTTP_BEARER，且令牌长度不得少于 32 字节；这与 REST 入口的 HTTP_API_KEY 规则一致。配置令牌后，客户端每次向 MCP_HTTP_PATH 发送请求时都必须携带 Authorization: Bearer <token>；/healthz 仍无需身份验证，以便探针访问。

使用 MCP TypeScript SDK 连接：

import {
  Client,
  StreamableHTTPClientTransport,
} from '@modelcontextprotocol/client';

const transport = new StreamableHTTPClientTransport(new URL('http://127.0.0.1:3001/mcp'), {
  authProvider: { token: async () => process.env.MCP_HTTP_BEARER },
});
const client = new Client(
  { name: 'my-client', version: '2.0.0' },
  {
    capabilities: {},
    versionNegotiation: { mode: { pin: '2026-07-28' } },
  },
);
await client.connect(transport);
const { tools } = await client.listTools();

与 REST 监听器一样，此监听器提供明文 HTTP，不会终止 TLS。远程客户端必须通过终止 TLS 的反向代理访问。请求是无状态的，因此副本之间无需粘性路由。

完整配置参考、使用 Neo Explorer Agent 进行端到端本地运行的说明、生产环境部署指南和故障排查，请参阅 remote-mcp-transport.md。

Docker

生产环境 Compose 文件为 docker/docker-compose.yml。它使用同一镜像定义两个服务：neo-mcp 在端口 3000 上运行 REST API，neo-mcp-http 在端口 3001 上运行远程 MCP 传输。每个服务都需要自己的令牌，默认将主机端口绑定到 127.0.0.1，并将钱包记录持久化到各自的卷中：

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 bytes” 检查仅在该容器实际启动时运行）：

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 位小写十六进制摘要：

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

只有在服务必须通过终止 TLS 的反向代理或负载均衡器访问时，才设置 HTTP_BIND_ADDRESS=0.0.0.0（REST）或 MCP_HTTP_BIND_ADDRESS=0.0.0.0（远程 MCP）。不要将任一明文监听器直接暴露给远程客户端。

开发环境 Compose 文件默认绑定本地地址，并提供本地开发令牌。它为 REST API 定义了 neo-mcp-dev，为远程 MCP 传输定义了 neo-mcp-http-dev：

docker compose -f docker/docker-compose.dev.yml up -d

这些默认令牌仅供本地开发使用。在任何共享环境中，都应覆盖 HTTP_API_KEY 和 MCP_HTTP_BEARER。

不使用 Compose 构建并运行：

npm run docker:build
export HTTP_API_KEY="$(openssl rand -hex 32)"
npm run docker:run -- --detach

有关镜像、卷和辅助脚本的详细信息，请参阅 DOCKER.md。

MCP 工具和资源

默认 MCP 接口提供 59 个非托管工具。两个链都实现的每个工具都必须传入必填的 chain 区分参数 "n3" 或 "neox"，没有默认值；单链工具会拒绝其不支持的链。network 参数始终为 "mainnet" 或 "testnet"；注册表会在内部将其改写为 Neo X 对应的网络，因此调用方无需写出带链名称的网络名。

• 服务端和数据实用工具：get_network_mode、get_wallet、inspect_neo_value、convert_neo_data、get_neo_service_info、analyze_stablecoins
• 链，两条链均支持：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
• Neo 生态查询：decode_neo_script、query_nns、query_neofs、get_oracle_info
• 收款方解析：resolve_recipient
• 专用 Neo N3 构建工具：build_vote、build_nns_operation
• 区块浏览器和智能分析：explorer_get_address、analyze_address、analyze_account_graph、analyze_consensus_health、analyze_address_connection、analyze_transaction、investigate_transactions、analyze_contract、analyze_contract_upgrades、get_contract_source_verification、inspect_contract_code、analyze_neox_transaction、analyze_neox_block、analyze_neox_address、analyze_neox_contract、analyze_neox_token、explorer_list_address_transactions、explorer_list_address_transfers、explorer_list_token_holders、explorer_search、query_explorer
• 已验证的通知操作：request_account_watch 会针对明确指定的 Neo N3 网络、地址和电子邮件发送受冷却时间限制的验证消息。该操作不会造成破坏，且具有幂等性；收件人在区块浏览器中确认前，监控不会生效。
• 仅 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 支持：analyze_neox_transaction、analyze_neox_block、analyze_neox_address、analyze_neox_contract、analyze_neox_token、query_explorer_graphql

call_contract 严格只读：在 Neo N3 上使用 invokefunction，在 Neo X 上使用 eth_call。build_* 工具会运行精确的只读模拟，并返回供钱包审核和签名的未签名交易提案；默认接口中的工具不会持有密钥、签名或广播交易。build_vote 固定使用原生 NEO 合约，而 build_nns_operation 固定使用网络对应的 NameService 合约和操作参数。

调用 build_transfer 前，resolve_recipient 会解析转账收款方：输入的 Neo N3 地址会原样返回，且不会再次读取；.neo 名称则通过其 NNS TXT 记录解析，并以所有者和注册到期时间作为来源信息。该工具要求明确指定 network，且具有确定性——仅使用一种记录类型、没有默认值，也不使用缓存。它采用失败即关闭策略：名称未注册、缺少所有者、记录不是 Neo N3 地址、无法读取到期时间，或任何链上读取未能停止，都会抛出错误，绝不会回退到其他地址。query_nns 仍是用于发现的工具，并非收款方解析器。

query_neofs 要求显式提供 network 字段。结果中会保留所选 N3 网络作为地址上下文，而固定的 NeoFS 网关仍为全局设置；这样可避免助手将主网／测试网 N3 上下文误报为 NeoFS 网关切换。

构建的 N3 和 Neo X 提案均会以仅限未签名的形式返回，并在区块浏览器向钱包展示之前进行模拟。

Explorer AI 路线图

跨仓库的权威计划维护在 Neo OS Fura AI 计划与路线图中。 Neo MCP 是类型化的编排边界：它向助手公开确定性的 Explorer 证据和未经签名的模拟提案，同时将钱包审核、签名和广播保留在托管的 MCP 服务之外。

analyze_transaction 是 Neo N3 的主要调查工具。其 v2 响应新增稳定的证据 ID、有界计数、精确的分组资金流、保守的失败分类和基于代码的发现。客户端应引用这些 ID、保留精确的十进制字符串，并说明何时无法获取详细的操作码或存储追踪。

investigate_transactions 将一至十二笔已确认的 Neo N3 交易组合成一个确定且不可变的证据集。它会返回按区块排序的时间线、每笔交易的完整分析，以及观测到的资产关系，其中包含来源交易、证据引用、置信度类别和 requested_transactions_only 采样边界。它不会推断共同所有权、因果关系、隐藏调用或集合之外的活动。

analyze_contract 是 Neo N3 的主要合约情报工具。其 v1 响应会返回限定网络范围的 ABI、Manifest 权限与信任、NEF 方法令牌、编译器、更新和源代码验证事实，并附带稳定的证据 ID。客户端必须区分声明的源代码 URL、safe=false ABI 方法、确定性的静态发现、已验证源代码、模拟和漏洞声明。

inspect_contract_code 是分页代码检查配套工具。它会返回有界的 NeoVM 操作数、已解析的系统调用名称、ABI 方法归属关系，以及带稳定操作码证据 ID 的静态控制流目标。它提供的是确定性反汇编，而非运行时追踪、已验证源代码、反编译或模拟。

analyze_contract_upgrades 按更新计数器比较不可变的已索引合约制品。它会报告精确的 complete 或 partial 历史覆盖情况、SHA-256 制品标识，以及结构性的 ABI 方法、事件和标准变更。不会合成缺失版本；由于 Manifest 和 NEF 制品无法证明存储布局，存储兼容性始终为 not_determined。

get_contract_source_verification 会为每个已验证的更新计数器返回不可变的可复现性记录：源代码包摘要、不可变的仓库提交、编译器设置，以及精确的 Manifest、NEF、二进制文件和脚本哈希。只有当前更新计数器对应的记录才能验证当前代码。制品完全相同并不等同于安全审计。

使用 NEO_ENABLE_WRITES=true、NEO_SIGNER_WIF_FILE 和 NEO_MCP_REQUEST_STATE_KEY 在本地启动的 stdio 服务会注册另外四个 Neo N3 工具，并使用由所有者提供的密钥进行签名： transfer_assets、invoke_contract_write、claim_gas、deploy_contract。 这些工具要求提供 idempotencyKey 和显式的 network，使用能够完成内嵌表单请求的现代客户端，并通过 input_required 确认完全匹配的返回意图指纹。MCP HTTP 传输按设计仅供读取，会忽略此设置。

在每个条目都具有当前网络哈希和经过验证的链上 Manifest 之前，精选合约列表会有意保持为空。通用合约工具接受脚本哈希、Neo 地址、精确的 N3Index 名称，或从实时 Manifest 中获取的名称。

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 }，并附带其 Manifest。原始 VM 字节码不是可部署的 NEF 制品。 get_block_height 同时返回 blockCount 和 height，其中 height 为 max(0, blockCount - 1)。

对于 Neo N3 区块分析，向 get_block 传入 includeStateRoot: true，即可获取准确的 StateService 根，以及本地和经 StateValidator 验证的高度边界。仅当请求的根位于已验证边界以内或之上时，返回的 validated 标志才为 true。Neo X 不接受此 N3 专用选项，普通区块查询不会产生额外的 RPC 调用。Neo N3 区块响应还会在节点的毫秒级 time 值旁，包含确定性的 ISO-8601 格式 timeIso。

资源：

• neo://network/status
• neo://mainnet/status
• neo://testnet/status
• neo://block/{height}

安全说明

• 除非需要远程访问，否则请将两个 HTTP 监听器都绑定到 loopback。
• 每个远程 HTTP 连接都应先终止 TLS；Bearer token 可以验证请求身份，但自身不会对传输内容加密。
• HTTP_API_KEY 和 MCP_HTTP_BEARER 请使用随机生成的至少 32 字节的令牌。
• 对任何可从远程访问的 MCP 监听器，请保持 NEO_ENABLE_WRITES=false；远程传输绝不能携带交易签名者。
• 除非部署有意支持验证邮件，否则请保持 EXPLORER_ACCOUNT_WATCH_ENABLED=false。启用时，请使用专用的、至少 32 字节的 EXPLORER_ACCOUNT_WATCH_API_TOKEN，且该令牌不得与任何传输/API Bearer 令牌相同。
• 签名者 WIF 仅保存在仅所有者可访问的 NEO_SIGNER_WIF_FILE 中；绝不要通过 MCP 或 HTTP 发送。
• 将 WALLETS_DIR 持久化到受控存储中，并设置严格的权限。
• 修改状态的 MCP 工具需要明确指定 network、使用稳定的幂等键，并提供准确的 input_required 批准；其请求状态必须通过 HMAC、过期时间、方法绑定、意图、网络、操作和指纹检查。
• 除非设置 NEO_ALLOW_INSECURE_RPC=true，否则会拒绝远程明文 HTTP RPC 端点；建议使用 HTTPS。
• 如果已签名交易的系统费和网络费总和超过 NEO_MAX_TRANSACTION_FEE_GAS，则会拒绝该交易。
• 默认情况下，在非测试类环境中启用速率限制。

测试

# Deterministic unit tests; excludes tests/mcp-*.test.ts
npm run test:unit

# Compile, then run deterministic built-server smoke and lifecycle checks
npm run build
npm run test:mcp

# Unit tests + build + deterministic MCP checks
npm run test:all

# Opt-in public RPC checks; requires a build and network access
npm run build
npm run test:mcp:live

# Explicit stress suite; requires a build
npm run test:mcp:stress

npm run test:integration 是一项额外的已构建服务集成脚本，会调用公共 RPC 端点；它不属于 test:all。

发布与依赖检查

预期 npm audit 和 npm audit --omit=dev 均能通过。此软件包使用针对传递依赖 @cityofzion/neon-core 的作用域 [email protected] 覆盖项。

./scripts/prepare-release.sh 会安装锁文件、运行类型检查、确定性测试、构建、两项审计、软件包验证、Compose 验证和容器构建。只有在验证完成后才会更新版本，且不会创建提交或标签。

GitHub Actions 会测试 Node.js 22 和 24。配置好所需的仓库密钥后，已发布的 GitHub 版本可以发布 npm 软件包和 Docker 镜像；此仓库未定义生产部署目标。

文档

• API 参考
• 远程 MCP 传输
• 部署指南
• Docker 指南
• 测试指南
• 生产环境检查清单
• 版本管理
• 架构
• 网络
• 更新日志

故障排除

• 安装失败：确认 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 -32022：客户端未固定使用 2026-07-28，或尝试使用已移除的旧版初始化流程。请升级到 @modelcontextprotocol/client v2。
• 远程 MCP -32020：请求的 Mcp-Method、Mcp-Name 或协议版本标头与请求正文不一致。请改用 v2 SDK，而不是手动构造信封。
• RPC 错误：确认所选 RPC URL 可访问，并支持所请求的 Neo RPC 方法。

许可证

MIT。请参阅 LICENSE。