Construct3 MCP Server

A Model Context Protocol (MCP) server that enables AI assistants (Claude, Cursor, Antigravity, and any MCP-compatible tool) to safely read, analyze, and modify Construct 3 game engine projects.

v1.9.0 — Writes follow what the Construct 3 editor itself saves and checks: load-time rules before every event sheet write, the editor's event shapes and name rules, and a validate_project without the false reports it gave on editor-saved projects. See What's new in 1.9.0 and the CHANGELOG.

What's new in 1.9.0

• Editor load-time checks — validate_project checks the rules the Construct 3 editor enforces when it opens a project, and event sheet writes that would add such an error are refused.
• Behavior conditions and actions the editor reads — written with behaviorType; fix_legacy_behavior_keys repairs sheets from older versions (behavior-type is still accepted as a deprecated input alias).
• Find events by editor number — locate_event and get_eventsheet_outline turn "sheet, event N, action M" into the event's JSON path.
• Runtime traps — find_runtime_traps, the construct3://docs/pitfalls resource and the debug_stuck_game prompt for logic that loads but hangs or fails silently.
• Editor-faithful event shapes — else-if and OR blocks, events without conditions, positional function calls, script lines and the Functions object as the editor saves them; fix_legacy_event_shapes converts older sheets.
• Safer deletes and editor name rules — deletes and removals of used behaviors, instance variables and family members are refused, ambiguous SIDs are refused (pick one with eventPath), case-only name clashes are refused, and nested sub-layers are supported everywhere.
• Accurate reports — validate_project, find_orphaned_objects, get_asset_usage and analyze_performance read editor-saved projects correctly (Transitions folder, animation folders, file assets, non-world instances, sub-layers) instead of reporting false problems.
• Byte-faithful writes — line endings, trailing newline, BOM and file-name case are kept; lowercase image file names and per-instance behavior entries match the editor; every write result carries an editorNote.

Full list: CHANGELOG.

Quick Start

# Install dependencies
npm install

# Build the server
npm run build

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

Add to your MCP config (Claude Code, Cursor, Antigravity — see Usage for config file locations):

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

Table of Contents

• Why This Exists
• Features
• Installation
• Usage
• Safety Model
• Development
• Contributing
• License

Why This Exists

The Problem: When you ask Claude Code to work on Construct 3 projects, it directly edits JSON files and often breaks:

• Object references and unique IDs (SIDs/UIDs)
• Event sheet dependencies and includes
• Layout and instance relationships
• Plugin and behavior configurations
• The usedAddons registry

The Solution: This MCP server provides a structured, validated interface that:

• Understands Construct 3's internal file format and ID system
• Provides structured access to project data via resources and query tools
• Enables deep analysis (dependency graphs, orphan detection, performance audits)
• Safely creates, updates, and deletes project entities with automatic backup, ID generation, and validation
• Includes access to official Construct 3 documentation

Features

Resources (Read-Only Data Access)

Resource	Description
construct3://project/info	Project metadata and basic info
construct3://project/structure	Complete project structure overview
construct3://project/addons	All plugins, behaviors, and effects
construct3://objects/{name}	Specific object type details
construct3://eventsheets/{name}	Specific event sheet details
construct3://layouts/{name}	Specific layout details
construct3://docs/index	Index of documentation categories and popular topics
construct3://docs/manual/{topic}	Official Construct 3 documentation
construct3://docs/pitfalls	Curated Construct 3 pitfalls (signals, scripts, picking, expressions), each tagged with its source

Query Tools (Read-Only)

Tool	Description
list_objects	List all object types with optional name filtering
list_eventsheets	List all event sheets
list_layouts	List all layouts
list_families	List all object families
list_timelines	List all timelines (root and subfolders); transitions are listed separately
list_addons	List addons in usedAddons, optionally filtered by type
get_object_details	Get detailed info about a specific object
get_eventsheet_details	Get detailed info about an event sheet
get_layout_details	Get detailed info about a layout
get_timeline_details	Get a timeline's full JSON (tracks and settings)
search_objects	Search objects by name pattern
get_project_summary	Get comprehensive project summary

Analysis Tools

Tool	Description
get_eventsheet_flow	Event sheet include hierarchy and layout bindings (Mermaid or JSON)
get_function_map	Function definitions and call sites across event sheets (Call function actions, Functions.Name(...) expression calls, function map registrations)
get_object_dependencies	Where objects are used (event sheets, layouts including sub-layers, families)
find_orphaned_objects	Find objects not used by any event (including object parameters, expressions and script actions) or layout (including sub-layers, non-world instances and object properties of other instances)
get_asset_usage	Track sound, image, font, video and project file usage (used, unused or not analysed)
analyze_performance	Heuristic performance audit with categorized issues
validate_project	Integrity checks: missing files, required fields, duplicate SIDs/UIDs, repeated layer names, broken references and includes, behaviors and instance variables that events use but their object lacks, missing addons, legacy "behavior-type" keys, layout instances without behavior entries, event shapes older versions wrote that the editor never writes, scripts in the one-string shape of older Construct 3 releases, orphaned and backup files, plus the rules the C3 editor enforces at load (trigger and else placement, expression syntax, empty expressions, duplicate names/SIDs, family plugins). Rules verified only in part are reported as warnings (details in API.md). valid means no errors and every registered file was checked; complete (and so valid) is false when a registered file exists but was not checked (over the 10MB read limit, invalid JSON, unreadable; listed in unscannedFiles)
get_group_settings	Event group settings (isActiveOnStart, disabled) across sheets, filterable by sheet and active state
locate_event	Map an editor event number ("es_game, event 72, action 1") to its JSON path, sid, content and neighbouring events
get_eventsheet_outline	Readable, paged event sheet outline with editor event numbers (IF/DO/CALL/SCRIPT/GROUP/FUNCTION/VAR)
find_runtime_traps	Runtime traps: Wait for signal tags nothing signals, waits that start after a call already raised their tag, unused/dynamic signal tags, scripts using function parameters without localVars

Mutation Tools (Safe Write Operations)

Objects and families

Tool	Description
create_object	Create a new object type (Sprite, Text, TiledBg, global plugins, etc.); refuses names that clash with an object type, a family, System or the Functions object, ignoring case
update_object_properties	Add/remove instance variables and behaviors, change global status; removing one that events still use is refused, listing the uses, unless forced
delete_object	Delete an object; refused while anything uses it (events, instances on any layer or sub-layer, families), listing where, unless forced
create_family	Create a family; refuses name clashes and members of mixed plugins (load-time checked)
update_family	Add/remove members and shared instance variables; refuses member changes that mix plugins (load-time checked), and removing an instance variable or member through which events still use the family's instance variables or behaviors, unless forced
delete_family	Delete a family; refused while events or object properties name it or events use its instance variables or behaviors through a member, listing where, unless forced

Event sheets

Tool	Description
create_event_sheet	Create a new event sheet with optional includes; refuses names that differ from an existing sheet only in case
add_event_to_sheet	Add a group, function, variable, include, or comment to a sheet (load-time checked); functions take the editor's return type, Asynchronous and Copy picked options; the names of a new (global) variable and of function parameters are checked like in the editor
add_event_block	Add a block event with conditions + actions (gameplay logic), written in the editor's own shapes: sub-events (also without conditions), else/else-if blocks, OR blocks, function calls, script actions, comment rows; refuses writes that break the checked editor load-time rules (expression syntax, empty expressions, trigger placement) and warns where Else cannot stand (after a triggered event)
update_event_block	Update an existing block: modify/add/remove actions and conditions, make it an else or OR block (load-time checked)
update_event_block_action	Replace the parameters of one action in a block (by block SID and action index; function call arguments as an array; load-time checked)
update_event_variable	Rename a variable or change its type, initial value, static or constant flag; a new name is checked like in the editor
move_events_between_sheets	Copy or move top-level events between sheets by SID (optionally into a group); load-time checked, so copying an event that breaks a load-time rule is refused; a copy or move that would clash event variable names (e.g. a copied global variable) is refused
delete_event_from_sheet	Delete an event from a sheet by SID or include name (dry-run, force); refuses while functions or event variables it removes are still referenced elsewhere (by calls, function maps, System variable ACEs or by name in expressions); warns about an else block the delete leaves behind
remove_event_from_sheet	Remove an include from a sheet by included sheet name
delete_event_sheet	Delete an event sheet (with reference checking and optional force)
fix_legacy_behavior_keys	Rename legacy "behavior-type" keys (written by older versions) to "behaviorType" in all event sheets, checking each name against the object's behaviors (dry-run by default)
fix_legacy_event_shapes	Convert event shapes written by older versions into the editor's own (block isElse to a System else condition, condition isOr to isOrBlock, old-shape function calls to positional arguments, one-string scripts, as older Construct 3 releases also saved them, to lines) where the result is unambiguous; reports the rest and which conversions can change how an event runs (dry-run by default)

Event SIDs are not always unique in editor-saved sheets. The tools that find an event by SID refuse a SID shared by several events in the sheet and list the candidates; pass eventPath (the JSON path that locate_event returns, e.g. events[3].children[1]) to pick one. move_events_between_sheets keeps SIDs and warns when a copy leaves such a shared SID in the target sheet. See API.md.

Layouts, layers and instances

Tool	Description
create_layout	Create a new layout with configurable layers; refuses names that differ from an existing layout only in case
update_layout	Update layout event sheet binding and dimensions
delete_layout	Delete a layout (blocks startup layout, checks references)
add_layer	Add a layer (position, visibility, transparency, parallax, blend mode); refuses a name any layer or sub-layer of the layout uses, ignoring case
update_layer	Rename a layer or sub-layer or change visibility, interactivity, parallax, blend mode, scale rate, Z elevation; refuses a new name used by another layer or sub-layer, ignoring case
delete_layer	Delete a layer or sub-layer with its sub-layers (never the last top-level one; blocked while they hold instances unless forced)
add_instance_to_layout	Place an object instance on a layout layer or sub-layer with full property control
update_instance	Update a placed instance by UID on any layer or sub-layer (position, size, angle, color, visibility, tags, instance variables)
delete_instance_from_layout	Remove a placed instance by UID (layers, sub-layers and non-world instances)

Sprite animations

Tool	Description
add_animation_to_sprite	Add a new animation to a Sprite object
update_animation_properties	Update animation speed, looping, ping-pong, repeat count
rename_animation	Rename an animation with its frame image files and the layout instances starting with it
delete_animation	Delete an animation (never the last one)
add_frame_to_animation	Add a blank frame (placeholder PNG) at an index
update_frame	Update a frame's duration, size or origin
delete_frame_from_animation	Delete a frame by index (never the last one)
replace_sprite_image	Replace a frame's image with base64 PNG data

Timelines

Tool	Description
create_timeline	Create a timeline (duration, loop, ping-pong, repeat count, start-on-layout); refuses a case variant of a timeline in the same folder
update_timeline	Update timeline settings or enable/disable it
delete_timeline	Delete a timeline (backs up exactly the file it deletes; errors and leaves project.c3proj unchanged when the file is missing)

Project and addons

Tool	Description
update_project_metadata	Update project name, version, author, or description
register_addon	Add a plugin, behavior or effect to usedAddons
unregister_addon	Remove an addon from usedAddons (built-ins need force)

Runtime Tools (Live Game Control)

Tool	Description
inject_runtime_bridge	Inject a bridge script into the C3 project that exposes the runtime via globalThis.__c3bridge
remove_runtime_bridge	Remove the bridge script and clean up the project
get_bridge_commands	List all commands the bridge supports (callFunction, getGlobalVar, getObjectState, etc.)
generate_bridge_eval_script	Generate a curl/python script to execute a bridge command via browser remote debugging
export_for_preview	Pre-flight checks (worker mode, bridge injection) for preview testing
clone_project	Deep-copy the project with optional bridge injection
pack_project	Pack the project folder into a .c3p file that Construct 3 can open (optionally injects the bridge first)

The runtime bridge enables external tools (Playwright, browser console, curl) to control a running C3 game. Once injected and the game is previewed, you can:

// 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" });

Prompts (Workflow Templates)

Prompt	Purpose
analyze_project	Analyze project structure and organization
find_object_usage	Find where a specific object is used
explain_eventsheet	Explain how an event sheet works
review_game_logic	Review overall game logic architecture
document_object	Generate documentation for an object
optimize_project	Get optimization suggestions
debug_stuck_game	Diagnose soft-locks and silently dead features (runs find_runtime_traps, uses the pitfalls doc)

Safety Model

Mutation tools follow a strict safety protocol (exceptions below):

1. Validation — Names checked for reserved words, path traversal, format. Plugin/behavior IDs validated against usedAddons.
2. Backup — JSON files are backed up to <filename>.bak before modification.
3. ID Generation — SIDs (15-digit random), UIDs (sequential), and imageSpriteIds (7-digit) are collision-checked against the entire project. Layouts and object types over the 10MB read limit or with invalid JSON are scanned as text for their UIDs and SIDs; when a registered layout or object type exists but cannot be read at all, a new UID is refused instead of guessed.
4. Write — JSON is pre-validated (round-trip test, size limit), then written to a temp file and renamed into place. Files keep their text style (see below).
5. Verify — Files are read back, compared with what was written, and re-parsed to confirm integrity.
6. Cache Invalidation — All reader caches and indexes are cleared so subsequent reads see fresh data.

Steps 2, 4 and 5 apply in full to writes that go through the project writer: objects, families, event sheets, layouts, animations, project metadata and addon auto-registration. The other write paths do less:

• register_addon and unregister_addon replace project.c3proj through a temp file, with no .bak backup and no read-back check.
• The timeline tools back up the timeline file and project.c3proj and write through a temp file, but do not read the result back.
• The runtime tools (inject_runtime_bridge, remove_runtime_bridge, and export_for_preview / pack_project when they inject the bridge) write project.c3proj and the bridge script in place, with no backup or read-back check.
• PNG images are written without a backup.

Close and reopen the project in Construct 3 before saving there. The editor keeps an open project in memory, so saving from a session that was opened before these edits can overwrite them. Its Project Bar reload (F9) re-reads script files only, not event sheets, layouts or project.c3proj. Every response that reports a completed write carries this reminder as editorNote. Error responses do not, even when a multi-step tool (e.g. create_object) failed after an earlier step had already written.

Additional safeguards:

• Reference checking — delete_object, delete_family, delete_event_sheet, and delete_layout scan for references before deleting; update_object_properties and update_family check the events before removing an instance variable, a behavior or a family member.
• Addon auto-registration — When creating objects with new plugins or adding behaviors, known Scirra addons are automatically registered in usedAddons. Unknown/third-party addons are blocked with an error.
• Global plugin protection — Singleglobal-inst objects (Audio, AJAX, etc.) cannot be placed on layouts.
• Plugin-specific defaults — Instances are created with correct default properties for each plugin type (Sprite, Text, TiledBg, NinePatch).
• Image generation — Sprite and TiledBg creation automatically generates valid placeholder PNGs, named like the editor names them: images/<object>-<animation>-000.png, all lowercase. Batch writes roll back on failure.
• Layout instance sync — Like the editor, every layout instance carries an entry for each behavior of its object type and of the families it belongs to, with the built-in behaviors' default property values. add_instance_to_layout writes these entries; adding or removing a behavior (update_object_properties) or changing family membership (update_family, delete_family) updates the existing instances. Behavior or variable changes also make sure every instance of the object has the behaviors and instanceVariables dicts C3 expects.
• Names compared like the editor — Create and rename tools refuse a name that differs from an existing one only in case where Construct 3 compares names ignoring case: event sheets and layouts (project-wide), object types and families, the layers of one layout (sub-layers included; the editor cannot load a layout with two such layers), the animations of one sprite (in any animation folder), and sibling project-bar folders. Timeline names are compared exactly, as the editor does, but a case variant of a timeline in the same folder is refused because both would share one file on Windows and macOS.
• Event variable names checked like the editor — add_event_to_sheet and update_event_variable refuse the event variable and function parameter names the editor's variable and parameter dialogs refuse: a name that matches, ignoring case, an event variable or function parameter in its scope (for a global variable, any in the project; for a local one or a parameter, the globals, the variables and parameters of its enclosing events and those below its parent event or function), the name of a System expression (e.g. time, random), and names with whitespace, punctuation such as - . :, a leading underscore or only digits. Names of object types and families are allowed, as in the editor. move_events_between_sheets refuses a copy or move that would create such a clash, e.g. a copy of a global variable (the editor renames a pasted variable instead).
• No overwrite on create — Create tools refuse to write an entity JSON file (object type, family, event sheet, layout) or a timeline file where one already exists, also one whose name differs only in case (an unregistered file, or one registered under another spelling). Nothing is backed up or replaced. Placeholder PNGs are not covered: create_object and the animation tools write them over an image file of the same name in images/, e.g. one left behind by a deleted object or animation.
• File names kept — Rewriting an existing file keeps its name on disk exactly, including case (e.g. Layout1.json registered as layout1); the .bak backup takes the same name.
• Text style preserved — JSON is written the way Construct 3 saves it (tab indent). A file that already exists keeps its own line endings (e.g. CRLF from a git core.autocrlf checkout), exact trailing whitespace and BOM. A new file follows project.c3proj, then the first JSON file with line breaks in its target folder, then Construct 3's own style (LF, no trailing newline, no BOM). For files in Construct 3's tab layout, diffs show only the lines that changed; files indented another way (e.g. with spaces) are re-indented with tabs in full.

Documentation

Detailed documentation is available in the /docs folder:

• Architecture - System design, components, and data flow
• API Reference - Complete reference for all resources, tools, and prompts
• Examples - Usage examples and workflows
• Development Guide - Contributing, adding tools, C3 format notes
• Troubleshooting - Common issues and solutions

Installation

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• A Construct 3 project saved in folder format (.c3proj, not .c3p)

Install Dependencies

cd construct3-mcp
npm install

Build

npm run build

This compiles TypeScript to JavaScript in the dist/ folder.

Usage

All MCP-compatible tools use the same JSON configuration format. The server auto-detects .c3proj in your working directory, or you can pass an explicit project path.

MCP config (same for all tools):

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

To target a specific project instead of auto-detecting:

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

With Claude Code

Add the config above to your project's .mcp.json or global ~/.claude/mcp.json.

1. Open Claude Code inside any Construct 3 project folder
2. The MCP tools appear automatically

With Claude Desktop

Add the config to your Claude Desktop settings file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Note: Claude Desktop doesn't change working directory per-project, so pass the project path explicitly in args.

With Cursor

Add the config to .cursor/mcp.json in your project root (project-specific) or ~/.cursor/mcp.json (global).

1. Restart Cursor after adding or modifying the config
2. The Construct 3 tools appear in Cursor's AI agent

With Antigravity

Add the config to Antigravity's MCP configuration:

• Via UI: Click the ... menu in the Agent panel → MCP Servers → Manage MCP Servers → View raw config
• Direct edit: ~/.gemini/antigravity/mcp_config.json

Note: Antigravity doesn't set a working directory per-project, so pass the project path explicitly in args.

Standalone Testing

# 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

Example Queries

Once the MCP server is running, ask Claude:

Project Analysis:

• "What objects are in my Construct 3 project?"
• "Give me an overview of the project structure"
• "What plugins and behaviors are being used?"
• "Find orphaned objects that aren't used anywhere"
• "Run a performance audit on my project"

Code Understanding:

• "Explain how the MainSheet event sheet works"
• "Show me the event sheet include hierarchy"
• "Map all the functions in the project"
• "What objects depend on the Player?"

Safe Modifications:

• "Create a new Sprite object called Enemy"
• "Add a health variable to the Player object"
• "Create an event sheet for the menu logic"
• "Add a new layout called LevelSelect with two layers"
• "Place a Player instance at position 100, 200 on the Game layout"

Documentation:

• "Show me the Construct 3 documentation for the Sprite plugin"
• "What are the best practices for event sheets?"

Development

Project Structure

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
│   │   ├── event-shapes.ts         # The event shapes the editor writes (else, OR, calls, scripts)
│   │   ├── instance-behaviors.ts   # Behavior entries on layout instances
│   │   ├── animation-rename.ts     # Frame image files and layout instances a rename_animation changes
│   │   ├── json-format.ts          # On-disk text style (line endings, trailing newline, BOM)
│   │   ├── layers.ts               # Layer trees: every layer and sub-layer, their instances, layer names
│   │   ├── atomic-write.ts         # Temp-file-and-rename writes that keep file names on disk
│   │   ├── names.ts                # Case-insensitive name and folder comparison
│   │   ├── event-variable-names.ts # Editor name rules for event variables and function parameters
│   │   ├── path-utils.ts           # Path resolution inside the project folder
│   │   ├── png-generator.ts        # Zero-dep placeholder PNG generation
│   │   ├── timeline-folders.ts     # The editor's Transitions folder in the timelines container
│   │   ├── types.ts                # TypeScript type definitions
│   │   └── analyzers/
│   │       ├── index-builder.ts    # Cross-reference index
│   │       ├── event-flow.ts       # Event sheet flow and function map
│   │       ├── object-deps.ts      # Object dependencies and orphaned objects
│   │       ├── asset-usage.ts      # Asset usage tracking
│   │       ├── animations.ts       # Sprite animation trees (items + subfolders)
│   │       ├── event-outline.ts    # Editor event numbers, event sheet outline
│   │       ├── performance.ts      # Performance heuristics
│   │       ├── integrity.ts        # Project integrity checks (validate_project)
│   │       ├── load-rules.ts       # Editor load-time rules (validate_project, pre-write checks)
│   │       ├── legacy-behavior-keys.ts # Legacy "behavior-type" key scan and repair
│   │       ├── legacy-event-shapes.ts # Legacy isElse/isOr/function call/script shape scan and repair
│   │       ├── delete-references.ts # Function and variable names an event delete would leave dangling
│   │       ├── behavior-refs.ts    # Behavior name checks against objects and families
│   │       ├── group-settings.ts   # Event group settings (get_group_settings)
│   │       ├── runtime-traps.ts    # Signal pairing and order, script/parameter traps
│   │       └── script-scan.ts      # Lightweight JS/TS scanner for script actions
│   ├── resources/
│   │   ├── project.ts              # 6 project resources
│   │   ├── docs.ts                 # 3 Construct 3 documentation resources
│   │   └── pitfalls.ts             # Curated pitfalls doc (construct3://docs/pitfalls)
│   ├── runtime/
│   │   ├── bridge.ts               # Injectable C3 runtime bridge script generator
│   │   └── zip-writer.ts           # Zero-dep ZIP writer for .c3p packing
│   ├── tools/
│   │   ├── query.ts                # 9 query tools
│   │   ├── analysis.ts             # 11 analysis tools
│   │   ├── mutations.ts            # Registers the domain tool modules below
│   │   ├── shared.ts               # Shared validation, result/error helpers, editor reload note
│   │   ├── object-tools.ts         # Object and family tools (6)
│   │   ├── event-tools.ts          # Event sheet tools (12)
│   │   ├── event-helpers.ts        # Event Zod schemas, builders, validators
│   │   ├── layout-tools.ts         # Layout, layer and instance tools (9)
│   │   ├── animation-tools.ts      # Sprite animation and frame tools (8)
│   │   ├── timeline-tools.ts       # Timeline tools (5)
│   │   ├── project-tools.ts        # Project metadata and addon tools (4)
│   │   └── runtime-tools.ts        # 7 runtime control tools
│   └── prompts/
│       └── workflows.ts            # 7 workflow prompts
├── test/                           # Vitest suites, mocks and fixtures
├── dist/                           # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

Development Commands

# Install dependencies
npm install

# Build (compile TypeScript)
npm run build

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

# Run the test suite (vitest)
npm test

# Start the server
npm start

Building from Source

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

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Build and test: npm run build && npm start
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to your branch: git push origin feature/amazing-feature
7. Open a Pull Request

Roadmap

Phase 1: Foundation ✅

• Read-only project access
• 7 resources, 9 query tools, 6 prompts
• Project structure parsing
• Official documentation access

Phase 2: Enhanced Analysis ✅

• Event sheet flow visualization (Mermaid diagrams)
• Object dependency graph
• Performance analysis tools
• Asset usage tracking
• Orphaned object detection
• Function mapping across event sheets

Phase 3: Safe Modifications ✅

• Object creation with proper SID/UID management
• Instance variable and behavior management
• Event sheet creation and event insertion
• Layout creation and instance placement
• Project metadata updates
• Automatic backup, validation, and verification
• Reference checking before deletion
• Addon auto-registration for known plugins

Phase 4: Event Blocks & Animation ✅

• Event block creation (conditions + actions) with group path targeting
• Script action support (inline JavaScript)
• Animation management (add/update animations on Sprites)
• Object class validation against project entities

Phase 5: Event & Layout Operations ✅

• Delete events from sheets by SID or include name (dry-run, force, checks for references to the functions and event variables it removes)
• Update existing event blocks (modify/add/remove conditions and actions)
• Delete layouts (with reference checking, startup layout protection)
• Update layout properties (event sheet binding, dimensions)
• Full instance property overrides (angle, color, instanceVariables, behaviors, tags, etc.)
• 278 tests, type-safe templates, domain-split tool modules

Phase 6: Runtime Control ✅

• Injectable runtime bridge (runOnStartup, command queue, tick processing)
• Bridge commands: callFunction, get/setGlobalVar, getObjectState, evaluateExpression, etc.
• Project cloning with bridge injection
• Export-for-preview pre-flight checks (worker mode, bridge registration)
• Bridge eval script generation (curl/python for browser CDP)

M1 Primitive Surface ✅ (v1.8)

• Layers, instance updates and instance removal
• Families (create, update members and variables, delete)
• Animation frames (add, update, delete, replace image) and animation rename/delete
• Timelines (create, update, delete, list, details)
• Addon registry tools (list_addons, register_addon, unregister_addon)
• Project integrity validation and event group settings
• .c3p packing (pack_project) and an end-to-end acceptance test

Editor Fidelity ✅ (v1.9)

• Editor load-time checks in validate_project and before event sheet writes
• Event shapes, names, image file names and instance behavior entries as the editor writes them, with repair tools for older sheets
• Event locator and outline by editor event number, runtime trap analysis and curated pitfalls
• Reference-checked deletes, ambiguous-SID protection and nested sub-layers in every layout tool
• Byte-faithful writes (line endings, BOM, file-name case)

Phase 7: Advanced Features

• Opening .c3p (zipped) projects directly
• Rename with reference updates (dry-run preview)
• Bulk operations
• Plugin development assistance

Known Limitations

• Folder Format Only: Works with .c3proj folder projects; pack_project can write a .c3p, but .c3p files cannot be opened
• Editor Holds the Project in Memory: Close and reopen the project in Construct 3 after MCP edits and before saving there, or the editor can overwrite them
• No Rename Refactoring: Renaming objects/sheets does not update cross-references (planned, see Phase 7)
• Runtime Bridge Requires Browser Automation: The runtime tools inject a bridge script but need an external tool (Playwright, curl, or any CDP-capable tool) to drive the browser and interact with the running game
• No ACE Validation: Event block conditions/actions are not validated against plugin schemas (the AI caller is expected to know valid ACE IDs). Only the editor load-time rules listed under validate_project are checked; triggers are recognised by the on- id convention, which third-party addons do not always follow, so their trigger problems are warnings only. OR blocks are created with isOrBlock

License

MIT License - see LICENSE file for details

Authors

Contributors

• Initial development and architecture

Acknowledgments

• Anthropic - For creating the Model Context Protocol
• Scirra - For Construct 3 game engine
• The MCP Community - For inspiration and examples

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with care for the Construct 3 community

Back to top