MCP: References and viewing images (#194) #208

Merged

crowmaki merged 2 commits from issue-194-mcp-references into main

2026-10-14 02:11:08 +00:00

crowmaki commented

2026-10-13 06:55:02 +00:00

Owner

Closes #194. Part of #157.

What changed

Read: read_reference_set returns a set's Tiles, each Tile's versions (generation or import provenance, lockedIn) and its Lock snapshots. list_location_reference_sets returns a Location's sets, one per Lighting, with the Location's own note and the note in force.
Tiles: add_tile and remove_tile both return the set.
Make versions: generate_tile (prompt) and edit_tile (instruction, ordered references, optional seed) return { jobId, version }. A reference can be any image the Project holds: a Reference version, Keyframe, Panel, Source sheet or Take frame. These use the existing EditSourceDto, which now also derives JsonSchema.
Import: import_tile_image makes the file a Source sheet and crops the whole sheet into the Tile, so the version has ordinary import provenance. Importing the same image again returns the existing version. import_source_sheet imports a sheet. import_voice_clip takes a Character id and imports into that Character's voice set.
Lock: lock_reference_set locks the set. roll_back_reference_set makes a new snapshot that copies an earlier snapshot's pick.
Atlas: preview_atlas takes 1 to 3 Look ids.
view_image takes a typed reference: referenceVersion, sourceSheet, atlas (by lookIds) or panel. It returns MCP image content scaled down to a long edge of maxSize, default 1024. Scaled images come back as PNG; images that already fit come back as stored. With saveTo (an absolute path) it writes the full-resolution stored bytes there and returns the path, media type and size. Keyframes and Take frames are left to later slices.
Core: ProjectSession::import_tile_image imports and crops as one command and refuses an unknown Tile before it imports anything. reference_image resolves an image reference the same way an Edit does. atlas_image reads a cached Atlas.

Beyond the issue

get_project now shows editReferenceLimit, so a harness knows how many references edit_tile takes.

Review notes

An Atlas is viewed by its Look ids, not its cache key. If the cache row was dropped (ADR-0005), the Atlas is built again.
The new ApiImpl methods are plain methods, not on the RPC trait, as job_statuses was for #193. The UI has no use for them yet.

Tests

src-tauri/tests/mcp_references.rs has 11 tests at the MCP boundary:

generate → wait_for_jobs → view_image → Edit with references and a seed → lock
import provenance, and that importing again makes nothing new
refusal of a relative path, a missing file, and an unknown Tile (no sheet is imported)
view_image downscaling by default and with maxSize, saveTo writing the full-resolution file, and a relative saveTo and unknown id refused
rolling back changes the read
Location sets per Lighting with Tile add and remove
voice clip import, and refusal to view a clip as an image
Atlas preview and view
viewing a Panel
get_project showing editReferenceLimit

The full workspace suite passes. Clippy shows no warnings in the changed code.

Closes #194. Part of #157. ## What changed - **Read:** `read_reference_set` returns a set's Tiles, each Tile's versions (generation or import provenance, `lockedIn`) and its Lock snapshots. `list_location_reference_sets` returns a Location's sets, one per Lighting, with the Location's own note and the note in force. - **Tiles:** `add_tile` and `remove_tile` both return the set. - **Make versions:** `generate_tile` (prompt) and `edit_tile` (instruction, ordered `references`, optional `seed`) return `{ jobId, version }`. A reference can be any image the Project holds: a Reference version, Keyframe, Panel, Source sheet or Take frame. These use the existing `EditSourceDto`, which now also derives `JsonSchema`. - **Import:** `import_tile_image` makes the file a Source sheet and crops the whole sheet into the Tile, so the version has ordinary import provenance. Importing the same image again returns the existing version. `import_source_sheet` imports a sheet. `import_voice_clip` takes a Character id and imports into that Character's voice set. - **Lock:** `lock_reference_set` locks the set. `roll_back_reference_set` makes a new snapshot that copies an earlier snapshot's pick. - **Atlas:** `preview_atlas` takes 1 to 3 Look ids. - **`view_image`** takes a typed reference: `referenceVersion`, `sourceSheet`, `atlas` (by `lookIds`) or `panel`. It returns MCP image content scaled down to a long edge of `maxSize`, default 1024. Scaled images come back as PNG; images that already fit come back as stored. With `saveTo` (an absolute path) it writes the full-resolution stored bytes there and returns the path, media type and size. Keyframes and Take frames are left to later slices. - **Core:** `ProjectSession::import_tile_image` imports and crops as one command and refuses an unknown Tile before it imports anything. `reference_image` resolves an image reference the same way an Edit does. `atlas_image` reads a cached Atlas. ## Beyond the issue `get_project` now shows `editReferenceLimit`, so a harness knows how many references `edit_tile` takes. ## Review notes - An Atlas is viewed by its Look ids, not its cache key. If the cache row was dropped (ADR-0005), the Atlas is built again. - The new `ApiImpl` methods are plain methods, not on the RPC trait, as `job_statuses` was for #193. The UI has no use for them yet. ## Tests `src-tauri/tests/mcp_references.rs` has 11 tests at the MCP boundary: - generate → `wait_for_jobs` → `view_image` → Edit with references and a seed → lock - import provenance, and that importing again makes nothing new - refusal of a relative path, a missing file, and an unknown Tile (no sheet is imported) - `view_image` downscaling by default and with `maxSize`, `saveTo` writing the full-resolution file, and a relative `saveTo` and unknown id refused - rolling back changes the read - Location sets per Lighting with Tile add and remove - voice clip import, and refusal to view a clip as an image - Atlas preview and view - viewing a Panel - `get_project` showing `editReferenceLimit` The full workspace suite passes. Clippy shows no warnings in the changed code.

crowmaki added 2 commits

2026-10-13 06:55:02 +00:00

MCP: References and viewing images (#194 ) b698f6ff46

Tools to read Reference sets and a Location's sets per Lighting, add and
remove Tiles, generate and Edit Tiles, import an image as a Tile version
(through a Source sheet and a whole-image crop), import Source sheets and
voice clips, lock and roll back Reference sets, and preview an Atlas.

view_image shows a Reference version, Source sheet, Atlas or Panel as MCP
image content, scaled down to a longest edge of 1024 by default, or writes
the full-resolution image to saveTo.

get_project now shows editReferenceLimit.

Address review of #194 d4ef47a610

Importing an image as a Tile version is one studio-core command, so the
adapter no longer re-derives which version an unchanged crop left. An Atlas
is viewed by its Looks, so a dropped cache entry is built again. view_image
writes saveTo off the async runtime.

crowmaki merged commit 2a8b623f35 into main

2026-10-14 02:11:08 +00:00

crowmaki deleted branch issue-194-mcp-references

2026-10-14 02:11:08 +00:00

crowmaki referenced this pull request from a commit

2026-10-14 02:11:09 +00:00

Merge pull request 'MCP: References and viewing images (#194)' (#208) from issue-194-mcp-references into main