Author guided experiences with MCP

TholusOS MCP supports structured authoring of guided experiences: scenes, phases, routes, audience profiles, language selections, source references and media assignments. Start by reading the actual project, prepare a bounded change, apply it and read back the result. The assistant uses the same project model as Studio.

What the integration can do

The available operations depend on the selected project and the tools exposed by your client. Read capabilities before choosing a workflow, especially when continuing an older project.

Task	Current workflow
Inspect a project	Read project context, scene or phase detail, summaries and capability descriptors.
Create a school project in the cloud	Use manage_project with action: "create" and no destination Mac.
Edit supported content and structure	Prepare typed commands, inspect their diff and apply the returned change envelope.
Attach supported media	Prepare the attachment and follow the asset-import operation. Cloud media import can run without a Mac when enabled for the account and service.
Open a project on a Mac	Target the intended registered Mac through the project workflow.
Request native validation, simulation or preview	Use inspect_experience with an explicit selection and exact project revision.

The authoring service does not offer a general “play this in the venue” command. Native simulation, a preview image and a cloud commit describe different results. Generative media providers are not enabled by the authoring service: prepare the required media through an available production tool, then import actual files.

Read the project before editing

Read its identity, revision, capabilities and the exact scene or phase you want to change. Stable identifiers prevent ambiguous titles from directing an edit to the wrong target.

Ask the assistant:

Read the selected project and list its scenes. For the introduction, show the current facilitator instructions, active audience and language, assigned media and next-scene destination. Report any ambiguous match before changing anything.

The usual read sequence is list_projects, get_project_context and, where required, get_phase_context. get_experience_summary provides a broader overview. Use exact scene IDs after resolving a title query.

Ask for the scope explicitly. A change may apply to common content, one profile or a selected combination. Supported language layers are project-dependent; adding a language to the catalog does not automatically translate its content or supply audio.

Prepare and apply a bounded change

prepare_changes checks proposed commands against one exact snapshot and returns a diff plus the envelope needed by apply_changes. Preparation does not modify the project or acquire media.

1. Read current capabilities and the relevant command descriptors.
2. Specify the target, scope and replacement value. Keep one coherent editorial change together.
3. Call prepare_changes and inspect the diff, including inherited or shared effects.
4. Apply the returned envelope unchanged through apply_changes when the edit is authorized.
5. Use get_operation and read the affected content again to confirm the result.

For example:

Prepare a revision of the introduction’s facilitator instruction for the selected primary-school profile. Keep its public text, media, timing and route unchanged. Show the proposed text and scope. After I approve, apply the prepared change and read the saved field back.

The revision and snapshot hash prevent a prepared change from silently overwriting a newer edit. If another writer changes the project first, reread the new state and prepare again. A timed-out write should be checked using its operation ID before attempting a second write.

Some operations support a compensating edit through prepare_changes with rollbackOperationID. It is subject to current-state checks; it is not a universal undo or a substitute for preserving a project copy before major restructuring.

Create a project and open it on a Mac

A cloud school project can be created while every Mac is offline. Opening it on a Mac is a separate operation that must complete on the chosen registered device.

Use a clear request such as:

Create a new cloud school project titled “Light and shadows”. Use the school template. Leave it as a draft, then report its project ID and supported capabilities. Do not open a Mac copy or start playback.

manage_project performs the cloud creation when destinationClientInstanceID is omitted. For a native copy, first list the registered devices, then explicitly target the desired Mac. The operation stays queued until that Mac can process it.

Project duplication and capability migration through manage_project target native authoring copies. Migration creates a new project and preserves its predecessor. Use dryRun when you need to inspect a supported project operation’s effects before queueing it.

Import real media with explicit assignments

An attachment needs accessible source bytes and an unambiguous destination. A filename, a prompt or a chat attachment that the connector cannot access is insufficient to establish an imported asset.

prepare_asset_attachment prepares supported attachment parameters without fetching the file or changing the project. Submit its returned request unchanged to attach_asset. Depending on the file and service capability, the source may be a usable chat-file descriptor, a direct HTTPS file link or a supported cloud transfer link. Storage entitlement, capacity and file limits also apply.

For audio, specify its bus, start time, assigned duration and source trim. Voice needs an explicit language when the project uses a language catalog. Finished-video playback uses a shared video and the matching final mix; a waiting loop uses an independent soundtrack for the selected version. See school media preparation.

Cloud video and audio import can measure actual bytes and media metadata without a Mac online when that capability is enabled. Follow get_operation until the assignment is committed or a required action is reported. With the original owner’s current write authorization, this call can finalize the already-authorized assignment after acquisition. A transfer marked ready is not yet proof of a committed assignment.

If the assignment target changed during transfer, reread it and prepare a fresh attachment request. resume_media_import can reuse verified bytes for an eligible operation in needs_input, rather than uploading them again. Native package acquisition, saving and playback checks remain separate.

Supported document and data imports include text, Markdown, PDF, JSON, CSV and TSV within the advertised limits. A document becomes a reference or documentation material. Runtime JSON requires the supported phase-variable schema and consumer; arbitrary documents or tables do not become executable scripts.

For a bounded attachment request, try:

Read the chosen scene and phase, then prepare the supplied audio file as the English voice track for that selection. Use the supplied measured duration, start and source trim; ask for any missing timing values. Report whether it creates a new reference or replaces an existing one. Show the target and assignment before importing. After import, report the measured metadata and the cloud and Mac save states.

Request a native check or preview

inspect_experience asks an exact registered authoring Mac to validate, simulate or render an advertised preview. It needs a precise audience, language and variant selection, plus the exact project revision and snapshot hash.

Choose the smallest check that answers the question:

• Validate: ask whether the selected native project satisfies its validation rules.
• Simulate: exercise a specified branch sequence through a deterministic simulation.
• Preview: request an available source, composition or dome view at an explicit time.

Follow the operation with get_operation; preview results arrive after completion. Unsupported renderer views fail explicitly. A simulation covers its supplied choices, and a single preview frame covers its requested view and time. Inspect the returned provenance before describing the result as verified.

A useful request is:

On the selected Mac, validate the chosen primary-school profile and language at the current revision. Report the native result and unresolved issues. Do not start a live room session or use a different device.

Understand completion and readiness

Treat cloud authoring, media acquisition, native saving, rehearsal and venue operation as separate checkpoints. Each answers a different practical question.

Checkpoint	What it establishes
Cloud commit	The service stored the authorized project change.
Media measurement	The import inspected actual source bytes and recorded media properties.
Native save and acknowledgement	The identified Mac copy saved the received state.
Native reopen or inspection	The reported native operation read or checked that specific copy.
Local rehearsal	The operator observed the tested route in Studio.
Room test	The installation was checked with its actual projection, audio and relevant devices.

For ordinary edit and attachment operations, commitRecorded: true and cloudState: "serverCommitted" identify a cloud commit. saveState: "waitingForDevice" still requires the Mac. Check localReceipts, the copy identity and reopenedVerified when a saved or reopened native copy is required. Project-creation and inspection operations return their own receipts; interpret the fields actually returned.

Recover from an interrupted workflow

Use the returned error and existing operation ID to choose the next action. Reading current state before retrying avoids duplicate imports and changes based on an old project revision.

Result	Next action
REVISION_CONFLICT	Reread the target and prepare against the current revision. For retained cloud media in needs_input, use the supported resume workflow.
FILE_EXPIRED	Obtain a valid source link for the same intended file and follow the operation’s retry requirements.
QUOTA_EXCEEDED	Check the reported file, storage or operation limit before retrying; smaller requests do not fix exhausted storage.
UNSUPPORTED_FIELD	Read current project and destination-device capabilities. A newer connector description alone does not upgrade an older project.
LOCAL_VALIDATION_REQUIRED	Open or inspect the bound native copy before reporting readiness.
Native operation queued	Bring the selected registered Mac online and keep TholusOS available; do not silently target another device.

When requesting a handover, ask the assistant to report the completed checkpoints and the remaining ones. Use Prepare and run a school session for the transition from authoring to a real class, and Connect with MCP for account and connection setup.