关于 GB Studio MCP Server
GB Studio MCP Server 是面向 Game Boy 游戏开发的 MCP 服务，可通过 MCP 工具创建和修改 GB Studio 项目中的场景、角色、资源并进行校验。它也支持 GBA Studio 项目，适合教学场景和个人开发者。
主要功能
- 01创建场景、角色、背景、精灵等资源
- 02读取项目清单并列出场景与资源
- 03校验 .gbsproj 项目结构
- 04通过 REST API 与 MCP stdio 两种方式运行
- 05构建 GBA ROM（需本地 GBA Studio）
适用场景
- 01为学生生成可扩展的 Game Boy 游戏模板
- 02通过提示词批量生成场景与角色
- 03对 GB Studio 项目进行结构校验与冒烟测试
MCP 相关
该项目是 MCP 服务，将 GB Studio 项目的创建、查询、校验和构建操作以 MCP 工具形式提供给客户端，例如 Claude Desktop。
配置
本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。
工具
本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。
详细介绍
用于创建 GameBoy 游戏的 GB Studio / GBA Studio Agentic MCP 服务。
提示词：为你的学生、孩子或自己构建一个可扩展的模板。
也适用于 GBA STUDIO……这是我 fork 的 GB Studio 版本，支持 GBA。
快速开始
-
安装：
npm install -g gbstudio-claude-mcp -
启动服务：
gbstudio-claude-mcp -
连接 Claude Desktop（参见 TUTORIAL.md）
-
向 Claude 提示：“检查并测试我的应用程序逻辑”
就这么简单。Claude 会检查、扩展，甚至生成可游玩的游戏模板，供你与学生在 GB Studio 中持续迭代。
氛围编程、大模型与现代教育：给学生建设性的工具，而不只是答案
教孩子编程、电子、3D 打印和游戏开发 14 年后，我明白了：最好的教育工具不只是让事情变得更简单，还会让学习成为一种有收获的活动。GB Studio 就是这样的工具。它是一款可视化游戏构建器，让你进行 Game Boy 开发，让学生、教育工作者和爱好者能够充分发挥创意，为实体硬件制作游戏。当我们将 GB Studio 与大模型（LLM）的能力教育结合起来时，就能让学生积极看待如何将大模型融入其中，而不是把它们当作拐杖依赖。
什么是氛围编程？
“氛围编程”不只是一个流行词，而是一种范式转变。它让编程摆脱语法门槛，让创作者专注于流程、逻辑和创意，而不是死记分号。Scratch、App Inventor 和 GB Studio 等工具体现了这一理念：它们消除障碍，让编程重新聚焦于真正重要的事情：创造力和解决问题。
氛围编程是孩子们成长过程中熟悉的方式。它让他们专注于编程的“为什么”和“怎么做”，而不必淹没在语法中。这不仅有帮助，也很重要：学生需要思考系统、设计和逻辑，但传统编程陡峭的学习曲线却让他们望而却步。
大模型在教育中的作用
ChatGPT 等大模型在教育领域引发了激烈讨论，这有充分的理由。如果使用不当，它们就会沦为作弊工具，用复制粘贴的心态取代思考。但如果有目的地使用，它们就能成为促进真实学习的脚手架。区别不在于工具，而在于我们如何使用它。
这正是我构建 Clawdbot MCP 服务的原因。通过将大模型直接集成到 GB Studio 中，用户和教师可以：
- 为项目搭建脚手架：通过简单的提示词生成入门模板、素材和事件流程。
- 自动化测试：运行冒烟测试，发现 Bug 并验证项目逻辑。
- 鼓励迭代：通过提供建议和示例，帮助学生完善项目。
也可以从零开始制作游戏，但它们达不到 AAA 级别，所以请调整好预期，哈哈
Pong（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.
Pac-Man（Game Boy Color）
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.
Mario Bros 风格平台游戏（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 服务
这是一个使用 Model Context Protocol（MCP）操作 GB Studio 项目的 TypeScript 服务。它提供用于项目发现、验证和创建游戏素材的端点。
安装
使用 npm 全局安装：
npm install -g gbstudio-claude-mcp
本地环境设置（.env）
进行本地开发时，请在项目根目录的 .env 文件中保存 API 密钥和配置。这样可以避免将机密信息提交到源代码管理中，并与 GitHub Actions 使用的模式保持一致。
- 在项目根目录创建
.env文件：CLAUDE_API_KEY=your-claude-api-key-here # Add other keys as needed - 如果使用 [dotenv]，服务器会自动从
.env文件加载变量。 - 默认情况下，
.env文件会被 gitignore 忽略。
切勿将 .env 文件提交到源代码管理中。
使用方法
启动服务器：
gbstudio-claude-mcp
服务器默认运行在 http://localhost:3000。
配置 MCP 客户端（例如 Claude Desktop）以连接此服务器。如需完整的设置说明和故障排查方法，请参阅本文末尾链接的教程。
端到端使用：Windows 和 Linux/macOS
请参阅 TUTORIAL.md，其中提供了使用此服务器构建 GB Studio 游戏的完整分步指南，包括 Windows 和 Linux/macOS 系统的屏幕截图及故障排查提示。
MCP 协议支持
此软件包支持 Model Context Protocol（MCP）。你可以在 MCP stdio 模式下运行服务器，以便与 Claude Desktop 和其他 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.git cd gb-studio-agent - 安装 Node.js（推荐版本：v21.7.1 或兼容版本）
- 安装依赖：
npm install - 启动开发服务器：
npm run dev - 运行测试套件：
npm test
健康检查
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, projectPath: string, target: "gb" | "gba", engine: "gb-studio" | "gba-studio", version: string | null }；无效或缺少必需字段时，返回 400/404 和错误消息。 - 错误情况：
- 如果缺少
projectRoot，或.gbsproj无效/缺少必需字段，则返回 400 - 如果
projectRoot不存在，或未找到.gbsproj文件，则返回 404
- 如果缺少
- 请求体：
构建 GBA ROM
POST /gba/build— 使用本地 GBA Studio 检出目录构建.gbaROM。- 请求体：
{ 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 和错误消息。
- 请求体：
创建 Actor
POST /actor/create— 在指定场景中创建新的 Actor。- 请求体：
{ 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向场景添加演员。 - 创建资源： 使用创建端点（目前为存根）添加精灵、背景等。
- 更新设置/元数据： 使用更新端点配置项目。
- 构建/导出： 使用
/gba/build或 MCPbuild_gba_rom将 GB 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 发布文档。
贡献
- Fork 此仓库
- 创建功能分支
- 进行更改并添加测试
- 向 https://github.com/eoinjordan/gb-studio-agent 提交拉取请求
许可证
MIT
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。