Gb Studio Agent

GB Studio代理MCP服务器，用于创建GameBoy游戏。

提示为你的学生、孩子或你自己建立一个模板来扩展。

快速开始

1. 安装: npm install -g gbstudio-claude-mcp

1. 启动服务器: gbstudio-claude-mcp

1. 连接克劳德桌面 （参见TUTORIAL.md）

1. 提示克劳德：“审查和测试我的应用程序逻辑”

就是这样。克劳德将重新审视、扩展甚至生成一个可玩的游戏模板，你可以在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中使用的模式相匹配。

1. 创建一个 .env 项目根目录中的文件：

   CLAUDE_API_KEY=your-claude-api-key-here
   # Add other keys as needed

1. 服务器将自动从以下位置加载变量 .env 如果你使用\[dotenv\]。
2. .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——所有计划终点的目录

本地开发

1. 克隆存储库：

   git clone https://github.com/eoinjordan/gb-studio-agent.git
   cd gb-studio-agent

1. 安装Node.js（推荐：v21.7.1或兼容）
2. 安装依赖项：

   npm install

1. 启动开发服务器：

   npm run dev

1. 运行测试套件：

   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 } 如果有效，或者如果无效或缺少必填字段，则显示400/404错误消息。 - 错误案例： - 400如果 projectRoot 丢失或 .gbsproj 无效/缺少必填字段 - 404如果 projectRoot 不存在或否 .gbsproj 找到文件

创建场景

• 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游戏，请执行以下操作：

1. 发现项目： 使用 /find_project 查找现有 .gbsproj 文件或从目录开始。
2. 验证项目： 使用 /validate 以确保项目的有效性。
3. 获取库存： 使用 /inventory 列出当前场景、演员、触发器、资源。
4. 创建场景： 使用 /scene/create 添加新场景。
5. 创建演员： 使用 /actor/create 为场景添加演员。
6. 创建资产： 使用创建端点（当前为存根）添加精灵、背景等。
7. 更新设置/元数据： 使用更新终结点配置项目。
8. 构建/导出： （未来）使用构建端点编译游戏。

注意：所有端点现在都完全正常工作。

示例提示

看 TUTORIAL.md 获取不同游戏类型的详细示例提示和完整的端到端工作流程。

测试覆盖率

所有端点都由tests/目录中的Jest测试覆盖。跑 npm test 以验证所有功能。测试使用真实的示例项目。

出版

要发布新版本，请执行以下操作：

1. 更新package.json中的版本
2. 构建项目：

   npm run build

1. 登录到npm：

   npm login --auth-type=legacy

1. 发布到npm：

   npm publish --access public

有关更多信息，请参阅npm发布文档。

贡献

1. 克隆该仓库
2. 创建要素分支
3. 进行更改并添加测试
4. 向提交拉取请求https://github.com/eoinjordan/gb-studio-agent

许可证

麻省理工学院