vibecraft

🚀 VibeCraft

基于人工智能的Minecraft世界编辑工具 — 通过与人工智能助手进行自然语言对话，打造宏伟的建筑作品。

🚀 快速开始

VibeCraft是一款强大的AI驱动的Minecraft世界编辑工具，借助自然语言与AI助手交互，即可轻松创建各种复杂建筑。以下将为你详细介绍其安装、使用等相关内容。

✨ 主要特性

• 🎯 46种MCP工具 – 全面覆盖WorldEdit功能（130+条命令），提供结构化工具和安全防护机制。
• ⚡ 快速执行 – 通过直接的RCON连接，实现实时命令执行和反馈。
• 🤖 原生AI设计 – 经过令牌优化的上下文文件、专业的代理提示和结构化工作流程。
• 🏗️ 智能建筑工具 – 支持家具摆放、建筑模式、参数化模板和地形生成。
• 🧠 空间感知 – 先进的系统通过快速、准确的扫描，防止常见的放置错误。
• 📚 知识库 – 包含1375种Minecraft物品、70+种模式、66种家具设计和比例参考。
• 🧰 上下文感知构建 – AI可利用精心整理的文档，在WorldEdit不适用时，使用方块调色板、家具布局和默认的/fill工作流程进行规划。
• 🛠️ 生产就绪 – 基于Docker的设置、自动化测试和全面的错误处理。
• 🔄 多客户端支持 – 支持Claude Code、Claude Desktop、Cursor和任何与MCP兼容的AI。

上下文库与默认命令

VibeCraft不仅仅是一个WorldEdit包装器。该仓库在context/目录中提供了完整的AI可读知识库，包括方块目录、建筑模式、家具布局、比例参考、地形配方等。AI代理在构建前会读取这些文件，从而理解材料、比例和风格规范。当任务需要使用原生的/fill或/setblock工作流程（如农田、红石细节、小型室内调整）时，额外的上下文信息可让AI将标准命令与WorldEdit结合使用，以获得精确的结果。

📦 安装指南

前提条件

• uv — 快速的Python包管理器 — 使用curl -LsSf https://astral.sh/uv/install.sh | sh 安装。
• Python 3.10+ — 下载。
• 带有Docker Compose的Docker Desktop — 下载。
• 与MCP兼容的AI客户端 — Claude Code、Claude Desktop或Cursor。

设置步骤

1. 克隆仓库并运行设置脚本：

git clone https://github.com/amenti-labs/vibecraft.git
cd vibecraft
./setup-all.sh

该脚本会自动完成以下操作：

• ✅ 使用uv（快速、现代的Python包管理器）安装依赖项。
• ✅ 在Docker中下载并启动PaperMC 1.21.3 + WorldEdit 7.3.17。
• ✅ 配置带有安全自动生成密码的RCON。
• ✅ 创建AI客户端配置文件。
• ✅ 测试所有连接。

2. 选择服务器模式： VibeCraft支持两种运行方式：

模式1：标准输入输出/命令模式（推荐单客户端使用）

适用场景：日常使用、简单设置、单AI客户端。 AI客户端在需要时将MCP服务器作为子进程启动。

配置方法：

# 复制系统提示
cp SYSTEM_PROMPT.md CLAUDE.md

{
  "mcpServers": {
    "vibecraft": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.vibecraft.server"],
      "cwd": "/absolute/path/to/vibecraft/mcp-server",
      "env": {
        "VIBECRAFT_RCON_HOST": "127.0.0.1",
        "VIBECRAFT_RCON_PORT": "25575",
        "VIBECRAFT_RCON_PASSWORD": "your_password_from_setup"
      }
    }
  }
}

# macOS
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
nano ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vibecraft": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.vibecraft.server"],
      "cwd": "/absolute/path/to/vibecraft/mcp-server",
      "env": {
        "VIBECRAFT_RCON_HOST": "127.0.0.1",
        "VIBECRAFT_RCON_PORT": "25575",
        "VIBECRAFT_RCON_PASSWORD": "your_password_from_setup"
      }
    }
  }
}

模式2：HTTP/SSE服务器模式（适用于调试和多客户端）

适用场景：调试、多AI客户端、查看实时日志。 将VibeCraft作为独立服务器运行，多个客户端可连接到该服务器。

启动服务器（从项目根目录）：

# 从vibecraft根目录
cd mcp-server
./start-vibecraft.sh

你将看到以下输出：

🎮 VibeCraft MCP Server - HTTP/SSE Mode
   All 45 tools available
============================================================
📡 RCON Host: 127.0.0.1:25575
✅ RCON connected
✅ WorldEdit 7.3.17 detected
🚀 Server running at http://127.0.0.1:8765/sse

配置方法：

{
  "mcpServers": {
    "vibecraft-sse": {
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}

SSE模式的优势：

• ✅ 实时查看所有RCON命令。
• ✅ 通过完整日志调试问题。
• ✅ 同时连接多个AI客户端。
• ✅ 重启客户端时无需重启服务器。

3. 获取RCON密码： 设置完成后，通过以下命令找到密码：

cat .rcon_password

将上述配置中的your_password_from_setup替换为该密码。

4. 完全重启AI客户端

5. 验证设置：

向你的AI询问："Can you connect to the Minecraft server?"

如果AI回复服务器信息，则表示你已准备好开始构建！🎉

💻 使用示例

构建建筑结构

用户："Build a 15x20 medieval castle with towers at each corner"
AI：*分析地形，创建基础，用石砖建造墙壁，
     添加角塔，创建城垛，安装橡木门*

室内设计

用户："Furnish the great hall with a dining area and throne"
AI：*扫描房间尺寸，放置带椅子的餐桌，
     添加吊灯，创建抬高的王座平台*

地形塑造

用户："Create rolling hills with oak trees around the castle"
AI：*分析区域，使用Perlin噪声生成地形，
     用草和泥土进行纹理处理，战略性地种植树木*

高级项目

用户："Build a village with 5 unique houses, a market, and a church"
AI：*使用建筑模板，定制每个建筑，
     铺设道路，添加照明，布置室内家具*

📚 详细文档

工作原理

MCP架构

VibeCraft实现了模型上下文协议（MCP），用于将AI助手连接到Minecraft：

1. MCP服务器（Python） — 将WorldEdit命令作为结构化工具公开。
2. RCON桥接器 — 直接连接到Minecraft服务器（无需模组）。
3. AI客户端 — 接收工具定义并通过自然语言执行命令。

构建过程

1. 用户请求 — 用户通过自然语言向AI发出指令。
2. AI规划 — AI分析请求，选择合适的工具。
3. 空间感知 — 扫描环境，防止放置错误。
4. 命令执行 — 通过RCON执行WorldEdit命令。
5. 验证 — 检查结果，必要时进行调整，并报告完成情况。

安全特性

• 命令清理 — 在执行前验证所有命令。
• 坐标边界 — 可选的构建区域限制。
• 异步预防 — 防止命令执行中的竞态条件。
• 撤销支持 — 支持完整的WorldEdit历史记录，可使用//undo和//redo。
• 空间扫描 — 强制扫描，防止家具/屋顶放置错误。

项目结构

vibecraft/
├── mcp-server/                # 核心MCP服务器
│   ├── src/vibecraft/
│   │   ├── server.py          # 主MCP服务器
│   │   ├── rcon_manager.py    # RCON连接处理程序
│   │   ├── sanitizer.py       # 命令验证
│   │   ├── tools/             # 工具处理程序（47个工具）
│   │   └── minecraft_items_loader.py  # 物品数据库
│   ├── tests/                 # 单元测试
│   ├── pyproject.toml         # 项目元数据和依赖项
│   └── uv.lock                # 锁定的依赖项（由uv管理）
├── context/                   # AI知识库
│   ├── minecraft_items_filtered.json  # 1375种物品
│   ├── minecraft_furniture_catalog.json  # 66种设计
│   ├── building_patterns.json  # 29种建筑模式
│   ├── terrain_patterns.json  # 41种地形模式
│   └── building_templates.json  # 5种参数化模板
├── AGENTS/                    # 专业AI提示
│   ├── minecraft-master-planner.md
│   ├── minecraft-shell-engineer.md
│   ├── minecraft-facade-architect.md
│   ├── minecraft-roofing-specialist.md
│   └── minecraft-interior-designer.md
├── SYSTEM_PROMPT.md           # 主要AI指令
├── docs/                      # 设置指南
├── scripts/                   # 辅助脚本
├── setup-all.sh               # 自动化设置
└── docker-compose.yml         # Minecraft服务器配置

# 使用过程中生成的文件
minecraft-data/                # Docker卷（世界、日志）
.rcon_password                 # 自动生成的RCON密码
claude-code-config.json        # AI客户端配置
CLAUDE.md                      # 系统提示（SYSTEM_PROMPT.md的副本）
mcp-server/.venv/              # Python虚拟环境（由uv管理）

示例

示例1：简单房屋

用户："Build a cozy cottage with stone walls and oak roof"

AI创建：

• 10×12方块的基础
• 带角柱的鹅卵石墙
• 带有适当悬挑的橡木楼梯屋顶
• 带框架的窗户、橡木门
• 室内地板和天花板

示例2：复杂城堡

用户："Build a medieval fortress with main keep, four corner towers, and courtyard"

AI创建：

• 地形分析和基础平整
• 30×30的主楼，多层结构
• 四个8×8的角塔，通过墙壁连接
• 带入口大门的庭院
• 带家具的室内房间
• 各处的照明

示例3：景观设计

用户："Create a Japanese garden with koi pond, stone paths, and cherry trees"

AI创建：

• 挖掘带有自然曲线的池塘
• 放置水和睡莲
• 用踏脚石铺设砾石路径
• 种植樱花树（粉色混凝土树叶）
• 添加石灯笼和竹子

更多示例

如需详细的对话式示例和工作流程，请查看examples/目录：

• 基础建筑 (examples/basic_building_example.txt) — 基础操作：使用//pos1和//pos2设置位置，创建墙壁/地板/屋顶，有效使用材料。
• 家具摆放 (examples/furniture_example.txt) — 室内设计工作流程：使用spatial_awareness_scan查找地板/天花板高度，浏览家具目录，正确放置家具（避免嵌入），创建完整的房间布局。
• 地形生成 (examples/terrain_example.txt) — 自然景观创建：生成山丘/山脉/山谷，应用逼真的纹理，进行平滑处理以获得自然外观。
• MCP配置 (examples/configs/) — 为Claude Code、Claude Desktop和其他MCP客户端提供的示例配置文件。

这些示例展示了典型的AI辅助构建工作流程，你可以参考或根据需求进行调整。

高级功能

空间感知

先进的空间分析可防止常见的放置错误：

• 🏠 地板检测 — 精确找到地板/天花板的Y坐标。
• 📏 间隙分析 — 检查六个方向的空间。
• 🧱 材料检测 — 识别建筑材料，以匹配风格。
• 🏗️ 结构分析 — 识别屋顶、墙壁、建筑与地形。

详细级别：

• low (2 - 3秒) — 快速扫描，用于快速检查。
• medium (4 - 5秒) — 推荐 — 速度和细节平衡。
• high (8 - 10秒) — 全面分析，包括风格检测。

建筑模板

5种参数化模板，可快速创建建筑：

• medieval_round_tower — 带螺旋楼梯的圆形塔楼。
• simple_cottage — 可定制的带烟囱房屋。
• guard_tower — 防御性瞭望塔。
• wizard_tower — 带有神秘元素的幻想塔楼。
• simple_barn — 质朴的木制谷仓。

可定制内容：高度、宽度、材料、屋顶风格、特征。

家具系统

66种家具设计，支持自动放置：

• 所有66种家具都有精确的方块坐标。
• 通过place_furniture工具实现自动放置。
• 空间感知可防止放置错误。
• 使用风格匹配的材料。

模式库

70+种模式，用于建筑元素：

• 屋顶 (29种) — 多种材料的山墙、斜屋顶、平板、平屋顶。
• 外立面 (11种) — 窗户、门、框架。
• 角落 (8种) — 柱子风格和结构元素。
• 细节 (22种) — 烟囱、装饰元素。

最佳实践提示

1. 详细描述需求

   • 推荐："Build a 20×30 Gothic cathedral with flying buttresses and rose window"
   • 不推荐："Build a church"

2. 让AI先进行扫描

   • AI会自动使用空间感知功能进行家具和屋顶放置。
   • 信任扫描过程，可防止99%的放置错误。

3. 使用建筑模板提高效率

   • 模板比从头构建快10倍。
   • 完全可定制（高度、材料、特征）。

4. 利用知识库

   • AI可访问1375种Minecraft物品（适用于Minecraft 1.21.3的方块和物品）。
   • 可询问："What oak blocks are available?" 以获取材料建议。

5. 分阶段构建

   • 大型项目分阶段进行效果更佳：外壳 → 外立面 → 屋顶 → 室内 → 景观。
   • AI可针对每个阶段使用专业代理。

6. 检查进度

   • 连接服务器：minecraft://localhost:25565
   • 实时观看建筑构建过程。

故障排除

"Minecraft服务器无法启动"

# 检查Docker状态
docker ps

# 查看日志
docker logs -f vibecraft-minecraft

# 重启服务器
docker restart vibecraft-minecraft

"RCON连接失败"

# 测试连接
docker exec vibecraft-minecraft rcon-cli list

# 验证密码
cat .rcon_password

# 检查MCP服务器配置
cat mcp-server/.env

"AI无法连接到VibeCraft"

1. 验证Minecraft服务器是否正在运行：docker ps
2. 检查MCP配置是否与claude-code-config.json匹配。
3. 完全重启AI客户端（而非仅重新加载）。
4. 检查系统提示是否已配置（Claude Code使用CLAUDE.md）。
5. 测试RCON：./scripts/test-connection.sh

"WorldEdit提示 'You need to provide a world'"

此错误通常在WorldEdit无法从RCON/控制台确定世界上下文时出现。

修复方法（设置脚本会自动完成）：

# 若需手动修复：
docker exec vibecraft-minecraft bash -c "sed -i 's/^    disallowed-blocks:.*/    disallowed-blocks: []/g' plugins/WorldEdit/config.yml"
docker restart vibecraft-minecraft

替代方法：确保在运行WorldEdit命令时有玩家在线。WorldEdit在有活跃玩家提供世界上下文时效果最佳。

"WorldEdit命令无效"

问题表现：命令执行但游戏中无反应。

解决方法：

• 验证WorldEdit插件是否已加载：检查服务器启动日志中是否有 "WorldEdit"。
• 确保你具有操作员权限：从服务器控制台运行op <username>。
• 使用RCON中的逗号分隔坐标：//pos1 100,64,100（而非//pos1 100 64 100）。
• 某些命令需要玩家上下文，请确保有玩家在线。

"服务器性能问题"

问题表现：服务器延迟或WorldEdit操作缓慢。

解决方法：

• 检查Java版本：java --version（必须为21+）。
• 确保有足够的内存：至少分配2GB。
• 查看服务器日志：docker logs vibecraft-minecraft | grep ERROR。
• 若操作失败，可在plugins/WorldEdit/config.yml中增加WorldEdit限制。

🔧 技术细节

| 属性 | 详情 | |------|------| | 包管理器 | uv（比pip快10 - 100倍） | | MCP服务器 | Python 3.10+，使用MCP SDK | | Minecraft服务器 | PaperMC 1.21.3（最新版本） | | WorldEdit | 版本7.3.17 | | RCON协议 | TCP连接到端口25575 | | 工具 | 46种MCP工具，覆盖130+条WorldEdit命令 | | 上下文窗口 | 针对Claude模型优化（200K令牌） | | 响应时间 | RCON命令执行时间小于100ms | | 安全性 | 命令清理、边界检查、异步预防 | | Docker | 容器化的Minecraft服务器，带有持久卷 |

MCP工具细分

• 核心：2种工具（RCON命令、服务器信息）
• WorldEdit：20个工具类别（选择、区域、生成等）
• 高级：13种工具（家具、模式、地形、空间分析）
• 验证：6种辅助工具（模式/掩码验证、物品搜索等）
• 模板：3种工具（建筑模板、 schematic、地形模式）

手动设置（高级）

自动化的setup-all.sh脚本可完成所有设置。若你希望手动设置（不使用Docker）或需要自定义安装，可在docs/archive/MANUAL_SETUP.md中找到存档的手动设置说明：

• 手动安装Java和PaperMC
• 从源代码设置WorldEdit插件
• 手动配置RCON
• 自定义MCP服务器配置

注意：大多数用户不建议手动设置。自动化设置更快、更安全，且经过更充分的测试。

🤝 贡献指南

我们欢迎贡献！请查看：

• CONTRIBUTING.md — 开发工作流程和标准
• CODE_OF_CONDUCT.md — 社区准则

贡献领域：

• 更多建筑模板
• 更多家具设计
• 地形生成配方
• 模式库扩展
• 错误修复和优化

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

🛠️ 支持与社区

若你需要帮助或有疑问，我们将竭诚为你提供支持：

• 📧 邮箱：evan@amentilabs.com — 提问、反馈或加入社区
• 🐛 报告问题：提交问题
• 💬 讨论交流：GitHub讨论区

我们期待你的反馈，助你打造出令人惊叹的作品！

🙏 致谢

• 创建者：Amenti Labs
• 技术支持：基于Anthropic的Claude AI，通过模型上下文协议（MCP）实现。
• 依赖项目：Minecraft、PaperMC、WorldEdit、Docker
• 项目仓库：https://github.com/amenti-labs/vibecraft

⭐ 星标历史

祝你构建愉快！ 🧱 若有需要，可查看上述支持与社区部分或发送邮件至evan@amentilabs.com获取帮助。