使用说明
GB Studio/GBA Studio代理MCP服务器，用于创建GameBoy游戏。
提示为你的学生、孩子或你自己建立一个模板来扩展。
也适用于 GBA工作室 …我的GB Studio分支，涵盖了GBA
快速开始
-
安装:
npm install -g gbstudio-claude-mcp -
启动服务器:
gbstudio-claude-mcp -
连接克劳德桌面 （参见TUTORIAL.md）
-
提示克劳德：“审查和测试我的应用程序逻辑”
就是这样。克劳德将重新审视、扩展甚至生成一个可玩的游戏模板，你可以在GB Studio中与学生一起迭代。
Vibe编码、法学硕士和现代教育：可以给学生提供建设性的工具，而不仅仅是答案
在教孩子们编程、电子、3D打印和游戏开发14年后，我学到了这一点：最好的教育工具不仅仅是让事情变得更容易。他们使学习成为一项有益的活动。GB Studio就是其中之一。这是一个视觉游戏构建器，为您提供game Boy开发，将真正的创造力交给学生、教育工作者和业余爱好者，为物理硬件构建。当我们将GB Studio与关于如何使用大型语言模型（LLMs）的教育相结合时，我们为学生带来了一种积极的观点，即他们如何与之整合，而不是依赖它们作为拐杖。
什么是Vibe编码？
“Vibe编码”不仅仅是一个流行语。这是一种范式转变。它是剥离了语法把关的编程，创作者专注于流程、逻辑和想法，而不是记忆分号。Scratch、App Inventor和GB Studio等工具体现了这一理念：它们消除了障碍，重新围绕真正重要的事情进行编程：创造力和解决问题。
对于孩子们来说，氛围编码是他们成长的过程。它将让他们专注于编程的“为什么”和“如何”，而不会淹没在语法中。这不仅有帮助。对于学生来说，在系统、设计和逻辑方面进行思考很重要，但传统编码的陡峭学习曲线将他们拒之门外。
法学硕士在教育中的作用
像ChatGPT这样的大型语言模型在教育领域引发了激烈的争论，这是有充分理由的。如果不小心使用，它们就会变成作弊工具，用抄袭的心态取代思考。但与purpos一起使用，它们可以成为加速真正学习的脚手架。区别不在于工具。这就是我们如何运用它。
这正是我构建Clawdbot MCP服务器的原因。通过将LLM直接与GB Studio集成，用户和教师可以：
- 脚手架项目：从简单的提示生成启动器模板、资产和事件流。
- 自动化测试：运行冒烟测试以捕获错误并验证项目逻辑。
- 鼓励迭代：通过提供建议和例子帮助学生完善他们的项目。
游戏也可以从头开始构建，但它们不会是AAA级的，所以要衡量你的期望哈哈
乒乓球（Game Boy）
Create a Pong clone for the original Game Boy. Two paddles, a ball, and a score counter. The player controls the left paddle, the right paddle is AI-controlled. Use simple monochrome graphics and authentic GB sound effects. Generate all scenes, actors, and assets for a playable Pong game.
吃豆人（游戏男孩色）
Build a Pac-Man style maze game for Game Boy Color. The player navigates a maze, collects pellets, and avoids ghosts. Include at least one maze layout, four ghosts with basic AI, and colorful graphics. Generate all scenes, actors, and assets needed for a playable demo.
马里奥兄弟风格平台游戏机（Game Boy Color）
Design a Mario Bros inspired platformer for Game Boy Color. The player can run, jump, and stomp on enemies. Include three levels, power-ups, coins, and a flagpole at the end of each level. Use bright palettes and catchy background music. Generate all scenes, actors, and assets for a classic platformer experience.
太空射手（Game Boy）
Create a vertical scrolling space shooter for the original Game Boy. The player controls a spaceship, shoots enemies, and dodges obstacles. Include multiple enemy types, power-ups, and a boss fight. Use classic GB graphics and chiptune sound effects. Generate all scenes, actors, and assets for a playable shooter.
GB Studio的Claude MCP服务器
这是一个TypeScript服务器，用于使用模型上下文协议（MCP）操纵GB Studio项目。它为项目发现、验证和创建游戏资产提供了端点。
安装
使用npm全局安装：
npm install -g gbstudio-claude-mcp
本地环境设置（.env）
对于本地开发，请将API密钥和配置存储在 .env 项目根目录下的文件。这使秘密不受源代码控制，并与GitHub Actions中使用的模式相匹配。
- 创建
.env项目根目录中的文件：CLAUDE_API_KEY=your-claude-api-key-here # Add other keys as needed - 服务器将自动从以下位置加载变量
.env如果你使用[dotenv]。 .env默认情况下，文件是gitignore。
永远不要承诺你的 .env 文件到源代码管理。
用法
启动服务器：
gbstudio-claude-mcp
服务器运行在http://localhost:3000默认情况下。
配置您的MCP客户端（例如Claude Desktop）以连接到此服务器。有关完整的设置和故障排除，请参阅本文档末尾链接的教程。
端到端使用：Windows和Linux/macOS
请参阅 TUTORIAL.md 获取使用此服务器构建GB Studio游戏的完整分步指南，包括Windows和Linux/macOS的屏幕截图和故障排除提示。
MCP协议支持
此软件包支持 模型上下文协议（MCP）。您可以在MCP stdio模式下运行服务器，以便与Claude Desktop和其他MCP客户端一起使用：
npm run build:mcp
node build/mcp.js
MCP stdio服务器代理到上的本地REST APIhttp://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/coolermon/--用于集成测试的Real GB Studio项目
- gbstudio_api_endpoints.csv——所有计划终点的目录
本地开发
- 克隆存储库：
git clone https://github.com/eoinjordan/gb-studio-agent.git cd gb-studio-agent - 安装Node.js（推荐：v21.7.1或兼容）
- 安装依赖项：
npm install - 启动开发服务器：
npm run dev - 运行测试套件：
npm test
健康
GET /health--退货{ status: "ok" }进行健康检查。
API密钥
GET /claude-key--退货{ present: true }如果CLAUDE_API_KEY设置在环境中，否则{ 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, projectPath: string, target: "gb" | "gba", engine: "gb-studio" | "gba-studio", version: string | null }如果有效，或者如果无效或缺少必填字段，则显示400/404错误消息。 - 错误案例：
- 400如果
projectRoot丢失或.gbsproj无效/缺少必填字段 - 404如果
projectRoot不存在或否.gbsproj找到文件
- 400如果
- 主体：
构建GBA ROM
POST /gba/build--构建a.gbaROM使用当地GBA Studio结账。- 主体：
{ projectRoot: string, gbaStudioRoot?: string, output?: string, buildCli?: boolean, verbose?: boolean, extraArgs?: string[] } - 环境：
GBA_STUDIO_ROOT可以代替gbaStudioRoot. - 退货：
{ success: true, projectPath, gbaStudioRoot, output, stdout, stderr }关于成功，或{ success: false, error, stdout, stderr }. - MCP工具：
build_gba_rom为Claude/agent客户端暴露相同的参数。
- 主体：
创建场景
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带有错误消息。
- 主体：
创建Sprite
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带有错误消息。
- 主体：
克劳德密钥
POST /claude/key-在环境中设置Claude API密钥。- 主体：
{ key: string } - 退货：
{ success: true }如果成功，则发送400条错误消息。
- 主体：
构建一个端到端的游戏
要使用此MCP服务器和Claude构建GB Studio游戏，请执行以下操作：
- 发现项目： 使用
/find_project查找现有.gbsproj文件或从目录开始。 - 验证项目： 使用
/validate以确保项目的有效性。 - 获取库存： 使用
/inventory列出当前场景、演员、触发器、资源。 - 创建场景： 使用
/scene/create添加新场景。 - 创建演员： 使用
/actor/create为场景添加演员。 - 创建资产： 使用创建端点（当前为存根）添加精灵、背景等。
- 更新设置/元数据： 使用更新终结点配置项目。
- 构建/导出： 使用
/gba/build或MCPbuild_gba_rom编译GBA Studio项目.gba.
注意：所有端点现在都完全正常工作。
GBA Studio构建示例
{
"projectRoot": "C:/Users/Eoin/git/gba-studio/examples/gba-starter-project",
"gbaStudioRoot": "C:/Users/Eoin/git/gba-studio",
"output": "C:/tmp/gba-starter.gba",
"buildCli": true
}
示例提示
看 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
许可证
麻省理工学院
