Loading... # VibeCraft AI 驱动 Minecraft 建造工具技术分析 # 一、项目概述 ## 1. 项目背景 VibeCraft 是一个创新的 AI 驱动 Minecraft 建造工具，允许用户通过自然语言对话与 Claude 交互，在 Minecraft 游戏中自动建造建筑结构。该项目由 Amenti Labs 开发，采用 MIT 许可证开源。 ### A. 核心理念 VibeCraft 的核心理念是将自然语言处理与游戏自动化结合，让玩家可以通过描述想要建造的内容，让 AI 代理自动在游戏中执行建造操作。这种交互方式极大地降低了 Minecraft 建造的门槛。 ### B. 技术特色 - 基于 MCP（Model Context Protocol）实现 AI 与游戏的桥接 - 支持 Fabric 客户端模组，兼容任意 Minecraft 服务器 - 提供 WorldEdit 集成，支持复杂的建筑操作 - 包含预配置的 Claude Agent 工作流和建造技能 ## 2. 项目统计 - Star 数：29 - Fork 数：2 - 主要语言：Python 81.4%，Java 15.3%，Shell 3.3% - 贡献者：2 人（Evan Reid、Kyryl Andreiev） - 最新提交：2026 年 1 月 12 日 # 二、系统架构 ## 1. 整体架构设计 VibeCraft 采用三层架构设计，通过 MCP 协议和 WebSocket 实现各组件之间的通信。 ```mermaid graph TB subgraph 用户层 A[Claude AI 聊天] end subgraph 协议层 B[MCP 协议] end subgraph 服务层 C[VibeCraft MCP Server] C1[WebSocket 桥接] end subgraph 客户端层 D[Minecraft 客户端模组] end subgraph 游戏层 E[Minecraft 服务器] E1[WorldEdit 插件] end A -->|MCP| B B --> C C -->|WebSocket| C1 C1 --> D D -->|玩家操作| E E --> E1 ```  ## 2. 组件详解 ### A. Claude Agent（代理层） Claude Agent 是整个系统的智能核心，负责： - 理解用户的自然语言建造请求 - 调用 MCP 工具执行建造命令 - 处理建造过程中的上下文和状态 - 管理建筑材料和模板 ### B. VibeCraft MCP Server（服务层） MCP Server 是 Claude 与 Minecraft 之间的桥梁，主要功能： - 实现 MCP 协议的服务端 - 提供 SSE（Server-Sent Events）和 Stdio 两种通信模式 - 通过 WebSocket 与客户端模组通信 - 管理 WorldEdit 和原生游戏命令 ### C. Fabric Client Mod（客户端层） 客户端模组是直接操作 Minecraft 的组件，负责： - 建立 WebSocket 服务器接收命令 - 解析并执行建造命令 - 支持认证和权限控制 - 提供游戏内命令接口 # 三、核心交互流程 ## 1. 建造流程时序图 ```mermaid sequenceDiagram participant U as 用户 participant C as Claude Agent participant M as MCP Server participant W as WebSocket 桥接 participant G as Minecraft 客户端 participant S as Minecraft 服务器 U->>C: 描述建造需求（如"建造石屋"） C->>M: 调用 MCP 工具 M->>W: 发送建造命令 W->>G: WebSocket 传输 G->>S: 执行游戏命令 S-->>G: 返回执行结果 G-->>W: 返回状态 W-->>M: 返回结果 M-->>C: 返回响应 C-->>U: 反馈建造进度 ```  ## 2. 命令执行链路 ``` 用户输入 ↓ Claude 理解意图 ↓ MCP 工具调用 ↓ WebSocket 消息 ↓ 客户端模组解析 ↓ 游戏命令执行（/fill, /setblock, WorldEdit） ↓ 结果反馈 ``` # 四、技术实现细节 ## 1. MCP Server 实现 ### A. 技术栈 - Python 3.10+ - uv 包管理器 - FastAPI/Starlette（HTTP 服务） - WebSocket（客户端通信） ### B. 核心工具 MCP Server 暴露的主要工具包括： | 工具名称 | 功能描述 | |---------|---------| | get_players | 获取在线玩家列表 | | get_position | 获取玩家位置 | | execute_command | 执行游戏命令 | | fill_blocks | 批量填充方块 | | set_block | 设置单个方块 | | select_region | 选择建筑区域 | ## 2. 客户端模组实现 ### A. 技术栈 - Java 17/21 - Fabric Mod Loader - Fabric API - Gradle（构建工具） ### B. 核心功能 客户端模组主要实现以下功能： - WebSocket 服务器（默认端口 8766） - 命令解析和执行 - 认证机制（Token 验证） - 游戏内命令接口 ## 3. WorldEdit 集成 WorldEdit 模式支持三种配置： | 模式 | 说明 | 适用场景 | |------|------|---------| | off | 禁用 WorldEdit，仅使用原生命令 | 无插件服务器 | | auto | 自动检测 WorldEdit，降级到原生命令 | 大多数服务器 | | force | 强制使用 WorldEdit，否则失败 | 确保插件环境 | # 五、项目结构 ## 1. 代码组织 ``` vibecraft/ ├── agent/ # Claude Agent 工作目录 │ ├── .claude/skills/ # 建造技能和工作流 │ ├── context/ # 材料指南和模板 │ ├── .mcp.json # MCP 服务器配置 │ └── CLAUDE.md # Agent 系统提示词 ├── client-mod/ # Fabric 客户端模组 │ ├── src/ # 模组源代码 │ ├── build.gradle # Gradle 构建配置 │ └── README.md # 模组文档 ├── mcp-server/ # MCP 服务器 │ ├── src/vibecraft/ # 服务器源代码 │ ├── server_http.py # SSE 模式入口 │ ├── start-vibecraft.sh # SSE 模式启动脚本 │ └── pyproject.toml # Python 依赖 └── docs/ # 项目文档 ``` ## 2. Agent 文件夹结构 Agent 文件夹是运行 Claude 的推荐位置，包含： - 预配置的 `.mcp.json` 配置文件 - 建造技能（Skills） - 材料指南和建筑模板 - 系统提示词（CLAUDE.md） # 六、使用流程 ## 1. 快速开始 ### A. 前置要求 - Python 3.10+ with uv - Java 21（Minecraft 1.21.x）或 Java 17（1.20.x） - jq 工具 - Minecraft Java Edition ### B. 安装步骤 1. 构建客户端模组 ```bash cd client-mod ./build.sh 1.21.1 # 替换为你的 Minecraft 版本 ``` 2. 使用 Prism Launcher 安装 - 创建实例 - 安装 Fabric 和 Fabric API - 添加 VibeCraft 模组 3. 启用 AI 控制 ``` /vibecraft allow ``` 4. 安装 Python 依赖 ```bash cd mcp-server uv sync ``` 5. 配置 Claude Code 在 `~/.claude.json` 中添加： ```json { "projects": { "/path/to/vibecraft/agent": { "mcpServers": { "vibecraft": { "type": "sse", "url": "http://127.0.0.1:8765/sse" } } } } } ``` 6. 启动服务 ```bash cd mcp-server ./start-vibecraft.sh cd agent claude ``` ## 2. 游戏内命令 | 命令 | 功能 | |------|------| | /vibecraft status | 显示桥接状态 | | /vibecraft allow | 启用 AI 控制 | | /vibecraft deny | 禁用 AI 控制 | | /vibecraft token <value> | 设置认证令牌 | | /vibecraft port <number> | 更改 WebSocket 端口 | | /vibecraft restart | 重启桥接 | # 七、技术亮点 ## 1. MCP 协议应用 VibeCraft 是 MCP 协议在实际应用中的优秀案例： - 标准化的 AI 工具调用接口 - 支持双向通信（SSE 模式） - 可扩展的工具定义 ## 2. 双模式通信 - SSE 模式：适用于实时交互 - Stdio 模式：适用于集成场景 ## 3. 客户端模组设计 - 不受服务器类型限制 - 支持任意 Minecraft 服务器 - 保持游戏兼容性 ## 4. Agent 工作流 - 预配置的建造技能 - 材料指南和模板系统 - 上下文感知的建造决策 # 八、应用场景 ## 1. 创意建造 - 快速原型设计 - 大规模建筑群生成 - 复杂结构自动化建造 ## 2. 教育场景 - 建筑教学辅助 - 编程逻辑可视化 - AI 交互演示 ## 3. 服务器管理 - 自动化基础设施建造 - 批量建筑生成 - 维护和修复工作 # 九、技术挑战与限制 ## 1. 已知限制 - 需要 Minecraft 客户端运行 - 依赖网络连接延迟 - 部分服务器可能限制模组 ## 2. 故障排查 | 问题 | 解决方案 | |------|---------| | Player not found | 使用精确的玩家名称（区分大小写） | | Command dispatched 无响应 | 更新到最新模组版本 | | Unknown block type | 使用当前 Minecraft 版本支持的方块 | | WorldEdit 命令失败 | 设置 VIBECRAFT_WORLDEDIT_MODE=off | | 连接失败 | 检查端口配置（默认 8766） | # 十、未来发展方向 ## 1. 功能扩展 - 支持更多建筑模板 - 集成更多游戏内插件 - 多玩家协作建造 ## 2. 性能优化 - 命令批处理优化 - 网络通信优化 - 大规模建造性能提升 ## 3. 生态建设 - 社区模板分享 - 建造技能扩展 - 第三方工具集成 *** ## 参考资料 1. [VibeCraft GitHub 仓库](https://github.com/amenti-labs/vibecraft) 最后修改：2026 年 01 月 18 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏