Skip to main content
Glama
Sign In
abdulfatiraziz

fcp-mcp

by abdulfatiraziz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

fcpxml_build_timeline

Create a Final Cut Pro project from media files, titles, and markers as FCPXML, then import it into the app.

Instructions

Create a new FCP project from media files, titles and markers, as FCPXML, and import it.

Example primary: [{"path": "/clips/a.mov", "source_in": 2, "duration": 5}, {"text": "Chapter 2", "duration": 3}, {"path": "/clips/b.mov"}]. Example connected: [{"path": "/music.mp3", "at": 0, "lane": -1}].

Input Schema

NameRequiredDescriptionDefault
fpsNoFrame rate, e.g. 25, 29.97, 30. Defaults to the first video clip's.
widthNoFrame width. Defaults to the first video clip's.
heightNoFrame height. Defaults to the first video clip's.
libraryNoName of an open library, or path to a .fcpbundle (opened if closed, created if missing). Default: the open library when exactly one is open.
markersNoMarkers, to-dos and chapter markers.
primaryYesPrimary storyline in order: media clips, gaps (duration only) and titles (text).
connectedNoClips/titles connected at a timeline position: B-roll and titles above, music/VO below.
backgroundNoHex colour behind clips that don't fill the frame (e.g. "#FFFFFF" around vertical footage fitted into 16:9). Ends where a trailing gap/end card starts.
event_nameNoEvent to put the project in (created if missing).fcp-mcp
output_pathNoWhere to save the .fcpxml. Default: ~/Movies/fcp-mcp/<project>.fcpxml
project_nameYesName of the new project.
start_timecodeNoTimeline start, e.g. "01:00:00:00". Default 0.
import_into_fcpNoOpen the file in Final Cut Pro after writing it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=false, consistent with 'create a new project' and 'import it' — no contradiction. The description adds that an .fcpxml is written to disk and opened in FCP, which is useful context, but it is silent on what happens if a project of that name already exists, whether the write overwrites output_path, or what occurs when no library is open.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One purpose sentence followed by two labeled examples, with no filler. The core action is front-loaded before the illustrative payloads.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter tool that mutates disk and drives a desktop app, the description covers intent and item shapes but omits collision/overwrite behavior, the FCP-must-be-running prerequisite, and any failure modes. The rich per-parameter schema carries most of the load, but the description leaves gaps around side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the two worked examples go beyond the schema by showing how StoryItem and ConnectedItem compose into a real timeline (source_in + duration on the primary, at + lane -1 for music underneath). They clarify ordering and lane semantics in a way the JSON schema alone does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource chain: create an FCP project, serialize it as FCPXML, and import it. That distinguishes it in substance from fcpxml_import (which takes an existing file), but the description never names the sibling, so the agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the examples of primary and connected item shapes, which show what this tool is for. However, there is no explicit when-to-use guidance versus fcpxml_import, fcpxml_validate, or fcpxml_add_markers, and no stated prerequisite that FCP be running.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools