Construct3 MCP服务器

一个模型上下文协议（MCP）服务器，使AI助手（Claude、Cursor、Antigravity和任何兼容MCP的工具）能够安全地读取、分析和修改Construct 3游戏引擎项目。

v1.8.0（M1版本） --完整的原始曲面已完成。请参阅路线图和更新日志了解详情。

![License: MIT](https://opensource.org/licenses/MIT) ](https://nodejs.org/) ![TypeScript](https://www.typescriptlang.org/)

快速开始

# Install dependencies
npm install

# Build the server
npm run build

# Test with your project
node dist/index.js /path/to/your/project.c3proj

添加到MCP配置 （克劳德密码，光标，反重力-- 请参阅用法对于配置文件位置）：

{
  "mcpServers": {
    "construct3": {
      "command": "node",
      "args": ["/absolute/path/to/construct3-mcp/dist/index.js"]
    }
  }
}

为什么存在

问题当你让Claude Code处理Construct 3项目时，它会直接编辑JSON文件，并且经常中断：

对象引用和唯一ID（SID/UID）
事件表依赖关系和包括
布局和实例关系
插件和行为配置
这 usedAddons 注册表

解决方案：此MCP服务器提供 结构化、经过验证的界面 即：

了解Construct 3的内部文件格式和ID系统
通过资源和查询工具提供对项目数据的结构化访问
支持深度分析（依赖关系图、孤立检测、性能审计）
通过自动备份、ID生成和验证安全地创建、更新和删除项目实体
包括访问Construct 3官方文件

特性

资源（只读数据访问）

资源	描述
`construct3://project/info`	项目元数据和基本信息
`construct3://project/structure`	完整的项目结构概述
`construct3://project/addons`	所有插件、行为和效果
`construct3://objects/{name}`	特定对象类型详细信息
`construct3://eventsheets/{name}`	具体事件表详细信息
`construct3://layouts/{name}`	具体布局细节
`construct3://docs/manual/{topic}`	官方构造3文件

查询工具（只读）

工具	说明
`list_objects`	列出所有具有可选名称筛选的对象类型
`list_eventsheets`	列出所有事件表
`list_layouts`	列出所有布局
`list_families`	列出所有对象族
`get_object_details`	获取特定对象的详细信息
`get_eventsheet_details`	获取事件表的详细信息
`get_layout_details`	获取布局的详细信息
`search_objects`	按名称模式搜索对象
`get_project_summary`	获取全面的项目摘要

分析工具

工具	说明
`get_eventsheet_flow`	事件表包括层次结构和布局绑定（Mermaid或JSON）
`get_function_map`	跨事件表的函数定义和调用站点
`get_object_dependencies`	使用对象的位置（事件表、布局、族）
`find_orphaned_objects`	查找任何事件表或布局中未引用的对象
`get_asset_usage`	跟踪声音、图像、字体和视频资源的使用情况
`analyze_performance`	具有分类问题的启发式绩效审计

突变工具（安全写入操作）

工具	说明
`create_object`	创建新的对象类型（Sprite、Text、TiledBg、全局插件等）
`update_object_properties`	添加/删除对象上的实例变量和行为
`delete_object`	删除对象（使用引用检查和可选强制）
`create_event_sheet`	创建一个新的事件表，其中包含可选内容
`add_event_to_sheet`	向工作表添加组、函数、变量、包含或注释
`add_event_block`	添加一个带有条件+动作的块事件（游戏逻辑）
`delete_event_sheet`	删除事件表（带参考检查和可选强制）
`delete_event_from_sheet`	按SID从工作表中删除事件或包含名称（模拟运行、强制）
`update_event_block`	更新现有块：修改/添加/删除操作和条件
`create_layout`	创建具有可配置图层的新布局
`add_instance_to_layout`	将对象实例放置在具有完全属性控制的布局图层上
`delete_layout`	删除布局（阻止启动布局，检查引用）
`update_layout`	更新布局事件表绑定和尺寸
`update_project_metadata`	更新项目名称、版本、作者或描述
`add_animation_to_sprite`	向Sprite对象添加新动画
`update_animation_properties`	更新Sprite上的动画速度、循环和乒乓球

运行时工具（实时游戏控制）

工具	说明
`inject_runtime_bridge`	将桥接脚本注入C3项目，该脚本通过以下方式公开运行时 `globalThis.__c3bridge`
`remove_runtime_bridge`	删除桥接脚本并清理项目
`get_bridge_commands`	列出网桥支持的所有命令（callFunction、getGlobalVar、getObjectState等）
`generate_bridge_eval_script`	生成curl/python脚本，通过浏览器远程调试执行桥接命令
`export_for_preview`	飞行前检查（工作模式、桥接注射）用于预览测试
`clone_project`	通过可选的桥接注入深度复制项目

运行时桥使外部工具（Playwright、浏览器控制台、curl）能够控制正在运行的C3游戏。一旦注入并预览了游戏，您可以：

// From the browser console or any CDP-capable automation tool
globalThis.__c3bridge.submit("callFunction", { name: "StartGame", params: [] });
globalThis.__c3bridge.submit("getGlobalVar", { name: "Score" });
globalThis.__c3bridge.submit("getObjectState", { objectName: "Player" });

提示（工作流模板）

提示	目的
`analyze_project`	分析项目结构和组织
`find_object_usage`	查找特定对象的使用位置
`explain_eventsheet`	解释事件表的工作原理
`review_game_logic`	审查整体游戏逻辑架构
`document_object`	为对象生成文档
`optimize_project`	获取优化建议

安全模型

所有突变工具都遵循严格的安全协议：

验证 --检查保留字、路径遍历和格式的名称。插件/行为ID已验证 usedAddons.
备份 --每个文件都备份到 .bak 在修改之前。
ID生成 --SID（15位随机）、UID（顺序）和imageSpriteIds（7位）会针对整个项目进行冲突检查。
写 --JSON在写入之前经过预验证（往返测试，大小限制）。
验证 --文件在写入后被读回并重新解析，以确认完整性。
缓存失效 --清除所有读取器缓存和索引，以便后续读取看到新数据。

附加保障措施：

背景调查 — delete_object, delete_event_sheet，以及 delete_layout 删除前扫描参考文献。
插件自动注册 --当使用新插件创建对象或添加行为时，已知的Scirra插件会自动注册到 usedAddons。未知/第三方插件因错误而被阻止。
全局插件保护 --单全局inst对象（音频、AJAX等）不能放置在布局上。
插件特定默认值 --为每种插件类型（Sprite、Text、TiledBg、NinePatch）创建具有正确默认属性的实例。
图像生成 --Sprite和TiledBg创建会自动生成具有正确命名约定的有效占位符PNG。批处理写入失败时回滚。
布局实例同步 --当将行为或变量添加到对象类型时，该对象的所有布局实例都会自动更新为所需的 behaviors 和 instanceVariables 这样C3就可以正确加载项目。

文档

详细文档可在 /docs 文件夹：

建筑 -系统设计、组件和数据流
API 参考 -所有资源、工具和提示的完整参考
示例 -使用示例和工作流程
开发指南 -贡献、添加工具、C3格式注释
故障排除 -常见问题和解决方案

安装

先决条件

Node.js >= 18.0.0
npm 或纱线
已保存的Construct 3项目 文件夹格式 （.c3proj，而不是.c3p）

安装依赖项

cd construct3-mcp
npm install

构建

npm run build

这将TypeScript编译为JavaScript dist/ 文件夹。

用法

所有MCP兼容工具都使用相同的JSON配置格式。服务器自动检测 .c3proj 在您的工作目录中，或者您可以传递一个显式的项目路径。

MCP配置 （适用于所有工具）：

{
  "mcpServers": {
    "construct3": {
      "command": "node",
      "args": ["/absolute/path/to/construct3-mcp/dist/index.js"]
    }
  }
}

要针对特定项目而不是自动检测，请执行以下操作：

"args": ["/path/to/construct3-mcp/dist/index.js", "/path/to/your-project"]

使用克劳德代码

将上面的配置添加到项目的 .mcp.json 或全球 ~/.claude/mcp.json.

在任何Construct 3项目文件夹中打开Claude Code
MCP工具会自动出现

使用克劳德桌面

将配置添加到您的Claude Desktop设置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

注意：Claude Desktop不会为每个项目更改工作目录，因此请在中显式传递项目路径 args.

带光标

将配置添加到 .cursor/mcp.json 在项目根目录中（特定于项目）或 ~/.cursor/mcp.json （全球）。

添加或修改配置后重新启动Cursor
Construct 3工具出现在Cursor的AI代理中

与反重力

将配置添加到Antigravity的MCP配置中：

通过用户界面：单击 ... “代理”面板中的菜单→ MCP服务器 → 管理MCP服务器 → 查看原始配置
直接编辑: ~/.gemini/antigravity/mcp_config.json

注意：Antigravity不会为每个项目设置工作目录，因此请在中显式传递项目路径 args.

独立测试

# Auto-detect .c3proj in current directory
cd /path/to/project-folder
node /path/to/construct3-mcp/dist/index.js

# Or pass explicit path
node dist/index.js /path/to/project.c3proj
node dist/index.js /path/to/project-folder

查询示例

MCP服务器运行后，询问Claude：

项目分析：

“我的Construct 3项目中有哪些对象？”
“给我一个项目结构的概述”
“正在使用哪些插件和行为？”
“查找未在任何地方使用的孤立对象”
“对我的项目进行绩效审核”

代码理解：

“解释MainSheet事件表的工作原理”
“显示事件表包括层次结构”
“映射项目中的所有功能”
“哪些对象依赖于玩家？”

安全修改：

“创建一个名为Enemy的新Sprite对象”
“向Player对象添加健康变量”
“为菜单逻辑创建事件表”
“添加一个名为LevelSelect的具有两层的新布局”
将玩家实例放置在游戏布局上的位置100、200

文档：

“显示Sprite插件的Construct 3文档”
“活动表的最佳实践是什么？”

发展

项目结构

construct3-mcp/
├── src/
│   ├── index.ts                    # Main MCP server entry point
│   ├── construct3/
│   │   ├── project-reader.ts       # Project file parser and cache
│   │   ├── project-writer.ts       # Safe write operations with backup
│   │   ├── id-generator.ts         # SID/UID generation with collision avoidance
│   │   ├── templates.ts            # Object, event sheet, layout templates
│   │   ├── png-generator.ts        # Zero-dep placeholder PNG generation
│   │   ├── types.ts                # TypeScript type definitions
│   │   └── analyzers/
│   │       ├── index-builder.ts    # Cross-reference index
│   │       ├── eventsheet-flow.ts  # Event sheet flow analysis
│   │       ├── function-map.ts     # Function mapping
│   │       ├── object-deps.ts      # Object dependency analysis
│   │       ├── orphan-finder.ts    # Orphaned object detection
│   │       ├── asset-usage.ts      # Asset usage tracking
│   │       └── performance.ts      # Performance heuristics
│   ├── resources/
│   │   ├── project.ts              # MCP resources
│   │   └── docs.ts                 # Construct 3 documentation access
│   ├── runtime/
│   │   └── bridge.ts               # Injectable C3 runtime bridge script generator
│   ├── tools/
│   │   ├── query.ts                # 9 query tools
│   │   ├── analysis.ts             # 6 analysis tools
│   │   ├── shared.ts               # Shared validation, error helpers
│   │   ├── event-tools.ts          # Event sheet mutation tools
│   │   ├── event-helpers.ts        # Event Zod schemas, builders, validators
│   │   ├── layout-tools.ts         # Layout mutation tools
│   │   ├── object-tools.ts         # Object mutation tools
│   │   ├── animation-tools.ts      # Animation mutation tools
│   │   ├── project-tools.ts        # Project metadata tools
│   │   └── runtime-tools.ts        # 6 runtime control tools
│   └── prompts/
│       └── workflows.ts            # 6 workflow prompts
├── dist/                           # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

开发命令

# Install dependencies
npm install

# Build (compile TypeScript)
npm run build

# Watch mode (auto-rebuild on changes)
npm run dev

# Start the server
npm start

从源代码构建

git clone https://github.com/liauw-media/construct3-mcp.git
cd construct3-mcp
npm install
npm run build

贡献

我们欢迎捐款！以下是如何开始：

分叉存储库
创建要素分支: git checkout -b feature/amazing-feature
进行更改
构建与测试: npm run build && npm start
提交您的更改: git commit -m 'Add amazing feature'
推到您的分支: git push origin feature/amazing-feature
打开拉取请求

路线图

第一阶段：基础✅

\[x\] 只读项目访问权限
\[x\] 7个资源，9个查询工具，6个提示
\[x\] 项目结构解析
\[x\] 官方文件访问

第二阶段：增强分析✅

\[x\] 事件表流程可视化（美人鱼图）
\[x\] 对象依赖关系图
\[x\] 性能分析工具
\[x\] 资产使用跟踪
\[x\] 孤立物体检测
\[x\] 跨事件表的功能映射

第三阶段：安全修改✅

\[x\] 使用适当的SID/UID管理创建对象
\[x\] 实例变量和行为管理
\[x\] 事件表创建和事件插入
\[x\] 布局创建和实例放置
\[x\] 项目元数据更新
\[x\] 自动备份、验证和确认
\[x\] 删除前的参考检查
\[x\] 已知插件的插件自动注册

第四阶段：事件块和动画✅

\[x\] 事件块创建（条件+动作），具有组路径目标
\[x\] 脚本动作支持（内联JavaScript）
\[x\] 动画管理（在Sprites上添加/更新动画）
\[x\] 针对项目实体的对象类验证

第5阶段：活动和布局操作✅

\[x\] 按SID从工作表中删除事件或包含名称（模拟运行、强制、函数调用者检查）
\[x\] 更新现有事件块（修改/添加/删除条件和操作）
\[x\] 删除布局（带参考检查、启动布局保护）
\[x\] 更新布局属性（事件表绑定、尺寸）
\[x\] 完整实例属性覆盖（角度、颜色、实例变量、行为、标签等）
\[x\] 278个测试、类型安全模板、域拆分工具模块

阶段6：运行时控制✅

\[x\] 可注入运行时桥（runOnStartup、命令队列、滴答处理）
\[x\] 桥接命令：callFunction、get/setGlobalVar、getObjectState、evaluateExpression等。
\[x\] 项目克隆与桥接注入
\[x\] 导出以预览飞行前检查（工作模式、登机桥登记）
\[x\] 桥接评估脚本生成（浏览器CDP的curl/python）

第7阶段：高级功能

\[\]支持.c3p（压缩）项目
\[\]使用参考更新重命名（模拟运行预览）
\[\]批量操作
\[\]插件开发协助

已知限制

仅文件夹格式：适用于.c3proj文件夹项目，而不是.c3p ZIP文件
无重命名重构：重命名对象/图纸不会更新交叉引用（计划在第5阶段）
运行时桥需要浏览器自动化：运行时工具注入一个桥接脚本，但需要一个外部工具（Playwright、curl或任何支持CDP的工具）来驱动浏览器并与正在运行的游戏交互
无ACE验证：事件块条件/操作未根据插件模式进行验证（AI调用者应知道有效的ACE ID）

许可证

MIT许可证-请参阅许可证详细信息文件

作者

贡献者

初始开发和架构

致谢

Anthropic -用于创建模型上下文协议
Scirra -用于构建3游戏引擎
MCP社区-灵感和例子

支持

问题:
讨论:

______________________________________________________________________

精心打造Construct 3社区

返回页首

Construct3 MCP

快速接入

详细介绍