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

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

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

新增工具

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

Related MCP server: minecraft-mcp

工具注解

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

构建与运行

npm install
npm run build

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

{
  "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 技能套件的执行底座。该套件包含网页体素设计器（mc-design）、秒落与表演模式建造（mc-build）、差量微调（mc-modify）三个技能，与本仓库的蓝图工具衔接为完整流水线：设计器产出蓝图，build-blueprint 落地，verify-region 验收，修改后差量回写。

许可证

本项目基于 Apache License 2.0 发行。

• 上游代码：Copyright 2025 Yuniko Software，Apache License 2.0，保留其全部版权与许可声明；

• 蓝图建造相关的修改与新增代码：Copyright 2026 ChenZeLongKnight，同样以 Apache License 2.0 发行。

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