MCP: add core tools, annotations and resources

Add strict tool keys, resource reads and panic recovery with regression coverage. Keep existing documented tools listed.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

docs/agents.md

@@ -97,6 +97,11 @@ may be absent from the last checkpoint.
 | `script_ui {action?, window?, widget?, value?, result?}` | Drive ScriptUI windows that scripts opened: `list` (default) the open windows, `get` a window's control tree, `click` a button / checkbox / radio button, `set` text, a slider or a list item, `close` a window (`result`: what a dialog's `show()` returns, default 2 = Cancel). |
 | `batch {steps: [{command, params}], label?, atomic?}` | Several commands in one call and one undo step (`engine.batch`); `"$N.key"` in a param is step N's result (`"$1.layer"`). A failing step rolls the batch back and names the step. |
 | *(bridge)* `screenshot {panel?, id?, max_side?, path?}`, `ui_inspect`, `ui_elements {prefix?}`, `ui_click`, `ui_drag`, `ui_key`, `ui_type`, `ui_set`, `control {method, params}` | Look at and operate the live window. |
+| `command_list` | List commands (same arguments as `list_commands`). |
+| `command_run {id, params?}` | Run a command. |
+| `command_batch {steps, stop_on_error?}` | Run commands in order with per-step results; each edit has its own undo step. |
+| `doc_inspect` | Project overview and active composition. |
+| `render_preview` | Render a PNG without writing a file (`comp`, `time`, `max_side`, `transparent`). |
 
 Layers are referenced by id (from `get_comp`), `"#n"` (1-based index from the top) or name. Comps are
 referenced by id or name, and default to the active comp. Property paths come from `get_layer`, for

docs/mcp.md

@@ -0,0 +1,36 @@
+# MCP conventions
+
+Run `effectcraft-cli mcp` for a headless session, or `effectcraft-cli mcp --bridge 9877`
+to use the desktop app's control channel. Existing ports are unchanged.
+
+The server provides the same core conventions as FilmCraft #28:
+
+| Tool | Arguments | Result |
+| --- | --- | --- |
+| `command_list` | `filter?`, `enabled_only?`, `schemas?` | Command catalog |
+| `command_run` | `id`, `params?` | Engine command result |
+| `command_batch` | `steps: [{id, params?}]`, `stop_on_error?` | `completed`, `failed`, per-step `results` |
+| `doc_inspect` | none | Project overview and active composition |
+| `render_preview` | `comp?`, `time?`, `max_side?`, `transparent?` | PNG and frame information |
+
+`command_batch` stops at the first error by default; false continues. Each edit has its
+own undo step. The existing `batch` tool retains its atomic undo grouping and result references.
+Existing tools, including `list_commands`, `execute_command`, and `batch`, remain listed
+because existing workflows use them; there are no hidden aliases. See [agents.md](agents.md)
+for the full catalog. Each tool has a title and read-only, destructive, idempotent and
+open-world hints. Tools with an optional output path are conservatively annotated as file writers.
+
+Unknown top-level tool argument keys return JSON-RPC `-32602` naming the key and accepted
+arguments. EffectCraft already rejects unknown engine command parameters; that behaviour is
+preserved. Tool failures (including escaped panics) return `isError: true`. Malformed JSON
+returns `-32700` with a null id and the session keeps serving. The MCP backend owns its session
+without a mutex; the engine's render-job mutexes already recover poisoned locks.
+
+Resources `effectcraft://document` and `effectcraft://commands` return JSON matching
+`doc_inspect` and `command_list`. Clients declaring MCP 2026-07-28 in per-request `_meta`
+receive `resultType: complete` and list/read cache hints; document reads are never cached.
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"command_run","arguments":{"id":"comp.new","params":{"width":640,"height":360}}}}
+{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"effectcraft://document"}}
+```