MC Architect MCP

MC Architect MCP 是一套面向 AI/MCP 客户端的 Minecraft Java 单人世界建筑系统。它通过本地 Fabric Mod 读取和修改真实世界，再由 TypeScript MCP Bridge 提供地形扫描、蓝图施工、几何生成、路径验证、照明检查、截图验收和持久化撤销等高层工具。

English summary: a local Fabric mod and MCP server for inspecting, building, validating, photographing, and undoing changes in Minecraft Java single-player worlds.

功能概览

• 32 个 MCP 工具：覆盖世界控制、调查、施工、验证、摄影和恢复。
• 五种世界扫描：summary、heightmap、collision、lighting、full。
• 蓝图工作流：预览、原子应用、实际世界对比和显式空气校验。
• 参数化建筑：盒体、围墙、立柱、双坡屋顶、圆、弧墙、穹顶和螺旋楼梯。
• 区域编辑：复制、旋转、镜像、阵列和按方块状态替换。
• 可用性验收：基于真实碰撞形状检查普通玩家通行路线。
• 大型施工任务：分 Tick 执行，支持暂停、恢复、取消和重启恢复。
• 持久化撤销：事务日志写入存档，可按事务或连续项目分组撤销。
• 视觉验收：可恢复的旁观相机会话和无 HUD 世界截图。
• 本地通信：只监听回环地址，并使用随机 Bearer Token 鉴权。

系统架构

flowchart LR
    A["AI / MCP Client"] -->|"stdio MCP"| B["TypeScript MCP Bridge"]
    B -->|"HTTP + Bearer Token"| C["Fabric Client Mod"]
    C --> D["Minecraft Client Thread"]
    C --> E["Integrated Server Thread"]
    D --> F["UI / Camera / Screenshot"]
    E --> G["World Scan / Build / Validate"]
    E --> H["Transactions / Persistent Jobs"]

组件职责

• bridge/：注册 MCP 工具、验证参数、调用本地 HTTP API，并把高层几何压缩为 cuboid 蓝图。
• mod/：在 Minecraft 进程内执行真实世界读取和修改，处理线程切换、风险检查、事务、后台任务和截图。
• docs/protocol.md：Bridge 与 Mod 之间的本地 HTTP 协议。
• bridge/scripts/：故宫、午门、科研港、托卡马克、雕像和像素画等项目级示例。

环境要求

当前项目版本：0.5.0。

快速开始

1. 构建 Fabric Mod

cd mod
.\gradlew.bat build

构建产物：

mod/build/libs/mcarchitect-0.5.0.jar

把该 JAR 和对应版本的 Fabric API 放入 Minecraft 实例的 mods 目录。

2. 首次启动 Minecraft

启动带 Mod 的 Minecraft。首次运行会创建：

%APPDATA%\.minecraft\config\mcarchitect.json

示例：

{
  "port": 8765,
  "token": "RANDOM_LOCAL_TOKEN"
}

HTTP 服务只绑定 127.0.0.1。除健康检查外，所有请求都需要该 Token。

3. 构建 MCP Bridge

cd bridge
npm ci
npm run build
npm test

4. 配置 MCP 客户端

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["D:/path/to/mc-architect-mcp/bridge/dist/index.js"]
    }
  }
}

如果使用非默认 Minecraft 目录，设置 MCA_CONFIG 为完整配置文件路径：

$env:MCA_CONFIG = 'D:\MinecraftInstance\config\mcarchitect.json'

5. 连接世界

可以先手动进入单人世界，也可以从标题界面调用：

1. mc_health
2. mc_list_worlds
3. mc_open_world
4. 轮询 mc_ui_state，直到 worldOpen 为 true

完成后可调用 mc_disconnect 保存世界并返回标题界面。

推荐建筑流程

flowchart TD
    A["检查连接与世界状态"] --> B["summary / heightmap 选址"]
    B --> C["full 扫描局部现状"]
    C --> D["生成最终蓝图，包括必要的 minecraft:air"]
    D --> E["mc_preview_blueprint"]
    E --> F{"施工规模"}
    F -->|"较小"| G["mc_apply_blueprint"]
    F -->|"较大"| H["mc_start_build_job"]
    G --> I["mc_compare_blueprint"]
    H --> I
    I --> J["mc_validate_access"]
    J --> K["lighting 扫描"]
    K --> L["mc_capture_inspection"]
    L --> M["保留结果或 mc_undo"]

MCP 工具一览

世界和客户端

调查和验证

蓝图和区域编辑

参数化几何

相机和截图

任务和撤销

扫描模式

蓝图示例

以下蓝图构建一个 9×5×9 空心房间，并显式保留内部空气：

{
  "label": "stone room",
  "projectId": "demo-room",
  "operations": [
    {
      "from": { "x": 0, "y": 64, "z": 0 },
      "to": { "x": 8, "y": 68, "z": 8 },
      "block": "minecraft:stone_bricks"
    },
    {
      "from": { "x": 1, "y": 65, "z": 1 },
      "to": { "x": 7, "y": 67, "z": 7 },
      "block": "minecraft:air"
    }
  ]
}

建议先用同一组操作调用 mc_preview_blueprint，施工后再调用 mc_compare_blueprint。显式空气可以发现后续装饰误堵的通道、门洞和房间。

方块 ID 支持完整状态：

minecraft:oak_stairs[facing=north,half=bottom,shape=straight,waterlogged=false]

事务、项目和后台任务

原子施工

直接蓝图施工时，如果中途发生异常，Mod 会把已经修改的方块恢复到施工前状态。只有世界修改和撤销日志都成功持久化后，事务才算完成。

项目分组

给多个连续事务设置同一个 projectId，即可通过一次 mc_undo 撤销栈顶连续项目。事务严格遵守栈顺序，不会跨过其他项目撤销旧事务。

事务日志位于：

WORLD_SAVE/mcarchitect/transactions/*.json.gz

最近 100 个事务会随存档保留并跨游戏重启加载。

大型任务

后台任务每个服务器 Tick 最多修改 2,048 个方块。计划和进度保存在：

WORLD_SAVE/mcarchitect/jobs/

未完成任务在崩溃或重启后以暂停状态恢复，需要显式调用 resume。取消任务会根据检查点恢复已修改的方块；完成任务会转换成普通撤销事务。

限制和保护

其他行为：

• 目标区块必须已经加载。
• 施工不得与玩家碰撞体相交。
• 活动后台任务期间禁止直接施工和撤销。
• 当前版本不读写方块实体 NBT，也不会覆盖箱子、告示牌等方块实体。
• 通行验证是保守的方块单元搜索，不完整模拟冲刺跳跃、游泳、爬行及所有局部碰撞边界。
• 目前面向本地 Minecraft Java 单人世界和集成服务器。

安全模型

• HTTP 服务只监听 127.0.0.1。
• 默认端口为 8765。
• 首次启动生成 32 字节随机 Token。
• 除 /v1/health 外的端点均要求 Authorization: Bearer TOKEN。
• 世界操作调度到 Minecraft 集成服务器线程。
• UI、相机和截图操作调度到客户端线程。
• 预览会报告未加载区块、方块实体和玩家碰撞，而不修改世界。

完整协议见 docs/protocol.md。

开发与测试

Bridge

cd bridge
npm ci
npm run check
npm test

现有测试覆盖：

• 填充圆的压缩和中心点
• 弧形墙高度
• 空心穹顶边界
• 螺旋楼梯自动朝向
• 空心盒无重叠表面
• 单方块轴的边框盒退化处理

Mod

cd mod
.\gradlew.bat build

项目统计

• 正式运行源码：约 3,294 行
• 核心项目（含测试、协议和配置）：约 3,655 行
• 连同建筑示例脚本：约 7,982 行

统计不包含依赖、构建产物、Gradle 缓存、测试世界和截图。

示例脚本

bridge/scripts/ 中包含实际项目脚本，例如：

• 故宫、午门和庭院
• 太和门河道
• 天空科研港
• 托卡马克装置
• 芙宁娜雕像与像素画
• 扫描、验证和多视角截图脚本

这些脚本包含具体坐标和项目参数，运行前请先在副本世界中检查坐标，并使用预览工具核对改动范围。

License

MIT