Scan to join WeChat groupREADME
🚀 GB Studio Agentic MCP 服务器：用于创建 GameBoy 游戏
GB Studio Agentic MCP 服务器可用于创建 GameBoy 游戏，为学生、儿童或您自己提供一个可扩展的模板构建方案。
🚀 快速开始
- 安装：
npm install -g gbstudio-claude-mcp - 启动服务器：
gbstudio-claude-mcp - 连接 Claude 桌面端（详见
TUTORIAL.md） - 向 Claude 发送提示：“Review and test my application logic”
完成以上步骤后，Claude 会审查、扩展甚至生成一个可玩的游戏模板，您可以与学生在 GB Studio 中对其进行迭代开发。
✨ 主要特性
氛围编程、大语言模型与现代教育：为学生提供建设性工具，而非仅仅是答案
在教授儿童编程、电子学、3D 打印和游戏开发 14 年后，我深刻体会到：最好的教育工具不仅仅是让事情变得更容易，而是让学习成为一种有回报的活动。GB Studio 就是这样的工具之一，它是一个可视化游戏构建器，支持 Game Boy 开发，将真正的创造力交到学生、教育工作者和爱好者手中，让他们能够为实体硬件进行开发。当我们将 GB Studio 与大语言模型（LLMs）的教育相结合时，能让学生以积极的视角看待如何与它们集成，而不是将其作为拐杖依赖。
什么是氛围编程？
“氛围编程”不仅仅是一个流行语，它是一种范式转变。它摒弃了语法限制，让创作者专注于流程、逻辑和创意，而不是记忆分号。像 Scratch、App Inventor 和 GB Studio 这样的工具就体现了这一理念：它们消除了障碍，将编程的核心重新聚焦在真正重要的方面：创造力和解决问题的能力。
对于孩子们来说，氛围编程是他们成长过程中的一部分。它让他们能够专注于编程的“原因”和“方法”，而不会被语法淹没。这不仅有帮助，而且对于那些想要从系统、设计和逻辑角度思考，但被传统编程陡峭的学习曲线拒之门外的学生来说至关重要。
大语言模型在教育中的作用
像 ChatGPT 这样的大语言模型在教育领域引发了激烈的争论，这是有原因的。如果使用不当，它们会成为作弊工具，用复制粘贴的思维取代思考。但如果有目的地使用，它们可以成为加速真正学习的支架。区别不在于工具本身，而在于我们如何使用它。
构建 Clawdbot MCP 服务器的原因
通过将大语言模型直接与 GB Studio 集成，用户和教师可以：
- 搭建项目框架：根据简单的提示生成起始模板、资源和事件流程。
- 自动化测试：运行冒烟测试以捕获错误并验证项目逻辑。
- 鼓励迭代：通过提供建议和示例帮助学生完善他们的项目。
游戏也可以从头开始构建，但不要期望达到 AAA 级水平哦。
示例游戏提示
- Pong（Game Boy）
为原版 Game Boy 创建一个 Pong 克隆游戏。包含两个球拍、一个球和一个计分器。玩家控制左球拍，右球拍由 AI 控制。使用简单的单色图形和正宗的 GB 音效。生成所有场景、角色和资源，以创建一个可玩的 Pong 游戏。
- Pac - Man（Game Boy Color）
为 Game Boy Color 构建一个 Pac - Man 风格的迷宫游戏。玩家在迷宫中导航，收集小球并躲避幽灵。至少包含一个迷宫布局、四个具有基本 AI 的幽灵和彩色图形。生成所有场景、角色和资源，以创建一个可玩的演示版本。
- Mario Bros 风格的平台游戏（Game Boy Color）
为 Game Boy Color 设计一个受 Mario Bros 启发的平台游戏。玩家可以奔跑、跳跃并踩踏敌人。包含三个关卡、道具、金币和每个关卡末尾的旗杆。使用明亮的调色板和动听的背景音乐。生成所有场景、角色和资源，以提供经典的平台游戏体验。
- 太空射击游戏（Game Boy）
为原版 Game Boy 创建一个垂直滚动的太空射击游戏。玩家控制一艘宇宙飞船，射击敌人并躲避障碍物。包含多种敌人类型、道具和一场 boss 战。使用经典的 GB 图形和芯片音乐音效。生成所有场景、角色和资源，以创建一个可玩的射击游戏。
📦 安装指南
全局安装
使用 npm 进行全局安装：
npm install -g gbstudio-claude-mcp
本地环境设置（.env）
对于本地开发，将 API 密钥和配置信息存储在项目根目录的 .env 文件中。这样可以将机密信息排除在源代码控制之外，并且与 GitHub Actions 中使用的模式相匹配。
- 在项目根目录创建一个
.env文件：CLAUDE_API_KEY=your-claude-api-key-here # 根据需要添加其他密钥 - 如果使用 [dotenv]，服务器将自动从
.env文件中加载变量。 .env文件默认会被 git 忽略。
注意：永远不要将 .env 文件提交到源代码控制中。
💻 使用示例
启动服务器
gbstudio-claude-mcp
服务器默认运行在 http://localhost:3000。
配置 MCP 客户端
将您的 MCP 客户端（例如 Claude 桌面端）配置为连接到该服务器。有关完整的设置和故障排除信息，请参阅本文档末尾链接的教程。
端到端使用：Windows 和 Linux/macOS
请参阅 TUTORIAL.md，以获取使用此服务器构建 GB Studio 游戏的完整分步指南，包括屏幕截图和针对 Windows 和 Linux/macOS 的故障排除提示。
📚 详细文档
MCP 协议支持
此软件包支持 Model Context Protocol (MCP)。您可以以 MCP stdio 模式运行服务器，以便与 Claude 桌面端和其他 MCP 客户端一起使用：
npm run build:mcp
node build/mcp.js
MCP stdio 服务器会代理到本地 REST API http://localhost:3000，因此请先启动 REST 服务器。如果要使用不同的端口，请设置 GBSTUDIO_API_URL（完整 URL）或 GBSTUDIO_API_PORT（端口号）：
gbstudio-claude-mcp
或者在您的 MCP 客户端配置中添加以下内容：
{
"mcpServers": {
"gbstudio-mcp": {
"command": "node",
"args": ["/absolute/path/to/build/mcp.js"]
}
}
}
Clawdbot / Moltbot 兼容性
Clawdbot 和 Moltbot 通过与 AgentSkills 兼容的 SKILL.md 文件发现工具。此仓库在以下位置提供了一个：
skills/gbstudio-mcp/SKILL.md
兼容性取决于传输方式：
- 如果 Clawdbot 可以将 stdio MCP 服务器作为子进程运行，
node build/mcp.js将正常工作。 - 如果您的 Clawdbot 设置需要 HTTP + SSE MCP 服务器，则需要一个桥接器，因为此 MCP 服务器仅支持 stdio。
- 如果您仅运行 REST API，Clawdbot 将无法自动将工具发现为 MCP。
要在 Moltbot 中启用该技能，请添加以下条目：
{
"skills": {
"load": {
"extraDirs": [
"~/.clawdbot/skills"
],
"watch": true,
"watchDebounceMs": 250
},
"entries": {
"gbstudio-mcp": {
"enabled": true,
"env": {}
}
}
}
}
项目结构
src/index.ts— 主服务器和端点逻辑tests/— 所有端点的 Jest 测试套件tests/poachermon/— 用于集成测试的真实 GB Studio 项目gbstudio_api_endpoints.csv— 所有计划端点的目录
本地开发
- 克隆仓库：
git clone https://github.com/eoinjordan/gb-studio-agent cd gb-studio-agent - 安装 Node.js（推荐：v21.7.1 或兼容版本）
- 安装依赖：
npm install - 启动开发服务器：
npm run dev - 运行测试套件：
npm test
API 端点说明
健康检查
GET /health— 返回{ status: "ok" }用于健康检查。
Claude API 密钥检查
GET /claude-key— 如果环境中设置了CLAUDE_API_KEY，则返回{ present: true }，否则返回{ present: false }并返回 404 状态码。
查找项目
POST /find_project— 从给定目录开始查找第一个.gbsproj文件。- 请求体：
{ startPath: string } - 返回值：
{ projectPath: string }，如果未找到则返回 404 状态码。
- 请求体：
项目清单
POST /inventory— 列出 GB Studio 项目根目录下的场景、角色、触发器和资源。- 请求体：
{ projectRoot: string } - 返回值：
{ scenes, actors, triggers, assets }，出错时返回 404/400 状态码。
- 请求体：
项目验证
POST /validate— 验证 GB Studio 项目的结构（检查是否有有效的.gbsproj文件和必需字段）。- 请求体：
{ projectRoot: string } - 返回值：如果有效，返回
{ valid: true, message: string, scenes: number }；如果无效或缺少必需字段，返回 400/404 状态码并附带错误消息。 - 错误情况：
- 如果
projectRoot缺失或.gbsproj文件无效/缺少必需字段，返回 400 状态码。 - 如果
projectRoot不存在或未找到.gbsproj文件，返回 404 状态码。
- 如果
- 请求体：
创建场景
POST /scene/create— 向指定的 GB Studio 项目中添加一个新场景。- 请求体：
{ projectRoot: string, scene: object } - 返回值：成功时返回
{ success: true, scene }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建角色
POST /actor/create— 在指定场景中创建一个新角色。- 请求体：
{ projectRoot: string, sceneId: string, actor: object } - 返回值：成功时返回
{ success: true, actor }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建背景
POST /background/create— 在项目中创建一个新背景。- 请求体：
{ projectRoot: string, background: object } - 返回值：成功时返回
{ success: true, background }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建精灵
POST /sprite/create— 在项目中创建一个新精灵。- 请求体：
{ projectRoot: string, sprite: object } - 返回值：成功时返回
{ success: true, sprite }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建音乐
POST /music/create— 在项目中创建一个新音乐轨道。- 请求体：
{ projectRoot: string, music: object } - 返回值：成功时返回
{ success: true, music }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建音效
POST /sound/create— 在项目中创建一个新音效。- 请求体：
{ projectRoot: string, sound: object } - 返回值：成功时返回
{ success: true, sound }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建图块集
POST /tileset/create— 在项目中创建一个新图块集。- 请求体：
{ projectRoot: string, tileset: object } - 返回值：成功时返回
{ success: true, tileset }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建触发器
POST /trigger/create— 在指定场景中创建一个新触发器。- 请求体：
{ projectRoot: string, sceneId: string, trigger: object } - 返回值：成功时返回
{ success: true, trigger }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建变量
POST /variable/create— 在项目中创建一个新变量。- 请求体：
{ projectRoot: string, variable: object } - 返回值：成功时返回
{ success: true, variable }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建脚本
POST /script/create— 在项目中创建一个新脚本。- 请求体：
{ projectRoot: string, script: object } - 返回值：成功时返回
{ success: true, script }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建调色板
POST /palette/create— 在项目中创建一个新调色板。- 请求体：
{ projectRoot: string, palette: object } - 返回值：成功时返回
{ success: true, palette }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建字体
POST /font/create— 在项目中创建一个新字体。- 请求体：
{ projectRoot: string, font: object } - 返回值：成功时返回
{ success: true, font }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建表情
POST /emote/create— 在项目中创建一个新表情。- 请求体：
{ projectRoot: string, emote: object } - 返回值：成功时返回
{ success: true, emote }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建头像
POST /avatar/create— 在项目中创建一个新头像。- 请求体：
{ projectRoot: string, avatar: object } - 返回值：成功时返回
{ success: true, avatar }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建常量
POST /constant/create— 在项目中创建一个新常量。- 请求体：
{ projectRoot: string, constant: object } - 返回值：成功时返回
{ success: true, constant }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建预制角色
POST /prefab/actor/create— 在项目中创建一个新的角色预制体。- 请求体：
{ projectRoot: string, actorPrefab: object } - 返回值：成功时返回
{ success: true, actorPrefab }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建预制触发器
POST /prefab/trigger/create— 在项目中创建一个新的触发器预制体。- 请求体：
{ projectRoot: string, triggerPrefab: object } - 返回值：成功时返回
{ success: true, triggerPrefab }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
更新设置
POST /settings/update— 更新项目设置。- 请求体：
{ projectRoot: string, settings: object } - 返回值：成功时返回
{ success: true, settings }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
更新元数据
POST /metadata/update— 更新项目元数据。- 请求体：
{ projectRoot: string, metadata: object } - 返回值：成功时返回
{ success: true, metadata }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
创建引擎字段值
POST /engine-field-value/create— 在项目中创建一个新的引擎字段值。- 请求体：
{ projectRoot: string, engineFieldValue: object } - 返回值：成功时返回
{ success: true, engineFieldValue }，否则返回 400/404/500 状态码并附带错误消息。
- 请求体：
设置 Claude 密钥
POST /claude/key— 在环境中设置 Claude API 密钥。- 请求体：
{ key: string } - 返回值：成功时返回
{ success: true }，否则返回 400 状态码并附带错误消息。
- 请求体：
端到端构建游戏
要使用此 MCP 服务器和 Claude 构建 GB Studio 游戏，请按照以下步骤操作：
- 发现项目：使用
/find_project定位现有的.gbsproj文件或从某个目录开始查找。 - 验证项目：使用
/validate确保项目有效。 - 获取清单：使用
/inventory列出当前的场景、角色、触发器和资源。 - 创建场景：使用
/scene/create添加新场景。 - 创建角色：使用
/actor/create向场景中添加角色。 - 创建资源：使用创建端点（目前为存根）添加精灵、背景等。
- 更新设置/元数据：使用更新端点配置项目。
- 构建/导出：（未来功能）使用构建端点编译游戏。
注意：所有端点现在都已完全可用。
示例提示
有关不同游戏类型的详细示例提示和完整的端到端工作流程，请参阅 TUTORIAL.md。
测试覆盖率
所有端点都在 tests/ 目录中的 Jest 测试中得到覆盖。运行 npm test 以验证所有功能。测试使用真实的示例项目。
发布新版本
- 在
package.json中更新版本号。 - 构建项目：
npm run build - 登录 npm：
npm login --auth-type=legacy - 发布到 npm：
npm publish --access public
有关更多信息，请参阅 npm 发布文档。
贡献代码
- 分叉仓库
- 创建一个功能分支
- 进行更改并添加测试
- 提交拉取请求到 https://github.com/eoinjordan/gb-studio-agent
📄 许可证
本项目采用 MIT 许可证。