Summary

This PR adds a Model Context Protocol (MCP) server to CommandPost, enabling AI assistants (such as Claude, ChatGPT, or any MCP-compatible client) to control Final Cut Pro and macOS workflows through CommandPost's existing automation infrastructure.

The server exposes 76 tools spanning timeline editing, effects, transitions, retiming, markers, keywords, generators, titles, import/export, color correction, and arbitrary Lua scripting — all accessible over a standard JSON-RPC protocol.

Architecture

AI Assistant (Claude Code, etc.)
        │
        │ stdio (JSON-RPC / MCP protocol)
        ▼
  MCP Server (Node.js / TypeScript)
        │
        │ WebSocket (port 27480, authenticated)
        ▼
  CommandPost (Hammerspoon runtime)
        │
        │ Accessibility API + Lua scripting
        ▼
  Final Cut Pro / macOS

How It Works

1. MCP Protocol Layer (src/mcp-server/src/index.ts) — A Node.js server implementing the Model Context Protocol specification. It communicates with AI assistants via stdio using JSON-RPC, translating tool calls into CommandPost operations.

2. WebSocket Transport (src/mcp-server/src/commandpost.ts) — A WebSocket client that maintains a persistent connection to CommandPost's built-in WebSocket server. Handles message correlation via unique IDs, automatic reconnection, request timeouts, deduplication of broadcast responses, and back-pressure protection (max 100 pending requests).

3. CommandPost WebSocket Server (src/plugins/core/websocket/manager/) — Enhanced with new message types (execute, batch), token-based authentication, audit logging, and improved plugin matching. The server generates a SHA-256 session token on startup, writes it to a well-known file path, and validates every incoming message.

4. Lua Execution Environment — Tool handlers generate Lua code that runs inside CommandPost's Hammerspoon environment with full access to hs.* APIs, cp.* modules, Final Cut Pro's accessibility tree, and all registered CommandPost plugins.

Authentication

The WebSocket connection uses shared-secret authentication:

• On server start, CommandPost generates a random SHA-256 token from timestamp + random data + process ID
• The token is written to ~/Library/Application Support/CommandPost/mcp-auth-token with chmod 600
• The MCP server reads this token automatically (with a 60-second TTL cache, force-refreshed on auth failures)
• Every WebSocket message includes an auth field; messages without valid tokens are rejected
• The token can also be set via the COMMANDPOST_AUTH_TOKEN environment variable

Operation Verification

Editing tools use a withVerification wrapper that captures timeline state before and after operations:

{
  "before": { "clipCount": 4, "timecode": "00:00:15:00" },
  "after": {
    "clipCount": 5,
    "timecode": "00:00:15:00",
    "undoText": "Undo Blade",
    "clips": [...]
  },
  "verified": {
    "undoText": "Undo Blade",
    "clipDelta": 1,
    "tcChanged": false
  }
}

Three verification signals confirm success:

• undoText — FCP's own name for the last action (read via AX, not menu reads that steal focus)
• clipDelta — Change in clip count (+1 = added, -1 = removed)
• tcChanged — Whether the playhead moved

Focus Management

FCP keyboard shortcuts require the app to be frontmost. The server:

• Calls activateFinalCutPro() before shortcut-based operations
• Checks for and dismisses modal dialogs (sheets, system dialogs) that would block interaction
• Dismisses speed popovers that persist after retime operations
• Uses AX-based undo text reading instead of getMenuItems() to avoid stealing focus during verification
• Uses {plain = true} on all selectMenu calls to prevent Lua pattern matching crashes from special characters in menu item names

Dialog Handling

A handleFCPDialog helper automatically detects and handles FCP modal dialogs (e.g., "not enough extra media beyond clip edges" when applying transitions). It scans for AXSheets and AXModal windows, reads their text content, and clicks the appropriate button. This is integrated into both withVerification and individual tool handlers.

Complete Tools Reference (76 tools)

System & Connection (9 tools)

Final Cut Pro — Application (6 tools)

Final Cut Pro — Timeline (9 tools)

Final Cut Pro — Effects & Plugins (4 tools)

Final Cut Pro — Discovery (6 tools)

Final Cut Pro — Browser & Libraries (3 tools)

Final Cut Pro — Inspector & Viewer (2 tools)

Final Cut Pro — Color (1 tool)

Final Cut Pro — Export & Import (4 tools)

Final Cut Pro — Projects & Playhead (5 tools)

Final Cut Pro — Markers & Keywords (2 tools)

Final Cut Pro — Clip Operations (10 tools)

Final Cut Pro — Speed & Retime (2 tools)

Final Cut Pro — Advanced (9 tools)

Final Cut Pro — Window & Undo (3 tools)

Final Cut Pro — Workflow (1 tool)

FCP v12 Compatibility Fixes

This PR includes several fixes for Final Cut Pro v12 (12.0+):

PrimaryToolbar.lua

FCP v12 no longer wraps toolbar checkboxes in AXGroup elements — they are now direct children of the toolbar. Updated all five checkbox properties (keywordEditor, backgroundTasksWindow, browserShowing, timelineShowing, inspectorShowing) to fall back to AXDescription-based matching when the legacy AXGroup wrapper is not found. Fully backwards-compatible with pre-v12.

Menu Item Relocation

"Rename Clip" moved from the Modify menu to the Clip menu in FCP v12. The rename tool tries Clip > Rename Clip first, falling back to Modify > Rename Clip.

Lua Pattern Safety

All selectMenu calls now pass {plain = true} to disable Lua pattern matching. This prevents crashes when menu items contain special pattern characters like % (e.g., "Normal (100%)"), ., (, or ).

Plugin Name-Only Matching

findFCPXPluginBySimplifiedPath in the WebSocket message handler now supports name-only matching as a fallback. This allows matching "Cross Dissolve" without requiring the full "Dissolves/Cross Dissolve" path — important for transitions and other plugins that lack filesystem path metadata.

Defensive Nil Handling

• Contents:clipsUI() and Contents:positionClipsUI() return empty tables {} instead of nil to prevent downstream nil index errors
• Timeline:isShowing() uses a safer prop composition
• Menu finder adds nil checks before calling :gsub() and :find() on potentially nil strings

Files Changed

New Files

Modified Files

Setup

# 1. Enable WebSocket in CommandPost
defaults write org.latenitefilms.CommandPost "cp.websocket.enabled" -int 1
# Then restart CommandPost

# 2. Build the MCP server
cd src/mcp-server
npm install
npm run build

# 3. Add to Claude Code's .mcp.json
# {
#   "mcpServers": {
#     "commandpost": {
#       "command": "node",
#       "args": ["/path/to/CommandPost/src/mcp-server/dist/index.js"]
#     }
#   }
# }

# 4. Restart Claude Code session

Test Plan

• Blade cuts (3 cuts creating 4 clips) — verified clip count delta
• Timeline navigation (beginning, next edit, end, timecode) — verified timecode changes
• Select clip at playhead and by index — verified AX selection
• Apply video effect (Gaussian Blur) — verified via action handler
• Apply transition (Cross Dissolve) — verified transition count delta
• Retime slow 50% and fast 4x — verified undo text "Speed Adjustment"
• Reset to normal speed — verified undo text "Retime Reset Clip"
• Add standard and chapter markers — verified marker added
• Add keyword via Keyword Editor — verified with PrimaryToolbar v12 fix
• Rename clip — verified via Clip menu (FCP v12 location)
• Duplicate clip — verified clip count delta and undo text "Paste"
• Apply generator (Custom Solid) — verified via action handler
• Apply title (Basic Title) — verified via action handler
• Delete clip — verified clip count delta
• Undo/Redo — verified undo title changes
• Select all / select none — verified count changes