# minecraft-mcp-server（蓝图建造增强版）

基于 [yuniko-software/minecraft-mcp-server](https://github.com/yuniko-software/minecraft-mcp-server)（Apache License 2.0）改造的 Minecraft MCP 服务器，在保留原全部能力的基础上，新增一套蓝图设计、建造与验收工具，构成完整的建筑自动化流水线。

原服务器支持通过 MCP 协议控制 Minecraft 角色移动、飞行、管理物品、放置与挖掘方块。本仓库在此基础上新增了蓝图引擎，使 AI 智能体能够从建模文件或体素数据直接建造整栋建筑，并对建造结果执行逐方块验收。

## 新增工具

| 工具 | 功能 |
|------|------|
| `list-schematics` | 列出蓝图库中的全部蓝图文件 |
| `schematic-info` | 解析蓝图文件的尺寸、方块统计与元数据 |
| `litematic-convert` | 将 `.schem` / `.schematic` / `.litematic` / `.nbt` 蓝图转换为标准 JSON（兼容新旧两种 litematic 调色板格式） |
| `build-blueprint` | 将蓝图（文件或内联体素数组）按物理依赖排序、分组压缩为 /fill 指令流并执行建造 |
| `verify-region` | 对指定区域逐方块回读世界数据，与蓝图比对并输出差异报告（用于建造验收） |

配套的蓝图格式：`{ width, height, length, blocks: [{ x, y, z, block: "minecraft:..." }] }`，方块名可携带完整状态（如 `spruce_stairs[facing=south]`）。

## 工具注解

全部工具均按 MCP 规范声明 `readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint` 四项行为注解，取值与各工具的实际行为一致：只读取状态而不改动世界的工具标为只读；会移除或替换既有内容（挖掉方块、放置方块、批量建造、写盘转换）的工具标为破坏性；重复调用同样参数不再产生额外影响的工具标为幂等；需要与实时游戏世界交互的工具标为开放世界。客户端可据此在调用前向用户给出提示，部分工具目录也会据此决定是否收录。

## 构建与运行

```bash
npm install
npm run build
```

MCP 客户端配置示例（以 Claude Desktop 为例）：

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "<本仓库路径>/dist/main.js",
        "--host", "localhost",
        "--port", "25565",
        "--username", "XiaoBuddy"
      ]
    }
  }
}
```

前置条件与上游一致：Node.js（>= 20.10.0）、运行中的 Minecraft Java 版、单人世界对局域网开放。版本支持情况见上游说明（上游标注支持 1.21.1；本仓库的蓝图工具在 1.21.1 完整验证）。

## 与一套 AI 建筑技能的配合

本引擎是 [Ai-build-for-minecraft](https://github.com/ChenZeLongKnight/Ai-build-for-minecraft) 技能套件的执行底座。该套件包含网页体素设计器（mc-design）、秒落与表演模式建造（mc-build）、差量微调（mc-modify）三个技能，与本仓库的蓝图工具衔接为完整流水线：设计器产出蓝图，build-blueprint 落地，verify-region 验收，修改后差量回写。

## 许可证

本项目基于 Apache License 2.0 发行。

- 上游代码：Copyright 2025 [Yuniko Software](https://github.com/yuniko-software)，Apache License 2.0，保留其全部版权与许可声明；
- 蓝图建造相关的修改与新增代码：Copyright 2026 ChenZeLongKnight，同样以 Apache License 2.0 发行。

依据 Apache License 2.0 第 4 条，修改过的文件均在文件头注明修改内容。