内容
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/status-alpha-orange?style=flat-square">
<img alt="status: alpha" src="https://img.shields.io/badge/status-alpha-orange?style=flat-square">
</picture>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/rust-nightly-blue?style=flat-square">
<img alt="rust: nightly" src="https://img.shields.io/badge/rust-nightly-blue?style=flat-square">
</picture>
<br>
# minecraft-mcp-rs
**一款通过模型上下文协议（MCP）控制的Minecraft机器人。**
本项目将LLM客户端（如Claude Desktop、Cursor等）桥接到真实的Minecraft游戏世界。一个由[azalea]库驱动的Rust机器人会连接到你的Minecraft服务器，并将其移动、挖掘、建造、背包管理、战斗和聊天等能力作为MCP工具暴露出来，支持**stdio**或**远程HTTP**（仅限本地回环，受Bearer Token保护）两种传输方式。
本项目针对**Minecraft Java Edition 1.21.11**（通过azalea 0.15.1实现）。
[azalea]: https://github.com/azalea-rs/azalea
## 功能特点
- **30余个MCP工具**，分为7个领域，外加统一的`act`工具。
提供**30余个MCP工具**，分为7个领域，外加统一的`act`工具。
- **双语UI（英文 / 简体中文）** — 可在运行时通过“设置”面板切换语言；系统会自动检测CJK字体，开箱即用即可正常显示中文。
**双语UI（英文 / 简体中文）** —— 可在运行时通过“设置”面板切换语言；系统会自动检测CJK字体，开箱即用即可正常显示中文。
- **实时世界状态** — 机器人会定期将周围环境快照保存到线程安全的`SharedState`，所有工具均可读取。
**实时世界状态** —— 机器人会定期将周围环境快照保存到线程安全的`SharedState`，所有工具均可读取。
- **远程MCP HTTP服务** — 仅限本地回环（`127.0.0.1`），受Bearer Token保护；stdio / HTTP传输模式可在UI中选择。
**远程MCP HTTP服务** —— 仅限本地回环（`127.0.0.1`），受Bearer Token保护；stdio / HTTP传输模式可在UI中选择。
- **多模态模型的AI视觉** — `get_world_view`可渲染附近方块的俯视PNG图并以base64返回。
**多模态模型的AI视觉** —— `get_world_view`可渲染附近方块的俯视PNG图并以base64返回。
- **智能移动与飞行** — `smart_move`可自动跳过1格宽的缺口，遇到更大障碍会停下；`fly_to`可在创造模式下飞向目标。
**智能移动与飞行** —— `smart_move`可自动跳过1格宽的缺口，遇到更大障碍会停下；`fly_to`可在创造模式下飞向目标。
- **桌面UI**（egui/eframe）—— 状态面板实时显示统计信息，设置面板可配置连接、机器人参数和MCP传输方式，另有MCP配置面板可生成可复制到Claude Desktop / Cursor的JSON配置。
**桌面UI**（egui/eframe）—— 状态面板实时显示统计信息，设置面板可配置连接、机器人参数和MCP传输方式，另有MCP配置面板可生成可复制到Claude Desktop / Cursor的JSON配置。
- **自动重连** —— 断开连接时采用指数退避；每次重连都会通过`ReceiverLease`干净地中止并重新启动命令执行器。
**自动重连** —— 断开连接时采用指数退避；每次重连都会通过`ReceiverLease`干净地中止并重新启动命令执行器。
- **复合操作** —— 基于原始命令构建的更高层状态机（例如“挖掘并拾取”流水线）。
**复合操作** —— 基于原始命令构建的更高层状态机（例如“挖掘并拾取”流水线）。
- **设计上线程安全** —— 通过`ArcSwap`实现无锁快照，原子标志控制状态，`RwLock`保护配置，`Mutex`保护容器句柄。
**设计上线程安全** —— 通过`ArcSwap`实现无锁快照，原子标志控制状态，`RwLock`保护配置，`Mutex`保护容器句柄。
- **脏区快照更新** —— 仅重算两次轮询之间发生变化的方块 / 区块。
**脏区快照更新** —— 仅重算两次轮询之间发生变化的方块 / 区块。
- **可配置的命令超时** —— `command_timeout_secs`由命令通道真正遵守，而不仅是UI字段。
**可配置的命令超时** —— `command_timeout_secs`由命令通道真正遵守，而不仅是UI字段。
- **诚实的错误报告** —— `BotError::InvalidParams`会映射为MCP的`INVALID_PARAMS`；无法破坏的方块返回`MiningInterrupted`而非panic；`set_game_mode`会提示需要OP权限。
**诚实的错误报告** —— `BotError::InvalidParams`会映射为MCP的`INVALID_PARAMS`；无法破坏的方块返回`MiningInterrupted`而非panic；`set_game_mode`会提示需要OP权限。
## 工具类别
| 类别 / 类别 | 工具 / 工具 |
|-----------------|--------------|
| **查询 / 查询** | `get_self_info`, `get_inventory`, `get_nearby_blocks`, `get_nearby_entities`, `get_chunk_summary`, `is_connected`, `get_chat_history`, `get_server_info`, `get_world_view` |
| **移动 / 移动** | `move_to`, `walk_direction`, `jump`, `teleport`, `smart_move`, `fly_to` |
| **方块 / 方块** | `break_block`, `place_block`, `use_item_on_block` |
| **物品 / 物品** | `drop_item`, `equip_tool`, `switch_hotbar_slot`, `use_item`, `collect_items` |
| **容器 / 容器** | `open_container`, `take_from_container`, `put_into_container`, `close_container` |
| **战斗 / 战斗** | `attack_entity`, `shield_block` |
| **聊天 / 聊天** | `send_chat`, `execute_command`, `set_game_mode` |
| **统一 / 统一** | `act` — 一个统一入口，能够根据传入参数执行移动、智能移动、飞行、挖掘、攻击或拾取物品，并返回环境快照 |
上述工具按功能领域分类；`act`是一个统一入口，能够根据传入参数执行移动、智能移动、飞行、挖掘、攻击或拾取物品，并返回环境快照。
## 文档
使用VitePress构建的双语（英文 / 简体中文）文档站点可在仓库启用GitHub Pages后访问：`https://<user>.github.io/minecraft-mcp-rs/`。
## 语言切换
桌面UI支持**英文**和**简体中文**。在“设置”面板的“语言”下拉框中切换，下一帧即生效，无需重连。启动时会自动探测系统默认中文字体（Windows `msyh.ttc`、macOS `PingFang.ttc`、Linux Noto / 文泉驿），无需手动安装字体即可正常显示中文。
## 快速开始
### 前置条件
- [Rust nightly](https://rustup.rs/)（`rust-toolchain.toml`已固定，edition 2024；azalea 0.15.1要求nightly）
- 一个Minecraft Java Edition 1.21.11服务器（本地或远程）
- 一个MCP客户端（Claude Desktop、Cursor或任何兼容MCP的LLM宿主）
### 构建
```bash
cargo build
```
### 运行
```bash
cargo run
```
这会同时启动MCP服务器和egui桌面UI。在“设置”面板中选择MCP传输方式：
- **stdio** —— MCP服务器监听标准输入 / 输出（Claude Desktop / Cursor的默认方式）。
- **HTTP** —— MCP服务器仅绑定到`127.0.0.1`；可在UI中设置端口与Bearer Token（每次`AppConfig::default()`时随机生成UUID v4，可在设置面板中覆盖）。MCP配置面板会生成对应的JSON配置，可复制到你的MCP客户端中。
默认情况下，机器人会尝试以`AI_Bot`身份连接到`127.0.0.1:25565`。可以在UI面板或启动前通过环境变量调整设置（详见Configuration章节）。
### 测试
```bash
cargo test # 所有测试
cargo test --lib # 单元测试
cargo test --test integration # 基于模拟的集成测试
cargo test --test proptest # 基于属性的测试
```
### 依赖补丁
仓库包括两个小的、有跟踪的补丁位于`patches/`下，以解决上游依赖冲突以实现干净构建：
- `patches/rmcp` —— 基于`rmcp 1.8.0`（Apache-2.0）。将可选的`rand`依赖从`0.10`降级到`0.9`，以避免与`azalea-crypto`固定的`rand_core = "=0.10.0-rc-5"`冲突。
- `patches/rsa` —— 基于`rsa 0.10.0-rc.13`（MIT OR Apache-2.0）。调整`src/encoding.rs`使用元组变体`pkcs8::Error::KeyMalformed(...)`，`pkcs8 0.11.0`需要此变体。
这些目录已提交到git，并由`Cargo.toml`中的`[patch.crates-io]`节引用。请勿将它们加入`.gitignore`；CI和其他克隆仓库需要这些文件在本地才能正确解析依赖。
## 持续集成
仓库提供两套并行的CI/CD配置：
- **GitHub Actions**（`.github/workflows/`）—— `build.yml`、`release.yml`、`deploy-docs.yml`。这是主流水线。
- **AtomGit Action**（`.gitcode/workflows/`）—— 镜像上述三个工作流，供AtomGit托管镜像使用：`build.yml`（dev二进制矩阵构建 + lint/test）、`release.yml`（`v*`标签触发的release构建与打包）和`deploy-docs.yml`（VitePress站点构建，仅上传制品）。
## 配置
所有设置都有合理的默认值，可以在运行时通过egui设置面板更改（完全可编辑——字符串使用文本输入框，数值字段使用DragValue滑块）。编辑完成后点击**Connect**，设置即会生效，并在专用后台线程上启动机器人连接。
| 字段 / 字段 | 默认值 / 默认值 | 描述 / 说明 |
|--------------|------------------|--------------------|
| `mc_address` | `127.0.0.1` | Minecraft服务器地址 / Minecraft 服务器地址 |
| `mc_port` | `25565` | Minecraft服务器端口 / Minecraft 服务器端口 |
| `ai_username` | `AI_Bot` | 机器人游戏内用户名 / 机器人游戏内用户名 |
| `mcp_transport` | `Http` | MCP传输方式：`Stdio`或`Http` / MCP传输方式：`Stdio`或`Http` |
| `mcp_address` | `127.0.0.1` | MCP HTTP绑定地址（仅本地回环） / MCP HTTP 绑定地址（仅本地回环） |
| `mcp_port` | `3000` | MCP HTTP端口 / MCP HTTP 端口 |
| `mcp_token` | 随机UUID v4 | HTTP传输的Bearer Token（每次`AppConfig::default()`时随机生成） / HTTP传输的Bearer Token（每次`AppConfig::default()`时随机生成） |
| `language` | `En` | UI语言：`En`或`ZhCn` / UI语言：`En`或`ZhCn` |
| `chunk_scan_radius` | `8` | 扫描区块半径（1–16） / 扫描区块半径（1–16） |
| `block_perception_radius` | `32` | 方块感知范围（8–64） / 方块感知范围（8–64） |
| `snapshot_interval_ms` | `500` | 世界快照间隔（毫秒） / 世界快照间隔（毫秒） |
| `reconnect_initial_delay_ms` | `5000` | 初始重连退避（毫秒） / 初始重连退避（毫秒） |
| `reconnect_max_delay_ms` | `60000` | 最大重连退避（毫秒） / 最大重连退避（毫秒） |
| `command_timeout_secs` | `30` | 机器人命令超时（秒） / 机器人命令超时（秒） |
数值型字段均可在UI中通过滑块或键盘输入调整；修改后需点击**Connect**才会应用到机器人连接。
## 架构
```
┼────────────────┐
│ egui 桌面UI │
│ ┌──────────┐ ┌──────────┐ │
│ │ 状态 │ │ 设置 │ │
│ └────┬─────┘ └────┬─────┘ │
│ └──────┬───────┘ │
│ │ 读取/写入 │
│ ▼ │
│ ┌──────────┐ │
│ │SharedState│ （ArcSwap + RwLock + Atomics) │
│ └────┬─────┘ │
└────────────┼─────────────────────────────────────┐
│ 读取
┌────────────┼─────────────────────────────────────┐
│ MCP Server (rmcp, stdio or HTTP transport) │
│ ┌──────────┐ ┌───────────────────────────┐ │
│ │ Router │──▶│ tools_query/movement/... │ │
│ └────┬─────┘ └───────────────────────────┘ │
│ │ sends BotCommand (tokio mpsc + oneshot) │
│ ▼ │
│ ┌──────────┐ │
│ │ BotEngine│ (azalea client + bevy_ecs) │
│ └──────────┘ │
└──────────────────────────────────────────────────┘
```
机器人运行在独立的操作系统后台线程上，拥有自己的tokio运行时；UI运行在主线程。两者通过`Arc<SharedState>`（无锁读取）和`BotCommand`通道（tokio mpsc + oneshot响应）进行通信。
## 项目结构
```
src/
types.rs — 共享数据类型（BlockPos, BotCommand, ActAction, …）
error.rs — BotError 枚举（AI 代理的可行变体）
config.rs — AppConfig + RunStats（原子计数器）
state.rs — SharedState 线程安全中心
block_data.rs — 方块/工具/材料表格
mining_calc.rs — 采矿时间公式
command_validate.rs — 坐标验证
snapshot.rs — 世界快照 + 脏区跟踪
tool_select.rs — 最佳工具选择
compound_ops.rs — 多步骤操作状态机
channel.rs — mpsc/oneshot 命令通道
logging.rs — tracing-subscriber（仅限 stderr）
bot/ — 机器人生命周期、事件、命令、操作
mcp/ — MCP 服务器 + 8 个工具模块（包括 act, render）
ui/ — egui 应用壳、设置、状态、mcp_config
tests/
integration.rs — 基于模拟的端到端测试
proptest.rs — 基于属性的测试
```
代码按“类型 → 逻辑 → 状态 → 机器人 → MCP → UI”分层，全部位于同一个 crate 中。`bot/`负责机器人生命周期与事件处理，`mcp/`暴露 MCP 工具，`ui/` 提供 egui 桌面界面。
## 开发
### 日志
所有日志输出仅写入 **stderr** —— stdout 保留给 MCP JSON-RPC 传输使用。默认过滤器：`minecraft_mcp_rs=debug, azalea=warn`。
### 测试约定
- 单元测试位于每个源文件底部的 `#[cfg(test)] mod tests` 中。
单元测试位于每个源文件底部的 `#[cfg(test)] mod tests` 中。
- `tests/integration.rs` 中的集成测试使用模拟（无需真实 Minecraft 服务器）。
`tests/integration.rs` 中的集成测试使用模拟（无需真实 Minecraft 服务器）。
- `tests/proptest.rs` 中的属性测试使用 `proptest` crate。
`tests/proptest.rs` 中的属性测试使用 `proptest` crate。
### 开发钩子
目前为空占位实现。未来项目将提供pre-commit / commit-msg钩子（计划：`cargo fmt --check`、`cargo clippy --all-targets -- -D warnings`、`cargo test --locked`和Conventional Commits检查），您可以选择加入：
```bash
bash scripts/install-hooks.sh
```
在此之前，该脚本不会触及`git config core.hooksPath`——运行`cargo build`后运行`git config --get core.hooksPath`应报错，确认没有配置全局副作用。
## 许可证
许可证：MIT
