GB Studio MCP 服务器

关键词

GB Studio自动化开发对话式工作流项目管理脚本与资源

使用说明（简要且易操作）

  • 项目简介

    • 该仓库实现了一个 MCP 服务器，用于通过对话和工具调用的方式管理 GB Studio 4.2.2 的项目数据。服务器通过 JSON-RPC 2.0 协议在本地进程间传输请求与响应，默认采用 stdio 传输方式，便于与大型语言模型（LLM）客户端集成。
    • 功能要点包括：创建/打开/保存项目、管理场景、角色（演员）与触发器、变量、背景与精灵资源，以及理解并执行脚本事件、构建 ROM 的外部调用。

  • 主要功能点

    • MCP 协议实现与工具路由
      • 将所有工具模块合并成一个统一的工具集合，并通过 MCP 的 tools/list 与 tools/call 接口暴露给客户端。
    • 资源与项目管理工具
      • create_project、open_project、save_project、get_project_info、set_start_scene、set_player_sprite、add_background、add_sprite 等。
    • 场景、演员、触发器管理工具
      • list_scenes/get_scene/update_scene/delete_scene、list_actors/add_actor/get_actor/update_actor/delete_actor、list_triggers/add_trigger/update_trigger/delete_trigger。
    • 脚本与变量工具
      • add_script_event、clear_script、get_script、add_variable/list_variables/delete_variable 等。
    • 构建支持
      • build_rom：尝试通过 gb-studio-cli 编译 ROM，若未找到 CLI 提供替代提示。
    • 运行环境与传输
      • 服务器使用 @modelcontextprotocol/sdk 提供的 Server API，默认通过 StdioServerTransport 在 stdin/stdout 上处理 JSON-RPC 请求。
    • 数据结构
      • 内存中的 GB Studio split-resource（project.gbsproj、project/settings.gbsres、variables.gbsres、engine_field_values.gbsres、palettes、scenes/actors/triggers、assets 等）格式化管理。

  • 安装步骤

    • 克隆仓库并进入目录
    • 安装依赖并构建
    • 构建后运行 dist/index.js 即可

  • 服务器配置（MCP 客户端配置信息示例说明）

    • MCP 客户端需要知道服务器的启动命令与参数，以便启动并连接。下面描述的是在客户端的配置要点，实际使用请将命令替换为你本地的绝对路径。
    • server 名称：gbstudio-mcp
    • 启动命令：node
    • 参数（示例，需使用你机器上的实际路径）：dist/index.js
    • 说明：将上述信息打包为一个 JSON 配置，客户端启动时会读取并执行该命令以启动 MCP 服务器，与客户端建立连接。该配置仅用于客户端使用，不需要开发者再向终端显示实现细节。

    伪示意（请以 JSON 配置形式提供给 MCP 客户端）： { "serverName": "gbstudio-mcp", "command": "node", "args": ["/absolute/path/to/gbstudio-mcp/dist/index.js"] } 注：serverName 与 command/args 对应仓库构建后实际路径，需使用实际的绝对路径来确保客户端能正确启动服务器。

  • 基本使用方法

    • 启动服务器后，MCP 客户端通过 JSON-RPC 请求与服务器交互。
    • 使用 tools/list 可以获取所有注册工具的信息（名称、描述、输入参数模式）。
    • 使用 tools/call 调用具体工具，例如创建项目、添加背景、设置起始场景等，返回的通常是文本描述或 JSON 字符串。
    • 通过 save_project 持久化当前在内存中的项目状态到磁盘；通过 open_project/load 重新载入磁盘中的项目。
    • 在 GB Studio 中打开/构建项目前，请确保安装了 GB Studio CLI（若要自动构建 ROM）。

服务器信息

访问项目