🚀 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 级水平哦。
示例游戏提示
为原版 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 创建一个垂直滚动的太空射击游戏。玩家控制一艘宇宙飞船，射击敌人并躲避障碍物。包含多种敌人类型、道具和一场 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 许可证。
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
