novai-mcp-server

NOVAI MCP 服务

一个只读的模型上下文协议（MCP）服务，可让任何支持 MCP 的 Agent 通过公开的 JSON-RPC 端点查询实时 NOVAI 链。它仅提供查询工具。此软件包中没有任何写入、签名、提交或密钥处理路径。

NOVAI 是一个采用链式 BFT 共识的 AI 原生 Layer 1。此服务是一个轻量、类型化的桥接层：Agent 可通过标准 MCP 工具发现这些工具并读取链，无需编写任何 SDK 代码。

安全边界

这是 0 版，设计上仅支持只读操作。

• 每个工具都是一个查询，对应公开端点上的一个读取方法。
• 此软件包不会持有私钥、签名或提交交易。
• 链提供的写入方法不会接入此服务。

要求

• Node.js 18 或更高版本。

安装和运行

直接使用 npx 运行：

npx novai-mcp-server

或者安装后运行二进制文件：

npm install novai-mcp-server
novai-mcp-server

此服务通过 stdio 使用 MCP 通信。将 MCP 客户端指向上面的命令。

MCP 客户端配置示例

{
  "mcpServers": {
    "novai": {
      "command": "npx",
      "args": ["novai-mcp-server"]
    }
  }
}

配置

• NOVAI_RPC_URL 用于覆盖 JSON-RPC 端点。默认值为 NOVAI 的公开 URL：https://rpc.novai.network。无需其他配置、密钥或身份验证，因为该公开端点开放且只读。

工具

所有哈希和 ID 均为 64 个十六进制字符（32 字节，不带 0x 前缀）。所有高度均为非负整数。每项输入都会在任何网络调用前经过验证；链错误和传输故障都会作为清晰的工具错误返回，且不包含堆栈跟踪。

工具	返回内容	必需参数	可选参数
novai_get_chain_status	最新已提交区块，可用于验证链是否在线并获取链顶高度	无	无
novai_get_block	单个区块	height 或 hash，且必须且只能指定其中一个	无
novai_get_transaction	已确认的交易；如果未知则返回 null	txid	无
novai_get_ai_entity	AI 实体（Agent）记录；如果未知则返回 null	entity_id	无
novai_get_balance	地址的余额（十进制字符串）和 nonce	address	无
novai_get_signals_by_height	指定高度记录的信号承诺	height	无
novai_get_signals_by_issuer	实体在指定高度范围内发布的信号	issuer、start_height、end_height	无
novai_get_signals_by_type	指定类型在指定高度范围内的信号	signal_type、start_height、end_height	无
novai_get_oracle_anchor	按信号哈希查询预言机锚点；如果未知则返回 null	signal_hash	无
novai_get_oracle_anchors_by_entity	按发布者查询指定高度范围内的预言机锚点	entity_id、start_height、end_height	ts_min、ts_max
novai_get_oracle_anchors_by_tag	按数据标签查询指定高度范围内的预言机锚点	data_tag、start_height、end_height	ts_min、ts_max
novai_get_memory_objects	实体拥有的链上记忆对象	entity_id	无

关于按高度查询区块的说明

端点只保留有限的近期区块高度窗口，因此，远低于当前链顶的高度可能返回 null，即使该高度曾对应有效区块。只要节点仍在索引某个区块，就可以按哈希查询该区块。先调用 novai_get_chain_status 获取当前链顶高度。

开发

npm install
npm run build
npm test

npm test 会运行离线单元测试和验证测试。要测试在线端点：

npm run test:live

还可进行端到端 stdio 检查：启动已构建的服务，并使用真实 MCP 客户端调用它：

npm run build && node scripts/smoke.mjs

许可证

MIT。请参阅 LICENSE 文件。