# AI 代理（MCP）

> 通过 neurochain-mcp Model Context Protocol 服务器把 AI 助手接入 NeuroChain——Claude Code 与 Claude Desktop 的配置、全部读写工具、会话密钥签名、支出上限以及 Sentinel 暂扣。

Source: https://docs.nro.world/zh/build/mcp

`neurochain-mcp` 是一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器。它让 AI 助手——Claude Code、Claude Desktop 或任何 MCP 客户端——读取链上数据，并在你设定的限制内对链进行操作。

```
AI 助手 ⇄ (MCP 经由 stdio) ⇄ neurochain-mcp ⇄ (HTTP) ⇄ gateway :3000 ⇄ 节点 :9933
```

该服务器是仓库 `neurochain-mcp/` 目录下的纯 Node.js 程序（无需构建步骤）。它只与 gateway 的 REST API 通信。

## 安全保障

- 写操作使用**会话密钥**签名，绝不使用钱包的主密钥。会话密钥由你的主密钥授予，带有**作用范围**、**支出上限**和**有效期**，每个验证者都会在共识中强制执行这些限制——参见[账户抽象 → 会话密钥](/zh/ai/account-abstraction#session-keys)。
- 会话密钥不能管理 Sentinel 信任列表，也不能确认被暂扣的转账。如果 [Sentinel](/zh/ai/sentinel) 暂扣了一笔有风险的转账，只有你本人才能放行。
- 质押、委托和治理投票不向代理开放。
- 没有会话密钥时，服务器以**只读**模式运行。

## 配置

### 1. 安装

```bash
cd neurochain-mcp
npm install
```

### 2. 创建会话密钥和配置文件

在 Web 钱包中打开 **Agent** 面板，创建会话密钥——选择它可以转账的目标地址（或 `*`）、总支出上限以及有效的区块数——然后点击 **Export config**。你会得到：

```json
{
  "node_rpc": "http://localhost:3000",
  "account": "neuro:<15 hex>.human",
  "session_pk": "<会话公钥，hex>",
  "sk_seed_hex": "<会话密钥 seed，hex>",
  "scope": "*"
}
```

| 字段 | 含义 |
|------|------|
| `node_rpc` | **gateway** 的 URL（不是节点的 9933 端口）。钱包会填入当前页面自身的地址；如果 gateway 运行在别处，请修改 |
| `account` | 代理所代表的地址 |
| `session_pk`、`sk_seed_hex` | 会话密钥。两者都留空即为只读 |
| `scope` | 仅供参考——真正生效的是链上的授权 |

把文件保存在仓库之外并妥善保管：`sk_seed_hex` 是机密。

### 3. 注册服务器

**Claude Code：**

```bash
claude mcp add neurochain \
  --env NEUROCHAIN_MCP_CONFIG=/absolute/path/to/neurochain-mcp.config.json \
  -- node /absolute/path/to/neurochain-mcp/src/index.js
```

**Claude Desktop**（`claude_desktop_config.json`）或项目的 `.mcp.json`：

```json
{
  "mcpServers": {
    "neurochain": {
      "command": "node",
      "args": ["/absolute/path/to/neurochain-mcp/src/index.js"],
      "env": { "NEUROCHAIN_MCP_CONFIG": "/absolute/path/to/neurochain-mcp.config.json" }
    }
  }
}
```

请使用绝对路径：客户端会从它自己的工作目录启动服务器。

## 工具

### 读取

| 工具 | 参数 | 返回 |
|------|------|------|
| `nc_get_account` | `address`（默认：配置的账户） | 余额、nonce、交易数量 |
| `nc_get_txs` | `address`、`limit`（1–200） | 交易历史 |
| `nc_gas_estimate` | — | 基础费用和费用估算 |
| `nc_list_proposals` | `status`、`limit`（1–100）、`offset` | 带计票结果的治理提案 |
| `nc_list_validators` | — | 验证者及其质押和指标 |
| `nc_get_contract` | `address`（`.app`） | 所有者、代码哈希、安全分数 |
| `nc_analyze_contract` | `bytecode_hex` | VMGuardian 分析——风险、违规项 |
| `nc_get_session_grants` | `address` | 账户的会话密钥，含上限和已花费金额 |
| `nc_get_held` | `address` | 被 Sentinel 暂扣的转账 |

### 写入（需要会话密钥）

| 工具 | 参数 | 说明 |
|------|------|------|
| `nc_transfer` | `to`、`amount_nro`（NRO，可带小数） | 如果被 Sentinel 暂扣，工具会说明它是会自动放行，还是需要你确认 |
| `nc_call_contract` | `to`（`.app`）、`function`、`args`、`value`（uNRO，默认 0） | |
| `nc_deploy` | `bytecode_hex`、`name`、`description`、`template`、`init_args` | 与任何部署一样经过 VMGuardian 关卡 |

每次写操作都会读取下一个 nonce，用会话密钥签名，并发送到 `POST /api/v1/transactions`。节点在每个验证者上检查授权；例如，超出上限的转账会返回：

```
Error: POST /api/v1/transactions failed: HTTP 401 — session spend cap exceeded
```

## 已验证

在本地测试网络上：读取工具返回实时数据；使用上限为 5 NRO 的会话密钥执行 1 NRO 的 `nc_transfer` 得到确认，授权中记录为 `spent: 1000000`；随后一笔 10 NRO 的转账以上述错误被拒绝；未配置会话密钥时，写入工具直接拒绝，不做任何签名。

## 撤销

在钱包的 Agent 面板中撤销密钥，或用主密钥签名调用 `POST /api/v1/session/revoke`。从下一个区块起，用该密钥签名的一切操作都会被拒绝。