Gb Studio Agent

🚀 GB Studio Agentic MCP 服務器：用於創建 GameBoy 遊戲

GB Studio Agentic MCP 服務器可用於創建 GameBoy 遊戲，為學生、兒童或您自己提供一個可擴展的模板構建方案。

🚀 快速開始

1. 安裝：npm install -g gbstudio-claude-mcp
2. 啟動服務器：gbstudio-claude-mcp
3. 連接 Claude 桌面端（詳見 TUTORIAL.md）
4. 向 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 中使用的模式相匹配。

1. 在項目根目錄創建一個 .env 文件：

   CLAUDE_API_KEY=your-claude-api-key-here
   # 根據需要添加其他密鑰
   

2. 如果使用 [dotenv]，服務器將自動從 .env 文件中加載變量。
3. .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 — 所有計劃端點的目錄

本地開發

1. 克隆倉庫：

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

2. 安裝 Node.js（推薦：v21.7.1 或兼容版本）
3. 安裝依賴：

   npm install
   

4. 啟動開發服務器：

   npm run dev
   

5. 運行測試套件：

   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 遊戲，請按照以下步驟操作：

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
   

3. 登錄 npm：

   npm login --auth-type=legacy
   

4. 發佈到 npm：

   npm publish --access public
   

有關更多信息，請參閱 npm 發佈文檔。

貢獻代碼

1. 分叉倉庫
2. 創建一個功能分支
3. 進行更改並添加測試
4. 提交拉取請求到 https://github.com/eoinjordan/gb-studio-agent

📄 許可證

本項目採用 MIT 許可證。