MCP: Entities (#192) #206

Merged

crowmaki merged 2 commits from issue-192-mcp-entities into main

2026-10-12 05:25:16 +00:00

crowmaki commented

2026-10-12 05:16:52 +00:00

Owner

Closes #192.

With these tools, a harness can complete and tidy what script import found.

Tools

Reads
- list_entities lists the Characters, Locations, Location folders and Props.
- read_character returns one Character with its identity fields, its Looks (each with its effective identity and default wardrobe), its Wardrobe items and its voice set.
Characters, Looks and Wardrobe items
- Characters: create_character, rename_character, set_character_identity, delete_character and merge_characters.
- Looks: create_look, rename_look, set_look_identity (the overrides), set_look_default_wardrobe, set_default_look and delete_look.
- Wardrobe items: create_wardrobe_item, rename_wardrobe_item, set_wardrobe_text and delete_wardrobe_item.
Locations
- Locations: create_location, rename_location, set_location_description, set_location_ambience, delete_location and merge_locations.
- Location folders: create_location_folder, rename_location_folder, delete_location_folder and move_location.
Props: create_prop, rename_prop, set_prop_description and delete_prop.
Lighting
- read_lighting returns the Lighting list with its phrases, and the slug table.
- add_lighting, rename_lighting, reorder_lighting, remove_lighting, set_lighting_phrase, set_slug_lighting and remove_slug_lighting each return read_lighting.

How the tools reply

Each edit returns the thing it changed. A tool that changes a Look or a Wardrobe item returns the Look's or item's Character.
A delete returns the undo state, and undo brings the deleted thing back.
A refused delete returns the core's reason. For example, a Character that speaks can't be deleted; the harness has to merge it into another Character instead.
Identity fields have the same names as in read_character (ageBuild, distinctiveFeatures…), and the core validates them.

set_default_look, set_look_default_wardrobe and set_wardrobe_text go a little beyond the ticket. set_default_look is necessary because the core refuses to delete the default Look. The other two fill in Look and Wardrobe text that prompts use.

Creating from a Line

create_character and create_prop take an optional fromLineId. This works the same way as making an Entity from a selection in the script view: an unknown Line is refused, and the reply includes sourceLineId. The Project does not store the link, because the core keeps no link today. We agreed to match the app for now. #205 tracks storing the link.

Tests

src-tauri/tests/mcp_entities.rs has one test per acceptance criterion:

Create, update and merge round-trip through the reads and emit change events.
A Prop or Character made from a Line's text names that Line.
Every delete can be undone through undo.

It also covers the Lighting and slug-table tools, and checks that every tool returns noProjectOpen when no Project is open. The import and edit-with-change-event helpers moved to tests/common/mcp.rs, and mcp_script.rs uses them too.

Closes #192. With these tools, a harness can complete and tidy what script import found. ## Tools - **Reads** - `list_entities` lists the Characters, Locations, Location folders and Props. - `read_character` returns one Character with its identity fields, its Looks (each with its effective identity and default wardrobe), its Wardrobe items and its voice set. - **Characters, Looks and Wardrobe items** - Characters: `create_character`, `rename_character`, `set_character_identity`, `delete_character` and `merge_characters`. - Looks: `create_look`, `rename_look`, `set_look_identity` (the overrides), `set_look_default_wardrobe`, `set_default_look` and `delete_look`. - Wardrobe items: `create_wardrobe_item`, `rename_wardrobe_item`, `set_wardrobe_text` and `delete_wardrobe_item`. - **Locations** - Locations: `create_location`, `rename_location`, `set_location_description`, `set_location_ambience`, `delete_location` and `merge_locations`. - Location folders: `create_location_folder`, `rename_location_folder`, `delete_location_folder` and `move_location`. - **Props**: `create_prop`, `rename_prop`, `set_prop_description` and `delete_prop`. - **Lighting** - `read_lighting` returns the Lighting list with its phrases, and the slug table. - `add_lighting`, `rename_lighting`, `reorder_lighting`, `remove_lighting`, `set_lighting_phrase`, `set_slug_lighting` and `remove_slug_lighting` each return `read_lighting`. ## How the tools reply - Each edit returns the thing it changed. A tool that changes a Look or a Wardrobe item returns the Look's or item's Character. - A delete returns the undo state, and `undo` brings the deleted thing back. - A refused delete returns the core's reason. For example, a Character that speaks can't be deleted; the harness has to merge it into another Character instead. - Identity fields have the same names as in `read_character` (`ageBuild`, `distinctiveFeatures`…), and the core validates them. `set_default_look`, `set_look_default_wardrobe` and `set_wardrobe_text` go a little beyond the ticket. `set_default_look` is necessary because the core refuses to delete the default Look. The other two fill in Look and Wardrobe text that prompts use. ## Creating from a Line `create_character` and `create_prop` take an optional `fromLineId`. This works the same way as making an Entity from a selection in the script view: an unknown Line is refused, and the reply includes `sourceLineId`. The Project does not store the link, because the core keeps no link today. We agreed to match the app for now. #205 tracks storing the link. ## Tests `src-tauri/tests/mcp_entities.rs` has one test per acceptance criterion: - Create, update and merge round-trip through the reads and emit change events. - A Prop or Character made from a Line's text names that Line. - Every delete can be undone through `undo`. It also covers the Lighting and slug-table tools, and checks that every tool returns `noProjectOpen` when no Project is open. The import and edit-with-change-event helpers moved to `tests/common/mcp.rs`, and `mcp_script.rs` uses them too.

crowmaki added 2 commits

2026-10-12 05:16:52 +00:00

MCP: Entities (#192 ) 1c3457edde

- `list_entities` lists the Characters, Locations, Location folders and
  Props; `read_character` returns one Character with its identity, Looks
  (effective identity, default wardrobe), Wardrobe items and voice set.
- Create, rename, set and delete tools for Characters, Looks, Wardrobe
  items, Locations, Location folders and Props, plus `set_default_look`,
  `move_location`, and `merge_characters` / `merge_locations`. Each
  returns the thing it changed (a Look or Wardrobe item returns its
  Character); a delete returns the undo state, so `undo` can bring it back.
- `create_character` and `create_prop` take an optional `fromLineId`, as
  creating from a selection in the script view does: an unknown Line is
  refused and the reply names the Line. The Project keeps no link back to
  the Line, as in the app.
- `read_lighting` and the Lighting, phrase and slug-table tools, which
  return it.
- Identity fields are named as read_character shows them (`ageBuild`…).
- The server instructions' glossary covers Props, Location folders,
  aliases and the slug table.

Address review of #192 d6a913b6bc

- Let the core validate identity field names; the adapter only maps camelCase to its snake_case.
- Create through the from-selection commands with an optional Line, instead of switching between two commands.
- Share the find-by-id, read-after-create and current-Project steps.
- Report a serialization error in a create-from-Line reply instead of hiding it.
- Delete descriptions say a delete is refused with the reason while in use, without listing the core's rules; fromLineId says the Project does not keep the Line; merge_characters moves dialogue Lines.
- Move the import and edit-with-change helpers into tests/common/mcp.rs and use them in mcp_script.rs too.

crowmaki merged commit c99e7977a5 into main

2026-10-12 05:25:16 +00:00

crowmaki deleted branch issue-192-mcp-entities

2026-10-12 05:25:16 +00:00

crowmaki referenced this pull request from a commit

2026-10-12 05:25:18 +00:00

Merge pull request 'MCP: Entities (#192)' (#206) from issue-192-mcp-entities into main