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限制。

🔧 技術細節

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獲取幫助。