内容
# Mineai工具包
MCP 服务器，用于与 Minecraft 进行交互。
## 运行时结构
一个进程服务所有功能。您可以手动启动它：
```bash
mineai-control
```
在 `http://127.0.0.1:8765` 上，它提供了以下接口：
| 路径 | 功能 |
| --- | --- |
| `/` | 网页 UI — 机器人、活动、控制台 |
| `/mcp` | MCP 端点（HTTP 传输） |
| `/health`、`/bots`、`/api/*` | JSON API |
opencode 作为一个 **远程** MCP 客户端连接并启动：
```json
"mineai-toolkit": { "type": "remote", "url": "http://127.0.0.1:8765/mcp" }
```
### 为什么使用一个进程
机器人在一个模块全局的 `BotManager` 中运行。以前的 stdio 设计允许每个 opencode 窗口启动自己的服务器，因此在网页 UI 中创建的机器人对于模型来说是不可见的——它与一个不同的进程通信，该进程有一个空的机器人列表。工具执行也不能分开：`tools/pathfinder.py` 操纵实时的 JSPyBridge 代理对象，这些对象不能跨进程边界。
启动第二个实例时，它会快速失败，而不是重新创建分割：
```text
[mineai] 127.0.0.1:8765 已被占用。
```
`mineai-mcp`（旧的 stdio 入口点）现在退出，并指向此命令。
### 环境
```bash
MINEAI_OPEN_UI=0 mineai-control # 不打开浏览器标签
MINEAI_CONTROL_HOST=127.0.0.1 MINEAI_CONTROL_PORT=8765 mineai-control
```
机器人连接的默认设置来自 `mineai_toolkit/.env`（参见 `.env.example`），在启动时读取一次。它们仅在创建机器人 **不使用** 帐户简写时应用；显式参数始终优先。
## 观察模型工作
**活动** 标签页是一个实时馈送，显示每个工具的调用——源（`模型` / `人类`）、名称、持续时间和点击后完整的参数和返回值。机器人生命周期事件（生成、踢出、断开连接）也一并显示，因此失败的登录会显示其原因，而不是无声地执行。
**控制台** 标签页根据工具的 JSON 模式渲染一个表单，并通过模型使用的同一个 FastMCP 实例运行它，标记为 `人类`。相同的执行路径，相同的中间件，相同的时序——因此学生的手动调用和模型的调用可以直接比较。
日志中会遮蔽密钥，环形缓冲区会保存最后 500 个事件。
## 控制 API
健康检查：
```bash
curl http://127.0.0.1:8765/health
```
列出机器人：
```bash
curl http://127.0.0.1:8765/bots
```
使用显式 mineflayer/minethon 选项创建机器人：
```bash
curl -X POST http://127.0.0.1:8765/bots \
-H 'content-type: application/json' \
-d '{"name":"builder","host":"localhost","port":25565,"username":"builder"}'
```
使用 minethon 的事件简写创建机器人：
```bash
curl -X POST http://127.0.0.1:8765/bots \
-H 'content-type: application/json' \
-d '{"name":"swimmer","account":"g_swim"}'
```
选择活跃的机器人：
```bash
curl -X POST http://127.0.0.1:8765/active_bot \
-H 'content-type: application/json' \
-d '{"name":"builder"}'
```
检查一个机器人：
```bash
curl http://127.0.0.1:8765/bots/builder/health
```
关闭一个机器人。它仍然在列表中，标记为 `closed`，因此您可以仍然读取它为什么结束（`end_reason` / `kicked_reason`）：
```bash
curl -X DELETE http://127.0.0.1:8765/bots/builder
```
永久删除它（如果仍然连接，则先关闭）：
```bash
curl -X DELETE http://127.0.0.1:8765/bots/builder/record
```
一次性删除所有已关闭的机器人：
```bash
curl -X DELETE http://127.0.0.1:8765/bots/closed
```
在网页 UI 中，这些是 **关闭** 和 **删除** 按钮——一个活跃的机器人提供关闭，一个已关闭的机器人提供删除——以及一个 **删除 N 个已关闭** 按钮，仅在有已关闭的机器人时出现。已删除的名称可以立即重新使用。
## MCP 工具
生命周期检查工具：
- `list_bots`
- `check_bot_health(bot_name)`
- `get_active_bot`
- `set_active_bot(bot_name)`
寻路工具：
- `load_pathfinder(bot_name?)`
- `pathfinder_status(bot_name?)`
- `pathfinder_stop(bot_name?)`
- `pathfinder_clear_goal(bot_name?)`
- `pathfinder_goto_near(x, y, z, radius?, bot_name?)`
- `pathfinder_goto_block(x, y, z, bot_name?)`
- `pathfinder_goto_get_to_block(x, y, z, bot_name?)`
- `pathfinder_goto_xz(x, z, bot_name?)`
- `pathfinder_goto_near_xz(x, z, radius?, bot_name?)`
- `pathfinder_goto_y(y, bot_name?)`
- `pathfinder_set_goal_near(x, y, z, radius?, dynamic?, bot_name?)`
- `pathfinder_set_goal_block(x, y, z, dynamic?, bot_name?)`
Minecraft 操作工具接受一个可选的 `bot_name` 参数。如果省略，它使用 UI/控制 API 选择的活跃机器人或 `set_active_bot` 选择的机器人。
