Faset_Engine/docs/manual/editor/mcp.md

Use the Editor through MCP

Faset exposes the same authoring commands to its native interface and to MCP. MCP runs in the Editor. It never provides access to a running game's entities, and is not linked into the Player or SchemaExporter.

Start a headless server after building Faset:

build/linux-debug/faset_editor --project /absolute/path/to/game --mcp

Configure your MCP client to launch that executable with those arguments using a stdio transport. On Windows select build/windows-debug/faset_editor.exe. Use absolute paths, including the project path. Add --gui when the same process should display the native Editor; a graphical session and supported GPU are then required. A separately launched Editor process owns a separate in-memory session.

The transport uses newline-delimited JSON-RPC and the MCP 2025-06-18 lifecycle. Initialize, send notifications/initialized, then discover commands with tools/list. Standard output is reserved for protocol messages. See the official MCP transport and tool contracts.

Authoring workflow

1. Use faset_documents or create/open a document.
2. Query faset_schema for stable type and field IDs and their constraints.
3. Query the document for its persistent ID and current revision.
4. Submit one faset_scene_edit batch with that revision.
5. Save with faset_document_save. Use Undo/Redo for authoring changes.

For example, the arguments to faset_scene_edit can be:

{
  "document": "REPLACE_WITH_DOCUMENT_ID",
  "revision": 0,
  "idempotency_key": "create-first-object",
  "operations": [{"op": "entity.create", "name": "Player"}]
}

The command returns the new revision and scene with generated IDs. Repeating the same batch and retry key in the same session returns its previous result. Reusing the key for a different payload is an error. An outdated revision produces revision.conflict; query the new state and decide how to apply the intended change. Do not blindly retry a write using a fresh revision.

Each successful batch is one Undo step. A failed operation rejects the whole batch. Manual Inspector edits use this same service, including revision checks.

Jobs and capabilities

faset_import, faset_build, faset_export, and faset_play return job IDs. Use faset_job or faset_jobs for progress, diagnostics and results. faset_job_cancel requests cancellation; cancelling a build is separate from undoing a document change. Failed compilation/import preserves the last successful published generation.

faset_capabilities reports available services. faset_editor_capture is present only in a graphical Editor. It returns an MCP image and can save a project-relative PNG. A headless server has no screenshot tool. faset_play_control provides pause, resume and single-step process controls; it cannot read or modify game entities.

faset_recovery_list and faset_recovery_restore expose crash recovery, including scenes that have never been saved. Restoring an already open document requires its current revision. Recovery refuses to overwrite an externally changed scene file.

Single-command CLI

The CLI is useful for scripts that do not need an MCP session:

build/linux-debug/faset_editor --project /absolute/path/to/game \
  --command '{"name":"faset_import","arguments":{"path":"Assets/door/manifest.json"}}' --wait

--wait follows a returned job until completion. Failed, cancelled and conflicting jobs produce a nonzero exit code. This shell quoting example targets Bash; use the appropriate argument quoting for your Windows shell.

Validation: unit tests cover protocol errors and shared authoring semantics. editor_mcp_stdio launches the real Editor and verifies initialization, clean JSON stdout, conflicts, retry behavior, Undo/Redo, saving, reopening, and orderly EOF.