{
  "markdown": "# construct3-chef\n\nA toolkit for automating Construct 3 project mutations: event sheet recipes, generators, layout scaffolding, sprite scaffolding, and an MCP server for AI-assisted editing.\n\n## What it does\n\nConstruct 3 stores project data as JSON files on disk (event sheets, layouts, object types). construct3-chef provides:\n\n- **Recipes** — JSON-driven mutation scripts that insert/remove/patch events, actions, conditions, and layout instances without opening the C3 editor\n- **Generators** — extract human-readable DSL, TypeScript, and layout summaries from C3 JSON, committed alongside source for diffing and code review\n- **Scaffolding** — clone layouts or sprite objectTypes with remapped UIDs and SIDs\n- **MCP server** — exposes all of the above as Model Context Protocol tools for AI coding agents\n\n## Installation\n\n```bash\nnpm install @genvidtech/construct3-chef\n```\n\nRequires Node.js 22+. The installed CLI binary is named `construct3-chef`.\n\n## Quick Start\n\nAll commands accept a global `--project-dir` option (defaults to `cwd`). Point it at the root of your C3 project — the directory containing `project.c3proj`.\n\n```bash\n# Generate extracted/ files from C3 JSON (run after editing event sheets)\nnpx @genvidtech/construct3-chef generate --project-dir /path/to/c3project\n\n# Apply a recipe\nnpx @genvidtech/construct3-chef apply-recipe my-recipe.json --project-dir /path/to/c3project\n\n# Validate project.c3proj matches disk\nnpx @genvidtech/construct3-chef validate-project --project-dir /path/to/c3project\n\n# Start the MCP server\nnpx @genvidtech/construct3-chef server --project-dir /path/to/c3project\n```\n\nIf you install globally or add to `package.json` scripts, you can omit `npx`.\n\n## CLI Overview\n\n21 subcommands — all accept `--project-dir <path>` (defaults to `cwd`). The table below is kept in lockstep with `src/cli.ts` by `test/readmeCommandInventory.test.ts`.\n\n| Subcommand | Purpose |\n| ---------- | ------- |\n| `server` | Start the MCP server over stdio |\n| `generate [--only <type>]` | Generate all extracted/ files, or one type: `scripts`, `dsl`, `layouts`, `templates`, `sid-registry`, `global-layers` |\n| `apply-recipe <file>` | Apply an event sheet mutation recipe |\n| `rename-symbol <from> <to>` | Rename a symbol across all event sheet scripts |\n| `validate-project` | Dry-run: check that `project.c3proj` matches files on disk |\n| `sync-project` | Write `project.c3proj` to match files on disk |\n| `scaffold-layout` | Clone a layout with remapped UIDs/SIDs |\n| `scaffold-sprite` | Clone a sprite objectType with remapped SIDs and copied images |\n| `remove-layer` | Remove a layer from a layout |\n| `list-templates` | List all template instances across layouts |\n| `navigation-graph` | Print GoToLayout calls (or write a PlantUML diagram) |\n| `search-dsl <pattern>` | Regex search across extracted DSL files |\n| `search-docs` | Search the C3 ACE reference (action/condition/expression ids, param names) for custom addons and the built-in reference cache |\n| `read-addon [name]` | Read a C3 addon's metadata + ACE summary (or a raw entry, or list all addons); works on extracted and archive-only addons |\n| `validate-addons [--addon <id|path>]` | Validate bundled `.c3addon` packages against `project.c3proj.usedAddons` (metadata, integrity, orphan/missing/duplicate) and each addon's `aces.json`/`plugin.js` properties against its `lang/*.json` locales; `--addon` scopes to one addon (by id or source-tree path). Read-only, non-zero exit on findings |\n| `list-addons` | Unified addon inventory — bundled `.c3addon` packages, `project.c3proj.usedAddons` entries, and editor-only addons — one row per addon with status, version, and package path. Read-only, never fails |\n| `diff-addon-aces <from> <to>` | Diff the ACE contract between two addon versions: added/removed ACEs plus changed param signatures. Sources are local (a `.c3addon` path, a discovered id, or an extracted dir). Read-only |\n| `scan-addon-usage <addon>` | Find where a plugin, behavior, or effect addon is used: object/family presence, event-sheet ACE call sites, and expression references. `--from` reports blast radius against a prior version, exiting non-zero when any affected site exists. Read-only |\n| `sync-addon-metadata --direction <manifest-from-package\\|package-from-manifest>` | Sync a bundled `.c3addon` package's `version`/`author` with its `project.c3proj.usedAddons` entry; `manifest-from-package` writes, `package-from-manifest` is a read-only report (chef has no `.c3addon` writer). `--addon` scopes to one addon by id only. `--dry-run` previews. Exits non-zero iff outstanding human work remains |\n| `list-ops` | List available user-defined ops |\n| `apply-op <name>` | Apply a user-defined op by name |\n\nSee [wiki/reference/cli.md](./wiki/reference/cli.md) for full flag documentation (addon-tooling commands — `read-addon`, `validate-addons`, `list-addons`, `diff-addon-aces`, `scan-addon-usage`, `sync-addon-metadata` — are in [wiki/reference/cli-addons.md](./wiki/reference/cli-addons.md)).\n\n## Recipes\n\nRecipes are JSON files that describe mutations to event sheets and layouts. They are the primary way to modify C3 projects programmatically.\n\n```bash\n# Validate without writing\nnpx @genvidtech/construct3-chef apply-recipe my-recipe.json --dry-run\n\n# Show script diffs\nnpx @genvidtech/construct3-chef apply-recipe my-recipe.json --preview\n\n# Apply and regenerate extracted/\nnpx @genvidtech/construct3-chef apply-recipe my-recipe.json\n```\n\nSee [wiki/reference/recipe-reference.md](./wiki/reference/recipe-reference.md) for the full recipe format, all 15 event sheet operations, all 12 layout operations, and the builder shorthand syntax.\n\n## Generators\n\nThe `generate` subcommand produces `extracted/` files that make C3 JSON human-readable:\n\n| Type | Output | Description |\n| ---- | ------ | ----------- |\n| `scripts` | `extracted/**/*.ts` | TypeScript extracted from event sheet script actions |\n| `dsl` | `extracted/**/*.dsl.txt` | Human-readable event sheet DSL |\n| `dsl` | `extracted/**/*.dsl.idx.txt` | JSON-path and SID index for recipe targeting |\n| `layouts` | `extracted/**/*.layout.txt` | Layer/instance summary for each layout |\n| `templates` | `extracted/template-scope.txt` | Cross-layout template instance map |\n| `sid-registry` | `extracted/sid-registry.txt` | Sorted list of all SIDs in the project |\n\nIt is recommended to commit `extracted/` alongside C3 source files for diffability and code review. Run `generate` after editing event sheets or layouts.\n\nSee [wiki/reference/generators.md](./wiki/reference/generators.md) for internals, output format, and cross-reference syntax.\n\n## MCP Server\n\n`construct3-chef server` starts a Model Context Protocol server over stdio. AI coding agents can connect to it to read and mutate a C3 project interactively.\n\n### Starting the server\n\n```bash\nnpx @genvidtech/construct3-chef server --project-dir /path/to/c3project\n```\n\nConfigure it in your MCP client (example for Claude Desktop or similar):\n\n```json\n{\n  \"mcpServers\": {\n    \"construct3-chef\": {\n      \"command\": \"npx\",\n      \"args\": [\"@genvidtech/construct3-chef\", \"server\", \"--project-dir\", \"/path/to/c3project\"]\n    }\n  }\n}\n```\n\n### Available MCP tools\n\nThe server can host more than one C3 project root at once (see [Multi-project support](#multi-project-support) below). Every tool listed here except `list-projects` accepts an optional `project` id parameter to target a non-default registered project; omit it to target the default project. `txId` values are the composite `<projectId>:<counter>` string described in [Optimistic concurrency](#optimistic-concurrency).\n\n**Read tools** (read-only, idempotent):\n\n| Tool | Description |\n| ---- | ----------- |\n| `list-event-sheets` | List all event sheet JSON files in the project |\n| `list-layouts` | List all layout JSON files in the project |\n| `list-global-layers` | List each global layer with its source layout, overriding layouts, and instance count |\n| `read-dsl` | Read the human-readable DSL for an event sheet |\n| `read-dsl-index` | Read the JSON-path/SID index for recipe targeting (supports grep filter) |\n| `read-event-sids` | Read SIDs directly from source JSON (useful after apply-recipe, before regenerate) |\n| `read-scripts` | Read the extracted TypeScript for an event sheet |\n| `read-layout` | Read the layout summary (layers, instances, templates) |\n| `read-template-scope` | Read the cross-layout template scope reference |\n| `read-sid-registry` | Read the global SID registry |\n| `list-include-tree` | Show the transitive include tree for an event sheet |\n| `search` | Regex search across extracted files (DSL, TypeScript, layout summaries, JSON) |\n| `search-docs` | Search the C3 ACE reference (action/condition/expression ids, param names) for custom addons and the built-in reference cache |\n| `resolve-anchor` | Look up a DSL coordinate by line number, SID, or name pattern |\n| `navigation-graph` | Show the layout navigation graph as a from→to→line table, or as PlantUML with `format:\"plantuml\"` |\n| `validate-recipe` | Validate a recipe JSON without applying it (returns txId) |\n| `validate-project` | Dry-run project.c3proj sync check |\n| `read-addon` | Read a C3 addon's metadata + ACE summary (or a raw entry, or list all addons); works on extracted and archive-only addons |\n| `validate-addons` | Validate bundled `.c3addon` packages against `project.c3proj.usedAddons` (metadata, integrity, orphan/missing/duplicate) and each addon's `aces.json`/`plugin.js` properties against its `lang/*.json` locales; optional `addon` param scopes to one addon (by id or source-tree path). Read-only |\n| `list-addons` | Unified addon inventory — one row per addon reconciling bundled `.c3addon` packages, `usedAddons` entries, and editor-only addons, with status and version |\n| `diff-addon-aces` | Diff the ACE contract between two addon versions: added/removed ACEs plus changed param signatures |\n| `scan-addon-usage` | Find where a plugin, behavior, or effect addon is used: object/family presence, event-sheet ACE call sites, and expression references; `from` reports blast radius against a prior version |\n| `preview-addon-metadata-sync` | Dry-run report of `version`/`author` drift between bundled `.c3addon` packages and `project.c3proj.usedAddons` — the read-only preview for `sync-addon-metadata`. Optional `addon` param scopes to one addon by id. Never writes |\n| `list-ops` | List the target project's user-defined ops (parameterized recipe templates) with their parameters |\n| `get-state` | Return server state for the target project: txId and extractedDirty flag |\n| `list-projects` | List every project registered at launch (id, root, extractedDir, default). The only tool with no `project` parameter — it enumerates the registry itself |\n\n**Mutate tools** (modify source files):\n\n| Tool | Description |\n| ---- | ----------- |\n| `apply-recipe` | Apply a recipe JSON string, optionally regenerate extracted/ |\n| `sync-project` | Sync project.c3proj to match disk |\n| `scaffold-layout` | Clone a layout with new UIDs/SIDs |\n| `scaffold-sprite` | Clone a sprite objectType with new SIDs and copied images |\n| `remove-layer` | Remove a layer from a layout; strict by default, with `cascade` / `removeInstances` overrides |\n| `extract-template` | Extract an instance + its scene-graph children into a reusable master template, converting the original into a replica |\n| `templatize-in-place` | Convert an existing instance into the master template on its current layout |\n| `clone-replica-to-layouts` | Add a replica of an existing template to one or more target layouts in one call |\n| `replace-instance-with-replica` | Remove an instance and place a replica of a named template in its spot (same layer, same world props) |\n| `sync-addon-metadata` | Sync `project.c3proj.usedAddons` `version`/`author` fields against bundled `.c3addon` packages; only `direction: \"manifest-from-package\"` writes. Optional `addon` param scopes to one addon by id |\n\n**Non-idempotent read tool** (reads source only, but returns different output per call — do not treat as idempotent for retry or caching):\n\n| Tool | Description |\n| ---- | ----------- |\n| `generate-sids` | Mint fresh unique C3 SIDs seeded from `sid-registry.txt`; minted SIDs are **not** persisted back to the registry |\n\n**Regenerate tool**:\n\n| Tool | Description |\n| ---- | ----------- |\n| `regenerate` | Run all 6 generators and update extracted/ |\n\n### Optimistic concurrency\n\nEach registered project maintains its own `txId` counter that increments on every source-file mutation, emitted and accepted on the wire as a composite `<projectId>:<counter>` string (e.g. `alpha:12`) rather than a bare integer — a bare integer would make an equal counter across two projects, the common case, silently acceptable against the wrong one. Read the current `txId` from `validate-recipe` or `get-state`, then pass it to `apply-recipe` or `sync-project`. If the target project changed between validate and apply, or the token names a different project than the call's `project` parameter, the server rejects the operation and returns the current `txId` so you can re-validate.\n\n### Multi-project support\n\n`server` can host more than one C3 project root in a single process: pass `--project-dir` repeatedly (each optionally prefixed `<id>=`), or set `C3_PROJECT_DIRS` (a `path.delimiter`-separated list of the same `[<id>=]<path>` specs). A bare `--project-dir` or `C3_PROJECT_DIR` continues to register exactly one project, unchanged. Every tool call targets exactly one project, selected by the optional `project` id parameter (see `list-projects` to discover registered ids); user-defined ops are namespaced per project as `op-<projectId>_<opName>`. See [wiki/reference/cli.md](./wiki/reference/cli.md#server) for the full launch-config precedence and [wiki/decisions/0034](./wiki/decisions/0034-mcp-server-multi-project-support.md) for the design.\n\n## Project structure expected\n\nconstruct3-chef expects the standard C3 \"project folder\" layout:\n\n```\nproject.c3proj\neventSheets/\nlayouts/\nobjectTypes/\nscripts/\n  ts-defs/\n    instanceTypes.d.ts\n    objects.d.ts\nfiles/\nimages/\naddons/\n```\n\nThe `extracted/` directory is written by `generate` and read by the MCP server. It does not need to exist before the first `generate` run — the server auto-generates it on startup if missing.\n\n## Documentation\n\nAll project documentation lives in the [wiki](./wiki/index.md) — reference manuals, architecture and research notes, process docs, and the decision records. Start at [wiki/index.md](./wiki/index.md); the most-used pages are:\n\n- [wiki/reference/recipe-reference.md](./wiki/reference/recipe-reference.md) — Complete recipe reference: format, SID addressing, all 15 event sheet operations, all 12 layout operations, builder shorthands, gotchas\n- [wiki/reference/generators.md](./wiki/reference/generators.md) — Generator internals, output format, cross-referencing C3 errors, localVars matching\n- [wiki/reference/cli.md](./wiki/reference/cli.md) — Full CLI flag documentation for all subcommands\n- [wiki/reference/cli-addons.md](./wiki/reference/cli-addons.md) — Addon-tooling commands (`read-addon`, `validate-addons`, `list-addons`, `diff-addon-aces`, `scan-addon-usage`, `sync-addon-metadata`)\n",
  "bytes": 15262,
  "sha": "4d9683534d3e45ecf076b9d9641a1a0b75b21ac01ca67f4d1710e9a28726bcf5",
  "repo_slug": "genvidtechnologies/construct3-chef",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_genvidtechnologies_construct3_chef_wiki__209d0ba6/readme"
}