MCP / Tools / Core Project / project_mutate

project_mutate

writebetaauth: project:writeapproval: suggeststatus: v1

Create or update project-level metadata, settings, and defaults, returning compact stable project identity for follow-up MCP calls. Do not request the full project scaffold during normal agent workflows.

When to use

Use for project creation or project-level settings changes.
Use `operation=delete_visual_style_reference` to remove an uploaded master style reference from the project default visual style, or pass `project_visual_style_id` for a specific project visual style.
For `single_scene` projects, use `template_settings.story_format.target_duration_seconds` to set the story length at create time or before story generation (allowed values: 15, 30, 60, 90, 120).
For `micro_drama` projects, use `template_settings.story_format.target_duration_seconds` to set the canonical episode length at create time or before episode generation (allowed values: 60, 90, 120, 180, 240). These selections resolve to authored ranges rather than exact runtimes.
On create, keep the compact returned `project_id` and use `project_canon_summary` / `template_manifest` resource links for follow-up inspection.

When not to use

Do not use for story cards, scenes, or screenplay text changes.
Do not set `include_project=true` just to inspect the scaffold after create; create always returns compact identity and ignores that flag. Use resource links instead.

Examples

“Create a new movie project from the movie template.”
“Create a new project and keep the returned project_id for later tool calls.”
“Create a `single_scene` project with `template_settings: {"story_format": {"target_duration_seconds": 15}}` when the user asks for 15-second stories.”
“Create or update a `micro_drama` project with `template_settings: {"story_format": {"target_duration_seconds": 180}}` for an authored 150-215 second episode range.”
“Create a new project and read the returned project_canon_summary resource when you need the scaffolded card library.”
“Delete a project visual-style reference image after inspecting `visual_style_effective`.”

Anti-examples

Change dialogue in scene 4.
Upload a new style reference image; use `asset_upload(target_type=project_visual_style_asset)`.
Create a project with `include_project=true` to inspect all template cards. Create ignores that flag; use default create, keep `project_id`, then read `project_canon_summary` or `template_manifest`.

Workflows

Switch behavior by setting the operation input field.

Workflow	Phases	Calls
`create`
`rename`
`template_settings`
`delete_visual_style_reference`

Backend capabilities

project.mutate

Linked resources

Tool calls may return resource_links pointing at these resource families.

project_canon_summary

Input schema

project_mutate input

{
  "$ref": "./project.mutate.input.json"
}

Output schema

project_mutate output

{
  "$ref": "./project.mutate.output.json"
}