gdevelop-mcp

# gdevelop-mcp [](https://github.com/gb2b/gdevelop-mcp/actions/workflows/ci.yml) [](./LICENSE) [](./package.json) [](https://modelcontextprotocol.io) 一个给任何MCP-aware的LLM代理（Claude Code, Cursor, …）提供对GDevelop项目的完全控制权的MCP服务器：检查，搜索，编辑，预览。 > **30工具 · 5提示 · GitHub规范目录 · 默认安全编辑 · 运行时 + 静态预览** ## 为什么 GDevelop自带一个付费AI助手集成在编辑器中。这个项目是一个免费、开源的替代品——并且可以说是更强大的，因为代理直接从规范的`4ian/GDevelop` GitHub仓库读取，而不是一个精选的快照。 使用gdevelop-mcp代理可以实现的功能： - **从提示构建游戏。** "将官方平台游戏示例改编成一个包含3个关卡的平台游戏，并使用您自己的英雄精灵。" 代理将使用`list_examples`, `read_github_source`, `search_assets`, `edit_project`和`preview_scene`从头到尾地完成任务。 - **彻底检查任何GDevelop功能。** ~1830个操作/条件/表达式，11种事件类型，47+扩展，13种资源类型，5种变量类型——所有这些都从官方源代码树中提取，而不是人工精选。 - **安全编辑项目。** 每次写入都经过基线验证，原子写入到临时文件并重命名，时间戳备份，语义差异。`undo_last_edit`只需一个工具调用即可。 - **获取任何场景的真实预览**，无需离开代理循环——要么是快速静态渲染（`render_scene_static`，<1秒），要么是headless Chromium中的真实运行时捕获（`preview_scene`，~10秒）。 ### vs. GDevelop内置AI | | 内置AI（付费） | gdevelop-mcp（本项目） | | --------------------- | ------------------------- | ------------------------------------------------------------------------------------ | | 成本 | 订阅（Silver / Gold） | 免费、开源 | | 底层模型 | GDevelop的选择 | 任何MCP兼容客户端支持的模型 | | 工具表面 | 仅编辑，带偏见 | 30个可组合工具（检查、搜索、编辑、预览、资产商店、示例、wiki） | | 资产商店 | 是，付费高级 | 是，公共CC0 + 开放许可包 | | 示例 | 是，官方 | 是，所有281个官方MIT示例 | | 自定义工作流 | 有限 | 任意代理提示 + 工具链 | | 真相所在 | 编辑器的快照 | 您选择的`4ian/GDevelop` GitHub仓库版本 | ## 安装 ```bash git clone https://github.com/gb2b/gdevelop-mcp cd gdevelop-mcp pnpm install pnpm build ``` > 需要Node 18+ 和 **pnpm 11+** （通过现代Node上的Corepack启用）。 > Puppeteer在首次安装时下载Chromium（~170 MB）。 > 默认启用供应链保护：生命周期脚本被阻止，除非明确允许（`@napi-rs/canvas`, `esbuild`, `puppeteer`）；Dependabot在提出新版本之前等待7天。有关完整策略，请参见[`.claude/rules/supply-chain.md`](./.claude/rules/supply-chain.md)。 将MCP连接到您的代理。对于Claude Code，请在您的项目（或您的家目录）中添加一个`.mcp.json`文件： ```json { "mcpServers": { "gdevelop": { "command": "node", "args": ["/绝对路径/to/gdevelop-mcp/dist/index.js"] } } } ``` 重启您的代理。工具将显示为`mcp__gdevelop__*`。提示将显示为斜杠命令（例如`/gdevelop:add-hero`）。 ## 入门指南 在需要GDevelop源代码的工具可以做任何有用的事情之前，请先获取规范源代码： ```text agent> sync_gdevelop_sources() → 下载~900个文件（~14 MB）到~/.cache/gdevelop-mcp/ agent> gdevelop_overview() → 返回1-2K令牌的架构图：阅读它以了解哪里可以挖掘 agent> list_examples(query: "platformer") → 发现可用内容 agent> edit_project(path: "/path/to/game.json", operations: [...], dryRun: true) → 预览更改 agent> preview_scene(projectPath: "/path/to/game.json") → 截图实际渲染的游戏 ``` ## 工具参考 ### 安装和缓存（5） | 工具 | 目的 | | ------------------------- | ------------------------------------------------------------------ | | `gdevelop_install_info` | 缓存状态 + 清单 + 可选的本地桌面安装信息 | | `sync_gdevelop_sources` | 从`4ian/GDevelop`下载/刷新规范源代码 | | `check_cache_freshness` | 将缓存引用与最新的GDevelop版本进行比较 | | `check_runtime_freshness` | 将捆绑的gdcore-tools（由`preview_scene`使用）与npm进行比较 | | `gdevelop_overview` | 架构图 + 工具指针图（先阅读以节省令牌） | ### 发现（5） | 工具 | 目的 | | ---------------------- | ----------------------------------------------------------------- | | `search_gdevelop_code` | Grep样式的正则表达式搜索缓存（路径/扩展名过滤器，上下文行） | | `describe_feature` | 获取GDevelop wiki页面作为markdown | | `list_event_types` | 11种内置事件类型（标准、ForEach、JsCode等） | | `list_resource_types` | 13种资源类型（图像、音频、字体等） | | `list_variable_types` | 5+种变量原语 | ### 扩展（4） | 工具 | 目的 | | ----------------------- | ---------------------------------------------------------------------------- | | `list_extensions` | 缓存中的所有扩展 | | `read_extension_source` | 任何扩展文件的原始.ts/.js/.cpp | | `list_dynamic_catalog` | 自动解析的对象/行为及其字段类型 | | `describe_extension` | 概览：动作 + 条件 + 表达式 + 运行时文件 + README | ### 目录（5） | 工具 | 目的 | | ------------------------ | -------------------------------------------------------------- | | `list_object_types` | 精选的对象类型 | | `list_behavior_types` | 精选的行为类型 | | `describe_object_schema` | 类型 + 内容示例的架构 | | `list_instructions` | ~1830个从C++ + JS解析的动作/条件/表达式 | | `describe_instruction` | 匹配类型的目录条目（例如`SimulateJumpKey`） | ### 模板（1） | 工具 | 目的 | | ---------------------- | ------------------------------------------------------------------ | | `quick_start_template` | 搭建一个有效的GDevelop项目（空白/平台游戏/横版/射击游戏） | ### 编辑和安全（7） | 工具 | 目的 | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `inspect_project` | 紧凑的人类可读项目摘要 | | `validate_project` | 结构 + 交叉引用验证 | | `find_in_events` | 事件树的正则表达式搜索（重构审计） | | `list_project_dependencies` | 项目中使用的对象/行为/资源/指令类型的清单 | | `edit_project` | 原子批量操作：布局、对象、实例、行为、**事件**、**自定义扩展**、**变量**、**组**、**资源**、**外部文件** | | `summarize_events` | 按类型的事件树分解 + 最大深度 | | `list_backups` | 项目的备份文件 | | `undo_last_edit` | 恢复最近的备份（可逆转 - 自身备份） | | `diff_projects` | 语义差异（添加/删除/修改） | ### 资产商店（5） | 工具 | 目的 | | ---------------------------- | ------------------------------------------------------- | | `list_asset_packs` | 129+公共包（Kenney，Foliage，Space Shooter等） | | `search_assets` | 11k+个单独的资产（精灵/图块/音频/预制体） | | `get_asset_details` | 准备插入的GDevelop对象JSON | | `list_asset_filters` | 可用的标签和类别 | | `import_assets_into_project` | 下载并插入一个或多个包 | ### 示例（3） | 工具 | 目的 | | ---------------------- | ------------------------------------------ | | `list_examples` | 281个官方MIT许可的示例项目 | | `get_example_details` | 元数据 + GitHub源代码路径 | | `list_example_filters` | 可用的标签 | ### GitHub备用（1） | 工具 | 目的 | | -------------------- | -------------------------------------------------------------------------- | | `read_github_source` | 从`4ian/GDevelop`或`GDevelopApp/GDevelop-examples`获取任何文件/目录 | ### 预览（2） | 工具 | 目的 | 速度 | | --------------------- | --------------------------------------- | ----- | | `render_scene_static` | 基于画布的静态布局渲染 | <1秒 | | `preview_scene` | 通过gdexporter + puppeteer的真实运行时 | ~10秒 | ## 提示（斜杠命令） | 提示 | 用途 | | -------------------- | --------------------------------------------------------------------- | | `start-from-example` | 通过学习官方示例来启动 | | `add-hero` | 查找CC0英雄精灵 + 连接正确的移动行为 | | `debug-project` | 诊断一个损坏的项目（验证/检查/与备份进行差异比较） | | `browse-store` | 资产搜索 + 导入流程的精选主题 | | `safe-edit-flow` | 强制检查 → 干燥运行 → 应用 → 验证 | ## 安全设计 每次编辑都经过： 1. **基线验证** — 拒绝编辑一个已经存在错误的项目 2. **原子批量** — 所有操作成功或都不应用 3. **自动备份** — 在写入之前创建`<file>.bak-<timestamp>` 4. **批量后验证** — 拒绝写入无效结果 5. **原子写入** — 临时文件 + 重命名（崩溃安全） 6. **可逆转** — `undo_last_edit`从任何备份恢复，备份本身 7. **路径验证** — 每个项目路径工具输入都经过规范化 + 空字节检查 结合`dryRun: true`和`diff_projects`，您可以预览、应用和审计每次更改。有关完整的契约，请参见[`.claude/rules/safety.md`](./.claude/rules/safety.md)。 ## 架构 ``` ~/.cache/gdevelop-mcp/ └── ref-v5.6.269/ # 规范源代码，从4ian/GDevelop镜像 ├── Core/ # C++模式 + 内置扩展 ├── Extensions/ # 单个扩展（C++ + JS + TS） └── GDJS/ # JS运行时引擎 src/ ├── index.ts # MCP服务器入口（~40行，薄） ├── prompts.ts # MCP提示（斜杠命令） ├── tools/ # 每个工具家族一个文件 │ ├── install.ts # 缓存管理 │ ├── discovery.ts # 搜索，wiki，事件/资源/变量列表 │ ├── extensions.ts # 扩展检查 │ ├── catalog.ts # 对象，行为，指令目录 │ ├── editing.ts # 验证，编辑，检查，总结 │ ├── safety.ts # 备份，撤销，差异 │ ├── assets.ts # 公共资产商店 │ ├── examples.ts # 官方示例项目 │ ├── github.ts # GitHub备用 │ └── preview.ts # 运行时 + 静态渲染 └── core/ # 业务逻辑（每个文件一个关注点） test/ # vitest单元测试 .claude/ # 仓库级Claude Code配置 ``` ## 限制 - 静态预览无法渲染完整的3D、动画、行为、着色器或自定义效果。要了解更多，请使用`preview_scene`。 - `gdexporter`（传递依赖，仅由`preview_scene`使用）是核心GDevelop贡献者维护的第三方包装器，仍处于测试阶段。如果它在新的GDevelop版本上崩溃，请提交问题。 - 这里使用的资产商店CDN是**公共**的 - 无身份验证，无高级，无私有包。 - Wiki集成爬取页面 - 取决于Wiki保持其当前HTML结构。 ## 贡献 参见[`CONTRIBUTING.md`](./CONTRIBUTING.md)。仓库约定位于[`CLAUDE.md`](./CLAUDE.md) + [`.claude/`](./.claude/)。 ## 许可证 MIT - 参见[`LICENSE`](./LICENSE)。