86 lines
3.9 KiB
Markdown
86 lines
3.9 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
|
|
and [tool contracts](https://modelcontextprotocol.io/specification/2025-06-18/server/tools).
|
|
|
|
## 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```sh
|
|
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.
|