# ElserStudio MCP tool map

Use this file to select MCP tools and respect their execution boundaries. The desktop app owns routing, credentials, local SQLite, CAS assets, and canvas state.

## Connection preflight

The MCP server name is `elser-studio`. It is hosted by the running Electron main process over local Streamable HTTP. If no ElserStudio tools are callable, do not substitute shell access, direct SQLite edits, backend HTTP, or Provider APIs.

## Skill runtime and A/B evidence

- Register package metadata with `register_skill_package`; inspect it with `list_skill_packages`.
- Open a visible run with `start_skill_run`, append modules/gates/degradations with `update_skill_run`, and close it with `finish_skill_run`.
- Read evidence with `get_skill_run` or `list_skill_runs`.
- Create paired frozen-input evaluation runs with `create_skill_ab_test`, score each variant with `score_skill_ab_variant`, inspect the result with `get_skill_ab_test`, and close an unscorable comparison explicitly with `finish_skill_ab_test` (`blocked`, `failed`, or `canceled` plus a required reason).
- These tools record and display orchestration evidence. They do not call Providers or add a second execution engine.

## Project and World tools

| Need | Tool | Rule |
|---|---|---|
| Discover projects | `list_projects` | Read before guessing a project id. |
| Create/select project | `create_project`, `set_active_project` | Creation is local; keep returned id. |
| Bind active World | `set_project_active_world` | Bind by canonical ids. |
| Discover/load Worlds | `list_worlds`, `get_world` | Always load before dedup or mutation. |
| Create/update World | `create_world`, `update_world` | Persist lore/style only as World facts, not per-shot prose. |
| Import local media | `import_local_asset` | Import to CAS and retain returned blob hash. |
| Attach shared media | `attach_world_shared_asset` | Use for style, continuity, motion, or other World-scoped shared assets. |
| Manage entities | `create_character`, `update_character`, `create_scene`, `create_prop` | Persist reusable identity/appearance facts; repair canonical character voice/profile facts with `update_character`, never per-request shadow state. |
| Attach entity media | `attach_character_asset`, `attach_scene_asset`, `attach_prop_asset` | Attach by real blob hash and semantic role. |

## Episode and Shot tools

| Need | Tool | Rule |
|---|---|---|
| Discover/load Episode | `list_episodes`, `get_episode` | Prefer the existing canonical Episode. |
| Create/update Episode | `upsert_episode` | Supply stable `sourceScriptWindowId` on re-runs. |
| Replace generated shot list | `replace_episode_shots` | This replaces the full list; prepare all rows before calling. |
| Inspect/update Shot | `list_shots`, `get_shot`, `update_shot` | Use update for targeted production changes. |
| Materialize on canvas | `sync_episode_to_canvas` | Use after Episode/Shot records and verified reference policies exist; pass accepted shot blobs when available. |

Shot persistence supports prompt, dialogue, camera, emotion, duration, reference policy, status, and a provider-neutral generation contract:

- `audio`: `speech`, `ambience`, `foley`, `music`;
- `continuity`: concrete `incomingState`, `outgoingState`;
- `transition`: incoming/outgoing type, optional motif and logical `anchorId`;
- `dependency`: `independent`, `shared_anchor`, or `sequential`.

`referencePolicy` is required production data, not optional prompt decoration. Populate `characterRefs`, `sceneRef`, and `propRefs` with the canonical ids for every visible identity-bearing asset in that Shot. After `replace_episode_shots`, call `list_shots` and compare the persisted ids with the prepared Shot asset ledger before generation or canvas sync. Empty arrays mean the Shot intentionally contains none of that asset class; names in prose do not replace bindings.

Do not write take-review fields into arbitrary Shot JSON. The current MCP has no dedicated take-review persistence tool.

## Text capabilities

- `extract_novel_assets`: returns character/scene/prop candidates and evidence.
- `generate_script`: creates a shot-level script. Pass `worldId` when a World exists so the client supplies canonical World context.

Use `shotPlanningMode: auto` unless the user explicitly specifies duration/range/fixed constraints. Do not invent a universal shot ceiling.

## Reference assembly

Call `assemble_shot_references` with canonical IDs. It resolves the World character sheets, scene/prop refs, style, voice, and optional motion board under the current reference ceiling. Treat its warnings as production blockers or review items; do not silently replace missing canonical media with names or external URLs.

## Image generation

- One output: `submit_image_generation`.
- Two to fifty independent outputs: `submit_image_generation_batch`.
- Synchronous compatibility path: `generate_image`; avoid it for production batches.

Pass `projectId` when the target canvas is known. Otherwise the desktop MCP uses
the Shot's project and then the active desktop project. Each resolvable call
immediately creates a standard image-generation node and updates it through
queued, running, completed, or failed while the canvas remains open. Pass
`canvasWindowId` only to intentionally regenerate an existing image node; never
guess one. A call with no resolvable project remains a headless asset generation.

For a reusable World result, send:

```json
{
  "worldId": "world_id",
  "targetAsset": {
    "kind": "character_sheet | scene_ref | prop_ref | style_ref",
    "entityId": "required for character/scene/prop",
    "label": "optional semantic label"
  }
}
```

A completed target task means generation and canonical attachment both succeeded.
For `character_sheet`, `scene_ref`, and `prop_ref`, the target entity's canonical
identity facts and the request's additional reusable facts are compiled through
the same shared production template as script-node assets: character closeups +
front/strict-side/back full-body views + expressions/details, a four-camera scene
topology board, or a six-view orthographic prop board. These production boards
use the canonical horizontal 16:9 layout. Do not duplicate or weaken the layout
inside Skill prose.

## Video generation

- One output: `submit_video_generation`.
- Two to fifty executable parallel outputs: `submit_video_generation_batch`.
- Synchronous compatibility path: `generate_video`.
- Interrupted KIE provider task: `resume_video_generation` only when a real provider task id is known.

Video arguments may include `shotId`, `worldId`, `generationContract`, `referenceImages`, `referenceMedia`, `promptContext`, `generationMode`, and output settings. Prefer `shotId` + `worldId`; the MCP then resolves stored Shot context and World references through the same client code path as the UI.

Reference media roles currently include `character`, `scene`, `prop`, `style`, `motion`, `spatial_guide`, `continuity`, `audio`, `asset`, and `reference`. Use semantic roles, never Provider-specific numbering.

## Task lifecycle

1. Submit and retain all returned local task ids.
2. Poll a set using `get_generation_tasks({taskIds})`.
3. Continue until `allTerminal` is true.
4. Separate `completed`, `failed`, and `canceled`; never retry failures automatically.
5. Use `get_generation_task` for a single diagnostic read, `list_generation_tasks` for recovery, and `cancel_generation_task` only when the user asks or the active plan is explicitly abandoned.

Canceling a running local task may not stop a remote Provider request, but its late result is not accepted locally.
