premiere-pro-mcp 1.11.0 → 1.11.2

package/CHANGELOG.md

@@ -6,6 +6,66 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.11.2] - 2026-08-18
+
+### Added
+
+- Added a durable local project-context engine with active-sequence capture,
+  transcript/shot/audio/note enrichment, bounded retrieval, and non-mutating
+  edit-plan scaffolds. Source-media and timeline revisions are tracked
+  independently so ordinary timeline changes do not repeat expensive source
+  analysis.
+- Added a context-aware rough-cut prompt and `config://premiere-project-context`
+  resource documenting privacy, invalidation, retrieval, and preview requirements.
+
+### Fixed
+
+- `add_track` and QE-backed `add_tracks` now validate their inputs and return success
+  only after the active sequence reports the exact requested track-count increase. The
+  single-track call uses a bounded QE fallback only when the public DOM call made no
+  change, and never retries a partially applied call.
+- `overwrite_clip` now rejects invalid video and audio track indices before invoking
+  Premiere and confirms the requested source item appears at the requested frame. A
+  no-op or an unverifiable repeat placement returns an error instead of false success.
+- `trim_clip` now proves the requested source point also produced the expected visible timeline
+  edge and duration. It refuses retimed clips and, by default, trims that would strand effect
+  keyframes instead of treating source-metadata-only changes as success on Premiere Pro 26.x.
+- `split_clip` now verifies that a clip spans the requested cut and that QE produced each expected
+  left/right segment, rather than accepting any increase in track clip count. QE keyframe
+  redistribution remains explicitly unverified.
+- `remove_effect` and `remove_effect_by_name` now preflight `Component.remove()` support before
+  mutation. Unsupported Premiere 26.x components such as Essential Sound's Amplify return an
+  actionable capability error without crashing or partially removing matched effects.
+
+### Security
+
+- Native media paths are hashed before persistence, credential-like enrichment
+  metadata is discarded, stale source/timeline enrichments are rejected, and
+  context clearing remains an explicit filesystem-authorized action.
+
+### Validation
+
+- Added fail-closed CEP/QE contract coverage for trim, split, track creation, overwrite placement,
+  and component removal. Licensed Premiere Pro 26.x host confirmation remains a separate gate.
+
+## [1.11.1] - 2026-08-16
+
+### Fixed
+
+- Extensionless landing routes such as `/changelog` now resolve to their
+  exported `index.html` file instead of attempting to stream a directory. The
+  previous behavior emitted an unhandled `EISDIR` error on Linux and restarted
+  the remote HTTP process.
+- Static asset candidates are required to remain inside the landing directory
+  and resolve to regular files, and read-stream failures are handled without
+  terminating the server.
+
+### Validation
+
+- Added regression coverage for extensionless exported routes and asynchronous
+  static-file read failures. The complete release gates remain distinct from
+  validation inside a licensed Premiere host.
+
 ## [1.11.0] - 2026-08-16
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@
 
 **Give compatible AI assistants structured control over supported Adobe Premiere Pro workflows.**
 
-282 core tools across 31 modules, 3 resources, and 4 guided workflows. A connected UXP host adds 48 capability-gated tools.
+285 core tools across 32 modules, 4 resources, and 5 guided workflows. A connected UXP host adds 48 capability-gated tools.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-20.19%2B-green.svg)](https://nodejs.org)
@@ -29,22 +29,20 @@ An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that l
 "Add the B-roll clips to V2, apply a cross dissolve between each, color correct them to match the A-roll, and export a 1080p ProRes."
 ```
 
-The AI handles the entire workflow through 282 core tools spanning the supported ExtendScript, QE DOM, local media analysis, safe edit-planning, and connection-verification surfaces. A compatible, authenticated UXP panel adds 48 documented, capability-gated tools without replacing the production CEP bridge.
+The AI handles the entire workflow through 285 core tools spanning the supported ExtendScript, QE DOM, local media analysis, revisioned project-context retrieval, safe edit-planning, and connection-verification surfaces. A compatible, authenticated UXP panel adds 48 documented, capability-gated tools without replacing the production CEP bridge.
 
-### Latest release: 1.11.0
+### Latest release: 1.11.2
 
-- **Host evidence and readiness:** a bounded UXP event journal, AME terminal receipts, and
-  explicit readiness gates distinguish verified completion, pending work, and lost history.
-- **Guarded production workflows:** GUID-targeted project sessions, growing-media pause leases,
-  transactional checkpoints, and bounded media-health inspection fail closed on stale state.
-- **Timeline precision:** caption-aware track controls and source-clip trim and framing add
-  readback-verified mutations; clip-volume writes now convert dB correctly and support batches.
-- **Performance and support evidence:** a hybrid-acceleration benchmark gate and the generated
-  [supported-actions catalog](docs/supported-actions.md) document every current action and boundary.
-- **Truthful compatibility:** CEP remains the production-compatible bridge, and automated UXP
-  contracts do not claim validation inside a real Premiere host.
+- **Honest timeline mutations:** trim, split, track creation, and overwrite placement now verify
+  observable postconditions instead of trusting Premiere 26.x calls that can silently no-op.
+- **Safe effect removal:** unsupported components such as Essential Sound's Amplify return an
+  actionable capability error instead of crashing or partially removing matched effects.
+- **Durable project context:** local, revision-aware context capture and retrieval adds bounded,
+  non-mutating edit-plan scaffolds while hashing persisted native media paths.
+- **Truthful compatibility:** the fixes have automated CEP/QE contract coverage; confirmation in
+  a licensed Premiere Pro 26.x host remains a separate validation boundary.
 
-See the [v1.11.0 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.11.0)
+See the [v1.11.2 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.11.2)
 for complete details. Live installation in Premiere Pro still requires host verification.
 
 ---
@@ -53,9 +51,9 @@ for complete details. Live installation in Premiere Pro still requires host veri
 
 ### Easiest supported path: Claude Desktop
 
-1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.11.0/premiere-pro-mcp-1.11.0.mcpb).
+1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.11.2/premiere-pro-mcp-1.11.2.mcpb).
 2. In Claude Desktop, open **Settings > Extensions > Advanced settings > Install Extension**, select the downloaded bundle, and restart Claude Desktop.
-3. Download the separate [signed Premiere connector (`.zxp`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.11.0/MCPBridgeCEP.zxp). Open it with your trusted ZXP installer. If your computer has no ZXP installer, use the npm connector installer in **Advanced setup** below.
+3. Download the separate [signed Premiere connector (`.zxp`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.11.2/MCPBridgeCEP.zxp). Open it with your trusted ZXP installer. If your computer has no ZXP installer, use the npm connector installer in **Advanced setup** below.
 4. Restart Premiere, open a project, then open **Window > Extensions > MCP Bridge**.
 5. In Claude, enter: `Safely check my Premiere connection with verify_premiere_connection. Make no changes.`
 
@@ -279,11 +277,11 @@ From a clone of this repository:
 ```bash
 codex plugin marketplace add .
 codex plugin add premiere-pro@premiere-pro-mcp
-npx -y premiere-pro-mcp@1.11.0 --install-cep
+npx -y premiere-pro-mcp@1.11.2 --install-cep
 ```
 
 Restart Premiere Pro and start a new Codex session after installation. The plugin
-launches `premiere-pro-mcp@1.11.0` through `npx`; the separate CEP installation is
+launches `premiere-pro-mcp@1.11.2` through `npx`; the separate CEP installation is
 required because the MCP server communicates with the running Premiere host through
 the local bridge.
 
@@ -303,7 +301,7 @@ For Claude Code, add this repository as a marketplace and install the plugin:
 Then install the Premiere bridge and start a new Claude Code session:
 
 ```bash
-npx -y premiere-pro-mcp@1.11.0 --install-cep
+npx -y premiere-pro-mcp@1.11.2 --install-cep
 ```
 
 The Claude Code package lives in
@@ -342,7 +340,7 @@ installed separately.
 QE-backed tools are reported as `experimental` because QE is undocumented and can vary between Premiere builds. Authority availability is reported separately from implementation support, so disabling `edit`, for example, does not incorrectly label editing tools as unsupported. Static metadata never claims that a Premiere operation succeeded; use `ping` and inspect each tool result for runtime evidence.
 
 MCP `tools/list` is filtered to the active authority profile. The default
-`inspect,edit,export,filesystem` profile advertises 280 of the 282 registered
+`inspect,edit,export,filesystem` profile advertises 283 of the 285 registered
 tools and omits `execute_extendscript` and `evaluate_expression`, which require
 explicit `unsafe-script` authority. `ping` and `get_capabilities` remain visible
 under every profile so a restricted or misconfigured server can still explain
@@ -383,6 +381,23 @@ capability negotiation.
 - The server never uses menu automation, private APIs, clip-name heuristics, or
   duration changes as proof that an AI operation occurred.
 
+### Reusable project context
+
+For projects where repeatedly inspecting clips, transcripts, audio, and timeline
+placements is expensive, call `manage_project_context` with `action: "capture"`.
+The local context engine indexes a bounded active-sequence snapshot, hashes native
+project/media paths before persistence, and returns independent source, timeline,
+and combined context revisions. Add transcript passages, shot descriptions, audio
+observations, or editor notes once with `action: "enrich"`; ordinary trims and moves
+update the timeline revision without discarding unchanged source analysis.
+
+Use `search_project_context` to retrieve only evidence relevant to the current
+editing intent. `create_context_edit_plan` returns a non-mutating candidate scaffold
+and stale-state guards; exact identities must still be resolved and passed through
+`preview_edit_plan` before any application. See the [project context engine guide](docs/project-context-engine.md)
+for storage controls, privacy boundaries, invalidation behavior, and the complete
+workflow.
+
 ### Authenticated UXP connection
 
 The MCP server can accept a local UXP panel connection and invoke the UXP commands that are currently implemented:
@@ -468,7 +483,7 @@ The file-based IPC bridge is simple, reliable, and works across macOS and Window
 
 ---
 
-## Tools (282 core total; 280 under the default profile; 328 with a connected UXP bridge)
+## Tools (285 core total; 283 under the default profile; 331 with a connected UXP bridge)
 
 The [complete supported-actions catalog](docs/supported-actions.md) lists every
 registered core tool, the two tools restricted behind explicit `unsafe-script`
@@ -514,7 +529,7 @@ the tables below are a shorter workflow-oriented overview.
 | `roll_edit` / `slide_edit` / `slip_edit` | Professional trim modes (QE) |
 | `move_clip_to_track` | Move between tracks (QE) |
 | `set_clip_speed_qe` / `reverse_clip` | Speed/reverse (QE) |
-| `split_clip` / `trim_clip` / `move_clip` | Basic edits |
+| `split_clip` / `trim_clip` / `move_clip` | Basic edits; trim verifies source points and visible timeline edges |
 | `set_clip_properties` | Opacity, scale, rotation, position |
 | `link_selection` / `unlink_selection` | Link/unlink A/V |
 
@@ -526,6 +541,24 @@ the tables below are a shorter workflow-oriented overview.
 > `qeTrack.addTransition`; overlay clips remain a workaround for transitions that do not need
 > to blend adjacent source frames. See [issue #21](https://github.com/leancoderkavy/premiere-pro-mcp/issues/21).
 
+> **Verified track edits:** `add_track` and `add_tracks` validate requested counts and
+> return success only when the active sequence's track counts exactly match the request.
+> `overwrite_clip` validates both selected track indices and confirms the requested source
+> item appears at the requested frame on a target track. On a Premiere 26.x build that
+> ignores any of these calls, the MCP response is an error with the observed state rather
+> than a false success. These are automated CEP contracts, not proof of a particular
+> licensed host configuration.
+
+ `trim_clip` accepts exactly one source-relative `new_in_seconds` or `new_out_seconds` per
+call. It refuses retimed clips because CEP cannot prove their source-to-timeline mapping, then
+reads both source points and visible timeline start/end/duration before reporting success. The
+default `keyframe_policy: "reject"` stops before a trim that would leave effect keyframes beyond
+the visible clip; `keyframe_policy: "preserve"` is an explicit opt-in and reports the remaining
+count. `split_clip` verifies a spanning clip, the expected count increase, and the left/right
+cut boundaries. Its QE path cannot prove effect-keyframe redistribution, so a successful result
+labels those semantics `unverified`. These are CEP contract checks, not validation in a licensed
+Premiere Pro 26.x host.
+
 ### Effects & Color (8)
 
 | Tool | Description |
@@ -536,6 +569,19 @@ the tables below are a shorter workflow-oriented overview.
 | `apply_lut` | Apply LUT files |
 | `stabilize_clip` | Warp Stabilizer with configurable settings |
 
+> **Premiere 26.x component removal:** `remove_effect` and `remove_effect_by_name`
+> require the CEP `Component.remove()` method. Some 26.x components, including
+> Essential Sound's **Amplify**, do not expose that method. The tools return an
+> actionable capability error and leave the component unchanged; use Effect Controls
+> to remove it manually. The QE DOM has no safe targeted-removal fallback.
+
+> **Essential Sound audio automation:** Essential Sound can write ducking or level
+> automation to an **Amplify** component rather than the clip's **Volume > Level**.
+> `adjust_audio_levels`, `set_clip_volume`, and `get_clip_volume` operate only on
+> Volume > Level, so they do not read, change, or verify Amplify automation. Inspect
+> the clip's components (or Effect Controls) before treating a Volume readback as the
+> clip's final gain.
+
 ### Keyframes (8)
 
 | Tool | Description |
@@ -694,6 +740,8 @@ Then connect with:
 | `PREMIERE_DEFAULT_SEQUENCE_PRESET` | Override the auto-discovered `.sqpreset` used by `create_sequence` | auto-discovered |
 | `PREMIERE_MCP_CAPABILITIES` | Comma-separated authority profile; add `unsafe-script` only when raw scripting is required | `inspect,edit,export,filesystem` |
 | `PREMIERE_MCP_DEBUG` | Set to `1` (or `true`) to emit verbose server diagnostics to stderr | unset |
+| `PREMIERE_CONTEXT_BACKEND` | Local project-context store: `auto`, `sqlite`, `json`, or `memory` | `auto` |
+| `PREMIERE_CONTEXT_DIR` | Override the local project-context storage directory | OS application-data directory |
 | `PORT` | HTTP port (HTTP/SSE transport only) | `3000` |
 | `MCP_AUTH_TOKEN` | Bearer token required by the HTTP transport | unset |
 | `ALLOW_UNAUTHENTICATED` | Set to `1` to run HTTP without auth (unsafe; throwaway instances only) | unset |
@@ -717,7 +765,7 @@ premiere-pro-mcp/
 ├── src/
 │   ├── index.ts                 # Entry point — stdio transport setup
 │   ├── http-server.ts           # Entry point — HTTP/SSE transport (Fly.io / remote)
-│   ├── server.ts                # MCP server — registers 280 tools, filtered by authority profile
+│   ├── server.ts                # MCP server — registers 285 tools, filtered by authority profile
 │   ├── bridge/
 │   │   ├── file-bridge.ts       # File-based IPC (write .jsx, poll .json)
 │   │   └── script-builder.ts    # ExtendScript generator with ES3 helpers

package/cep-plugin/CSXS/manifest.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.premiere.bridge" ExtensionBundleVersion="1.11.0" ExtensionBundleName="MCP Bridge">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.premiere.bridge" ExtensionBundleVersion="1.11.2" ExtensionBundleName="MCP Bridge">
   <ExtensionList>
-    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.11.0"/>
-    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.11.0"/>
+    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.11.2"/>
+    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.11.2"/>
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

package/cep-plugin/index.html

@@ -81,7 +81,7 @@
     <section class="update-section" aria-live="polite">
       <div class="update-copy">
         <span class="section-label">Connector updates</span>
-        <strong id="updateTitle">Version 1.11.0</strong>
+        <strong id="updateTitle">Version 1.11.2</strong>
         <span id="updateDetail">Checking for updates…</span>
       </div>
       <button id="btnUpdate" class="button button-update" onclick="handleUpdateClick()" type="button" disabled>

package/cep-plugin/updater.cjs

@@ -7,7 +7,7 @@
 })(this, function () {
   "use strict";
 
-  var CURRENT_VERSION = "1.11.0";
+  var CURRENT_VERSION = "1.11.2";
   var LATEST_RELEASE_API =
     "https://api.github.com/repos/leancoderkavy/premiere-pro-mcp/releases/latest";
   var RELEASES_URL =

package/dist/context/project-context-resource.d.ts

@@ -0,0 +1,2 @@
+export declare const PROJECT_CONTEXT_RESOURCE: string;
+//# sourceMappingURL=project-context-resource.d.ts.map

package/dist/context/project-context-resource.js

@@ -0,0 +1,29 @@
+export const PROJECT_CONTEXT_RESOURCE = JSON.stringify({
+    version: 1,
+    purpose: "Reuse clip, audio, transcript, shot, and timeline context without sending the full Premiere project on every model turn.",
+    workflow: [
+        "Call manage_project_context with action=capture for the active sequence.",
+        "Add expensive analysis once with action=enrich, using source_revision and timeline_revision guards when available.",
+        "Call search_project_context with the user's edit intent and only the relevant context kinds.",
+        "Use create_context_edit_plan to produce evidence candidates and expected revision guards.",
+        "Re-capture if the sequence changed, resolve exact identities, then use preview_edit_plan before apply_edit_plan.",
+    ],
+    revisionRules: {
+        sourceRevision: "Changes only when captured source-media identity changes; transcript, shot, and audio enrichments are reusable while it matches.",
+        timelineRevision: "Changes when timeline placement changes; it guards plans without invalidating unchanged source analysis.",
+        contextRevision: "Covers source state, timeline state, and enrichment content.",
+    },
+    privacy: [
+        "Context is stored locally and only after an explicit tool call.",
+        "Captured native media paths are hashed before persistence and are not returned by search.",
+        "Do not store credentials, unrelated customer data, or sensitive notes that are unnecessary for editing.",
+        "Use manage_project_context action=clear when the local context is no longer needed.",
+    ],
+    boundaries: [
+        "Capture indexes active-sequence structure and source identity; it does not transcribe or visually analyze footage.",
+        "Premiere transcript import/export support does not expose a documented API for starting Speech-to-Text.",
+        "create_context_edit_plan is non-mutating and does not prove that a candidate is editorially correct.",
+        "Every mutation still requires current Premiere identities, preview, authority checks, and post-state verification.",
+    ],
+}, null, 2);
+//# sourceMappingURL=project-context-resource.js.map

package/dist/context/project-context-store.d.ts

@@ -0,0 +1,79 @@
+export declare const PROJECT_CONTEXT_SCHEMA_VERSION = 1;
+export declare const MAX_CONTEXT_RECORDS = 10000;
+export declare const MAX_CONTEXT_TEXT_LENGTH = 20000;
+export type ProjectContextKind = "project" | "sequence" | "source" | "timeline" | "transcript" | "shot" | "audio" | "note";
+export interface ProjectContextRecord {
+    id: string;
+    kind: ProjectContextKind;
+    name: string;
+    text: string;
+    keywords: string[];
+    sequenceId?: string;
+    sourceId?: string;
+    timelineItemId?: string;
+    startSeconds?: number;
+    endSeconds?: number;
+    trackType?: "video" | "audio";
+    trackIndex?: number;
+    sourceRevision?: string;
+    timelineRevision?: string;
+    mediaPathHash?: string;
+    metadata?: Record<string, unknown>;
+    indexedAt: string;
+}
+export interface ProjectContextDocument {
+    schemaVersion: typeof PROJECT_CONTEXT_SCHEMA_VERSION;
+    projectId: string;
+    projectName: string;
+    projectPathHash?: string;
+    revision: string;
+    sourceRevision: string;
+    timelineRevision: string;
+    updatedAt: string;
+    records: ProjectContextRecord[];
+}
+export interface ProjectContextSummary {
+    projectId: string;
+    projectName: string;
+    revision: string;
+    sourceRevision: string;
+    timelineRevision: string;
+    recordCount: number;
+    updatedAt: string;
+}
+export type ContextBackendName = "sqlite" | "json" | "memory";
+export declare function defaultProjectContextDirectory(): string;
+export interface ProjectContextRepositoryOptions {
+    backend?: "auto" | ContextBackendName;
+    directory?: string;
+}
+export declare class ProjectContextRepository {
+    private readonly options;
+    private backendPromise?;
+    constructor(options?: ProjectContextRepositoryOptions);
+    private createBackend;
+    private backend;
+    backendName(): Promise<ContextBackendName>;
+    get(projectId: string): Promise<ProjectContextDocument | undefined>;
+    put(document: ProjectContextDocument): Promise<void>;
+    delete(projectId: string): Promise<boolean>;
+    list(): Promise<ProjectContextSummary[]>;
+    close(): Promise<void>;
+}
+export interface ProjectContextSearchOptions {
+    query: string;
+    sequenceId?: string;
+    kinds?: ProjectContextKind[];
+    limit?: number;
+}
+export interface ProjectContextSearchResult {
+    score: number;
+    record: ProjectContextRecord;
+    matchedTerms: string[];
+}
+export declare function searchProjectContext(document: ProjectContextDocument, options: ProjectContextSearchOptions): ProjectContextSearchResult[];
+export declare function contextRevision(sourceRevision: string, timelineRevision: string, records: ProjectContextRecord[]): string;
+export declare function stableContextId(...parts: unknown[]): string;
+export declare function normalizeContextText(value: unknown): string;
+export declare function normalizeContextKeywords(value: unknown): string[];
+//# sourceMappingURL=project-context-store.d.ts.map