内容
# Numen MCP
将你的 [Numen](https://github.com/Dwinovo/minecraft-numen) 同伴转化为外部人工智能可以直接驱动的工具。Numen MCP 在你的游戏客户端内运行一个小型 [模型上下文协议](https://modelcontextprotocol.io) 服务器，这样像 **Claude** 这样的代理可以列出你的同伴，控制其中一个，并直接调用其工具 — Claude 成为大脑，同伴成为其手和眼。
多加载器（Fabric + NeoForge），Minecraft 1.21.1。
## 与普通 Numen 同伴的区别
通常，Numen 同伴通过其内置的大型语言模型进行思考。Numen MCP 允许外部大脑完全跳过该大型语言模型：
- **Claude 是玩家。** 它通过感知工具（`get_self_status`、`scan_blocks` 等）读取世界，并自行决定每一步行动。
- **无需 Numen API 密钥** — Claude 进行推理；同伴仅执行工具。
- **平行舰队。** 每个调用都针对一个同伴，每个身体独立运行其任务，因此一个代理可以同时驱动多个同伴。
- **生存合法。** 暴露的工具与内置大脑使用的工具相同 — 挖掘、移动、放置、合成。没有任何物品是从无中生有的。
## 要求
- **[Numen](https://github.com/Dwinovo/minecraft-numen) 0.0.4+** （捆绑了 numen-api 引擎和 `NumenActuator`）
- 客户端 — 同伴及其工具注册表存在于所有者的游戏客户端中
- 一个 MCP 客户端：Claude Code（原生 HTTP）或 Claude Desktop（通过 `mcp-remote`）
## 设置
1. 在您的客户端中安装 Numen + Numen MCP。启动一次；它会写入 `config/numen/mcp_server.json`。当它正在监听时，日志会打印 `MCP server up on http://127.0.0.1:8765/mcp`。
2. 将您的 MCP 客户端指向它：
- **Claude Code** — 项目中的 `.mcp.json`：
```json
{ "mcpServers": { "numen": { "type": "http", "url": "http://127.0.0.1:8765/mcp" } } }
```
- **Claude Desktop** — `claude_desktop_config.json`（需要 Node/npx）：
```json
{ "mcpServers": { "numen": { "command": "npx", "args": ["mcp-remote", "http://127.0.0.1:8765/mcp"] } } }
```
3. 在游戏中召唤一个同伴，然后在您的代理中：`list_companions` → `acquire_companion` → 控制它。MCP 服务器仅在游戏运行时监听。
## 工具
| 工具 | 功能 |
|---|---|
| `list_companions` | 列出您的在线同伴（名称 + ID） |
| `acquire_companion` | 接管 — 暂停内置大脑，释放身体 |
| `release_companion` | 将同伴还给其内置大脑 |
| *(引擎工具)* | 每个 Numen 身体/感知工具（`get_self_status`、`scan_blocks`、`auto_mine`、`move_to`、`place_block` 等），每个工具都需要一个 `companion` 参数 |
## 训练您的代理
连接时，服务器会向代理提供简短的简介（MCP 的 `instructions`）— 什么是 Numen 以及 `acquire → perceive → act → release` 循环 — 因此任何 MCP 客户端都可以开箱即用。
对于 **Claude Code** 中的更丰富、始终在线的技能，请安装捆绑的技能：将 [`agent-skill/numen`](agent-skill/numen/SKILL.md) 复制到您的技能目录中（`~/.claude/skills/numen/` 或您的项目中的 `.claude/skills/numen/`）。然后，Claude 在您要求它玩 Minecraft 时会自动拾取它。
## 多人游戏
适用于远程服务器。Numen MCP 是客户端的，并且通过 Numen 现有的客户端→服务器协议驱动 — 与内置大脑使用的相同数据包。服务器需要安装 Numen（因为同伴存在时已经安装）；它 **不需要** Numen MCP。服务器所有者检查每一步操作，因此您只能驱动您拥有的同伴。
## 配置参考 — `config/numen/mcp_server.json`
- `enabled` — 主开关。
- `host` / `port` — HTTP 端点绑定的位置（默认为环回地址）。
- `token` — 可选的 bearer token；设置后，请求必须提供它（`Authorization: Bearer <token>` 或 `?token=`）。
- `call_timeout_seconds` — `tools/call` 在报告超时之前等待身体动作的时间。
- `hidden_tools` — 不向外部代理公开的引擎工具（代理内部记账）。
## 状态
早期。目前，动作工具是 **阻塞** 的（`tools/call` 会一直等待身体完成任务）；计划使用非阻塞的启动/轮询模型和 Groovy 技能编写层。
## 生态系统
**Numen** ([minecraft-numen](https://github.com/Dwinovo/minecraft-numen)) 是模组 — 人工智能同伴。它运行在 **[numen-api](https://github.com/Dwinovo/numen-api)** 引擎上（通过 **[numen-maven](https://github.com/Dwinovo/numen-maven)** 发布），该引擎公开了一个小型公共 API。两个事物建立在它之上：
**扩展同伴** — 其自身的大脑保持控制：
- **桥梁** 将外部通道带入同伴：消息到达，同伴决定做什么。基于 `NumenGateway`。→ **[numen-qq-bridge](https://github.com/Dwinovo/numen-qq-bridge)** （QQ），未来会有更多。
- **技能** 教同伴如何行为 — 加载到其上下文的 Markdown。Numen 捆绑，或社区编写。
**公开 Numen** — 将控制权交给外部大脑：
- **[numen-mcp](https://github.com/Dwinovo/numen-mcp)** 是一个模型上下文协议服务器：任何外部代理（像 Claude）都可以直接驱动同伴。基于 `NumenActuator`。*（此仓库）*
MIT 许可。
