premiere-pro-mcp 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -6,6 +6,49 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.18.0] - 2026-09-23
+
+### Added
+
+- MOGRT text recipes default to `text_controls: "full"`: each text layer exposes
+  Font Size, Stroke Width, Fill Color, and Stroke Color controls plus named
+  Position, Scale, Rotation, Anchor Point, and Opacity Essential Graphics
+  controls. The create result reads back source-comp controller names.
+  `text_only` keeps the previous behavior. Font-family editing is not scriptable
+  and is reported as a known gap. (#618)
+- `media_placeholder` MOGRT recipe imports a workspace-contained PNG, JPEG, MOV,
+  or MP4, requests a replaceable Essential Graphics media slot, and exposes its
+  transform controls. Not verified on a live After Effects or Premiere host.
+  (#619)
+- `import_mogrt` accepts `text_values`, writes each named text control after
+  insertion (replacing only the text value so styling is kept), and reports
+  `verified`, `mismatch`, `missing_property`, or `committed_unverified` per
+  field. `get_mogrt_component` returns `textValue` for every parameter and an
+  optional `expected_values` audit that flags stale Headline text. (#617)
+
+### Fixed
+
+- `encode_file` and `encode_project_item` pass natively typed arguments (String
+  paths, Boolean removal flag, Time in/out), fixing "Illegal Parameter type";
+  `encode_file` fails early when the preset file is missing. (#615)
+- `set_xmp_metadata` passes numeric `XMPConst` options to
+  `XMPUtils.appendProperties`, fixing "Bad argument list". (#611)
+- `manage_proxies` auto-discovery skips "Same as Project" proxy presets whose
+  output never reached `output_path`, and asks for `preset_path` when no safe
+  preset exists. (#610)
+- `manage_metadata_uxp` and `create_subclip_uxp` find items inside nested bins.
+  (#612, #613)
+- `set_scale_to_frame_size` accepts timeline clip IDs and reports `verified` or
+  `committed_unverified`. (#614)
+
+### Known limitations
+
+- The Essential Graphics panel can display a stale Headline after a MOGRT text
+  write. The tools read stored values and cannot refresh the host panel (#616
+  remains open).
+- These fixes are covered by mocked automated tests only; they are not verified
+  on a licensed Premiere or After Effects host.
+
 ## [1.17.0] - 2026-09-21
 
 ### Added

package/README.md

@@ -108,10 +108,10 @@ The current source exposes 384 core tools for supported workflow steps spanning
 
 <a id="latest-release"></a>
 
-### Latest release: 1.17.0
+### Latest release: 1.18.0
 
-The published v1.16.4 npm artifact contains **381 core tools**, 379 in its default profile,
-and 474 with a compatible UXP connection. The development catalog above can include
+The published v1.17.0 npm artifact contains **384 core tools**, 382 in its default profile,
+and 477 with a compatible UXP connection. The development catalog above can include
 unreleased work. See the [versioned facts and package provenance](https://premiere-pro-mcp.com/facts/).
 
 ### Try a bounded workflow
@@ -160,7 +160,7 @@ if the connection is unavailable.
   local Premiere processes. See the generated [supported action catalog](docs/supported-actions.md)
   for individual capability and verification contracts.
 
-See the [v1.17.0 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.17.0)
+See the [v1.18.0 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.18.0)
 for complete details. Live installation in Premiere Pro still requires host verification.
 
 ### Current MCP protocol support
@@ -208,7 +208,7 @@ their bins, media rules, and organization rules before a facility uses one.
 > ### Install the published package (verify the name)
 >
 > ```bash
-> npm i -g premiere-pro-mcp@1.17.0
+> npm i -g premiere-pro-mcp@1.18.0
 > ```
 >
 > This repository publishes only **`premiere-pro-mcp`**. A differently named package (`adobe-premiere-pro-mcp`) may also declare a `premiere-pro-mcp` executable. Before configuring a client, confirm:
@@ -216,7 +216,7 @@ their bins, media rules, and organization rules before a facility uses one.
 > | Check | Expected |
 > | --- | --- |
 > | Package name | `premiere-pro-mcp` (not `adobe-premiere-pro-mcp`) |
-> | Version | `1.17.0` |
+> | Version | `1.18.0` |
 > | Homepage / repo | https://premiere-pro-mcp.com/ · https://github.com/leancoderkavy/premiere-pro-mcp |
 >
 > ```bash
@@ -229,9 +229,9 @@ their bins, media rules, and organization rules before a facility uses one.
 
 ### Easiest supported path: Claude Desktop
 
-1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.17.0/premiere-pro-mcp-1.17.0.mcpb).
+1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.18.0/premiere-pro-mcp-1.18.0.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.17.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.18.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.
 4. Restart Premiere, open a project, then open **Window > Extensions > MCP for Adobe Premiere Pro**.
 5. In Claude, enter: `Safely check my Premiere connection with verify_premiere_connection. Make no changes.`
 
@@ -531,11 +531,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.16.4 --install-cep
+npx -y premiere-pro-mcp@1.17.0 --install-cep
 ```
 
 Restart Premiere Pro and start a new Codex session after installation. The plugin
-launches `premiere-pro-mcp@1.16.4` through `npx`; the separate CEP installation is
+launches `premiere-pro-mcp@1.17.0` through `npx`; the separate CEP installation is
 required because the MCP server communicates with the running Premiere host through
 the local bridge.
 
@@ -566,7 +566,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.16.4 --install-cep
+npx -y premiere-pro-mcp@1.17.0 --install-cep
 ```
 
 The Claude Code package lives in

package/after-effects-cep-plugin/CSXS/manifest.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.aftereffects.bridge" ExtensionBundleVersion="1.17.0" ExtensionBundleName="MCP for Adobe After Effects">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.aftereffects.bridge" ExtensionBundleVersion="1.18.0" ExtensionBundleName="MCP for Adobe After Effects">
   <ExtensionList>
-    <Extension Id="com.mcp.aftereffects.bridge.panel" Version="1.17.0"/>
+    <Extension Id="com.mcp.aftereffects.bridge.panel" Version="1.18.0"/>
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

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.17.0" ExtensionBundleName="MCP for Adobe Premiere Pro">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.premiere.bridge" ExtensionBundleVersion="1.18.0" ExtensionBundleName="MCP for Adobe Premiere Pro">
   <ExtensionList>
-    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.17.0"/>
-    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.17.0"/>
+    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.18.0"/>
+    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.18.0"/>
   </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">MCP updates</span>
-        <strong id="updateTitle">Version 1.17.0</strong>
+        <strong id="updateTitle">Version 1.18.0</strong>
         <span id="updateDetail">Checking the global MCP server and connector release…</span>
       </div>
       <button id="btnUpdate" class="button button-update" onclick="handleUpdateClick()" type="button" aria-describedby="updateDetail" disabled>

package/cep-plugin/updater.cjs

@@ -7,7 +7,7 @@
 })(this, function () {
   "use strict";
 
-  var CURRENT_VERSION = "1.17.0";
+  var CURRENT_VERSION = "1.18.0";
   var PACKAGE_NAME = "premiere-pro-mcp";
   var LATEST_PACKAGE_API = "https://registry.npmjs.org/" + PACKAGE_NAME;
   var LATEST_RELEASE_API =

package/dist/bridge/script-builder.js

@@ -520,17 +520,29 @@ function __findH264Preset() {
   return candidates[0].path;
 }
 
-function __findProxyPreset() {
+// Candidate presets for manage_proxies auto-discovery, in preference order:
+// Premiere's IngestPresets/Proxy files first, then AME's H.264 system presets.
+// Adobe ships the Proxy folder presets with a "Same as Project" destination, so
+// the TypeScript handler must content-scan every candidate (gzip-aware) before
+// using one. ExtendScript cannot inflate gzipped .epr files, so no filtering here.
+function __listProxyPresetCandidates() {
+  var out = [];
   var ppro = __adobeAppFolders("Adobe Premiere Pro");
   for (var i = 0; i < ppro.length; i++) {
     var proxyDir = __adobeApplicationResourceFolder(ppro[i], "Settings/IngestPresets/Proxy");
     var eprs = __collectEprFiles(proxyDir, []);
-    if (eprs.length) {
-      eprs.sort(function(a, b) { return a.displayName < b.displayName ? -1 : 1; });
-      return eprs[0].fsName;
+    eprs.sort(function(a, b) { return a.displayName < b.displayName ? -1 : 1; });
+    for (var e = 0; e < eprs.length; e++) out.push(eprs[e].fsName);
+  }
+  var presets = __collectAllPresets();
+  for (var p = 0; p < presets.length; p++) {
+    var haystack = (presets[p].name + " " + presets[p].format).toLowerCase();
+    if (presets[p].path.indexOf("IngestPresets") !== -1) continue;
+    if (haystack.indexOf("h264") !== -1 || haystack.indexOf("h.264") !== -1 || haystack.indexOf("48323634") !== -1) {
+      out.push(presets[p].path);
     }
   }
-  return "";
+  return out;
 }
 
 function __findStillPreset(outputPath) {

package/dist/http-server.js

@@ -35,7 +35,7 @@ import { toNodeHandler } from "@modelcontextprotocol/node";
 import { createMcpHandler } from "@modelcontextprotocol/server";
 import { createServer } from "./server.js";
 import { cleanupTempDir, getTempDir } from "./bridge/file-bridge.js";
-import { getTelemetry } from "./telemetry.js";
+import { getTelemetry, telemetryErrorType } from "./telemetry.js";
 import { createHomepageExperiment, injectFirstPaintExposure } from "./homepage-experiment.js";
 import { shouldGzipLanding } from "./landing-compression.js";
 import { LandingDocumentRenderer, assertLandingDocumentSize, readBoundedUtf8, readLandingDocumentSettings, } from "./landing-documents.js";
@@ -482,7 +482,7 @@ const httpServer = http.createServer(async (req, res) => {
             method: req.method ?? "unknown",
             status_code: 500,
             duration_ms: Date.now() - requestStartedAt,
-            error_type: err instanceof Error ? err.name : "UnknownError",
+            error_type: telemetryErrorType(err),
         });
         console.error("[premiere-pro-mcp] Request error:", err);
         if (!res.headersSent) {

package/dist/server.js

@@ -67,7 +67,7 @@ import { buildPremiereInstructions } from "./workflows/agent-instructions.js";
 import { WORKFLOW_PROMPTS, WORKFLOW_RESOURCE } from "./workflows/catalog.js";
 import { annotationsForTool, structuredToolResult, } from "./workflows/tool-metadata.js";
 import { isToolInSelectedPacks, resolveToolPacks, } from "./workflows/tool-packs.js";
-import { getTelemetry } from "./telemetry.js";
+import { getTelemetry, telemetryErrorType } from "./telemetry.js";
 import { z } from "zod";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -360,7 +360,7 @@ export function createServer(bridgeOptions, serverOptions = {}) {
                     tool: name,
                     outcome: "failed",
                     duration_ms: Date.now() - startedAt,
-                    error_type: err instanceof Error ? err.name : "UnknownError",
+                    error_type: telemetryErrorType(err),
                 });
                 return {
                     structuredContent: structuredToolResult(name, false, undefined, err instanceof Error ? err.message : String(err)),

package/dist/telemetry.d.ts

@@ -4,6 +4,8 @@ export interface Telemetry {
     capture(event: string, properties?: TelemetryProperties): void;
     shutdown(): Promise<void>;
 }
+/** Error names are mutable and may contain host data; never transmit them raw. */
+export declare function telemetryErrorType(error: unknown): string;
 /**
  * Activation telemetry is deliberately narrower than operational tool
  * telemetry. Emit it only after the read-only connection check has confirmed

package/dist/telemetry.js

@@ -1,5 +1,13 @@
 import { randomUUID } from "node:crypto";
 import { PostHog } from "posthog-node";
+/** Error names are mutable and may contain host data; never transmit them raw. */
+export function telemetryErrorType(error) {
+    if (!(error instanceof Error))
+        return "UnknownError";
+    return ["Error", "TypeError", "RangeError", "SyntaxError", "ReferenceError", "URIError", "EvalError", "AggregateError"].includes(error.name)
+        ? error.name
+        : "Error";
+}
 /**
  * Activation telemetry is deliberately narrower than operational tool
  * telemetry. Emit it only after the read-only connection check has confirmed
@@ -59,6 +67,7 @@ export function getTelemetry() {
         `server-${randomUUID()}`;
     const client = new PostHog(apiKey, {
         host,
+        disableGeoip: true,
         // MCP servers may be idle for long stretches. Flush each bounded operational
         // event promptly so a low-volume deployment remains observable.
         flushAt: 1,

package/dist/tools/advanced.d.ts

@@ -567,11 +567,19 @@ export declare function getAdvancedTools(bridgeOptions: BridgeOptions): {
                     type: string;
                     description: string;
                 };
+                expected_values: {
+                    type: string;
+                    description: string;
+                    additionalProperties: {
+                        type: string;
+                    };
+                };
             };
             required: string[];
         };
         handler: (args: {
             node_id: string;
+            expected_values?: Record<string, string>;
         }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
     };
 };

package/dist/tools/advanced.js

@@ -1,5 +1,6 @@
 import { buildToolScript, escapeForExtendScript, } from "../bridge/script-builder.js";
 import { sendCommand } from "../bridge/file-bridge.js";
+import { compareMogrtText, extractMogrtText, summarizeMogrtText, validateMogrtTextMap } from "./mogrt-text.js";
 import { SPEED_UNAVAILABLE_DESCRIPTION, SPEED_UNAVAILABLE_ERROR } from "./timeline.js";
 export function getAdvancedTools(bridgeOptions) {
     return {
@@ -1487,7 +1488,7 @@ export function getAdvancedTools(bridgeOptions) {
             },
         },
         get_mogrt_component: {
-            description: "Get MOGRT (Motion Graphics Template) component parameters from a clip",
+            description: "Get MOGRT (Motion Graphics Template) component parameters from a clip. Each parameter includes textValue (visible text extracted from textEditValue when present). Pass expected_values to audit text controls such as Headline; the result flags verified, mismatch, or missing_property per field. Reads the stored property, not the Essential Graphics panel display, which Premiere can show stale (host UI behavior this tool cannot refresh).",
             parameters: {
                 type: "object",
                 properties: {
@@ -1495,10 +1496,16 @@ export function getAdvancedTools(bridgeOptions) {
                         type: "string",
                         description: "Node ID of the MOGRT clip on the timeline",
                     },
+                    expected_values: {
+                        type: "object",
+                        description: "Optional read-only audit map of MOGRT text parameter display names to the text each should contain (for example { \"Headline\": \"Chapter 3\" }). Result audit.status is verified, mismatch, or missing_property.",
+                        additionalProperties: { type: "string" },
+                    },
                 },
                 required: ["node_id"],
             },
             handler: async (args) => {
+                const expected = validateMogrtTextMap(args.expected_values, "expected_values");
                 const script = buildToolScript(`
           var result = __findClip("${escapeForExtendScript(args.node_id)}");
           if (!result) return __error("Clip not found");
@@ -1517,7 +1524,27 @@ export function getAdvancedTools(bridgeOptions) {
           
           return __result({ clipName: result.clip.name, parameters: params });
         `);
-                return sendCommand(script, bridgeOptions);
+                const response = await sendCommand(script, bridgeOptions);
+                if (!response.success)
+                    return response;
+                const data = (response.data ?? {});
+                const rawParams = Array.isArray(data.parameters) ? data.parameters : [];
+                const parameters = rawParams.map((p) => ({ ...p, textValue: extractMogrtText(p.value) }));
+                if (!expected)
+                    return { ...response, data: { ...data, parameters } };
+                const checks = compareMogrtText(expected, parameters);
+                return {
+                    ...response,
+                    data: {
+                        ...data,
+                        parameters,
+                        audit: {
+                            status: summarizeMogrtText(checks),
+                            checks,
+                            scope: "Stored MOGRT property values only; the Essential Graphics panel display is not read.",
+                        },
+                    },
+                };
             },
         },
     };

package/dist/tools/export.d.ts

@@ -790,7 +790,11 @@ export declare function getExportTools(bridgeOptions: BridgeOptions): {
             proxy_path?: string;
             output_path?: string;
             preset_path?: string;
-        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult | {
+            success: boolean;
+            error: string;
+            skippedPresetCount: number;
+        }>;
     };
 };
 //# sourceMappingURL=export.d.ts.map

package/dist/tools/export.js

@@ -1331,7 +1331,7 @@ export function getExportTools(bridgeOptions) {
             outputFile.fsName,
             "${escapeForExtendScript(args.preset_path)}",
             app.encoder.ENCODE_IN_TO_OUT,
-            ${args.remove_on_completion !== false ? 1 : 0}
+            ${args.remove_on_completion !== false ? "true" : "false"}
           );
           if (!jobId || String(jobId) === "0") return __error("Adobe Media Encoder did not queue the project-item export.");
           app.encoder.startBatch();
@@ -1411,13 +1411,18 @@ export function getExportTools(bridgeOptions) {
           var srcOut = new Time();
           srcOut.seconds = ${outSeconds};
           var workArea = ${hasRange ? 1 : 0};
-          
+          var removeUponCompletion = ${args.remove_on_completion !== false ? "true" : "false"};
+          var presetFile = new File("${escapeForExtendScript(args.preset_path)}");
+          if (!presetFile.exists) return __error("AME preset file does not exist: " + presetFile.fsName);
+
+          // Premiere type-checks encodeFile natively: paths must be Strings,
+          // workArea a Number, removeUponCompletion a Boolean, and in/out Time objects.
           var jobId = app.encoder.encodeFile(
-            inputFile.fsName,
-            outputFile.fsName,
-            "${escapeForExtendScript(args.preset_path)}",
+            String(inputFile.fsName),
+            String(outputFile.fsName),
+            String(presetFile.fsName),
             workArea,
-            ${args.remove_on_completion !== false ? 1 : 0},
+            removeUponCompletion,
             srcIn,
             srcOut
           );
@@ -1467,12 +1472,44 @@ export function getExportTools(bridgeOptions) {
                     preset_path: {
                         type: "string",
                         description: "Path to a proxy ingest preset (.epr) for 'create'. " +
-                            "If omitted, the first preset found in Premiere's IngestPresets/Proxy folder is used.",
+                            "If omitted, the server lists Premiere's IngestPresets/Proxy presets and AME H.264 system presets, " +
+                            "skips every preset whose output destination is Same as Project (Adobe's shipped proxy presets are), " +
+                            "and uses the first remaining one. Fails with a clear error when none qualify.",
                     },
                 },
                 required: ["item_id", "action"],
             },
             handler: async (args) => {
+                let presetPath = args.preset_path;
+                const skippedPresets = [];
+                if (args.action === "create" && args.output_path && !presetPath) {
+                    const listing = await sendCommand(buildToolScript(`return __result({ candidates: __listProxyPresetCandidates() });`), bridgeOptions);
+                    if (!listing.success)
+                        return listing;
+                    const rawCandidates = listing.data?.candidates;
+                    const candidates = Array.isArray(rawCandidates)
+                        ? rawCandidates.filter((value) => typeof value === "string" && value.length > 0)
+                        : [];
+                    for (const candidate of candidates) {
+                        try {
+                            presetPath = inspectExportPresetFile(candidate).path;
+                            break;
+                        }
+                        catch {
+                            skippedPresets.push(candidate);
+                        }
+                    }
+                    if (!presetPath) {
+                        return {
+                            success: false,
+                            error: candidates.length === 0
+                                ? "Could not locate any proxy or H.264 export preset. Pass preset_path explicitly (an .epr with an explicit output destination)."
+                                : `All ${candidates.length} auto-discovered presets use a Same as Project output destination or could not be read, so AME would not write the proxy to output_path. Pass preset_path explicitly (an .epr with an explicit output destination).`,
+                            skippedPresetCount: skippedPresets.length,
+                        };
+                    }
+                }
+                const autoDiscovered = presetPath !== args.preset_path;
                 const script = buildToolScript(`
           var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
           if (!item) return __error("Item not found");
@@ -1483,12 +1520,7 @@ export function getExportTools(bridgeOptions) {
             ${!args.output_path
                     ? `return __error("output_path is required for the 'create' action");`
                     : `var outputPath = "${escapeForExtendScript(args.output_path)}";
-                 ${args.preset_path
-                        ? `var presetPath = "${escapeForExtendScript(args.preset_path)}";`
-                        : `var presetPath = __findProxyPreset();
-                      if (!presetPath) {
-                        return __error("Could not locate a proxy ingest preset. Pass preset_path explicitly (an .epr under Premiere's Settings/IngestPresets/Proxy folder).");
-                      }`}
+                 var presetPath = "${escapeForExtendScript(presetPath ?? "")}";
 
                  // ProjectItem has no createProxy(). Proxy generation must go through
                  // Adobe Media Encoder; the result is attached in a separate step once
@@ -1507,6 +1539,8 @@ export function getExportTools(bridgeOptions) {
                    jobId: String(jobId),
                    outputPath: outputPath,
                    presetUsed: presetPath,
+                   presetAutoDiscovered: ${autoDiscovered ? "true" : "false"},
+                   skippedSameAsProjectPresets: ${skippedPresets.length},
                    verificationScope: "Premiere returned an AME job ID. Queue presence and proxy-file creation are not verified by this tool.",
                    nextStep: "Verify the proxy file exists, then call manage_proxies with action 'attach' and proxy_path set to outputPath."
                  });`}

package/dist/tools/media.js

@@ -460,23 +460,75 @@ export function getMediaTools(bridgeOptions) {
             },
         },
         set_scale_to_frame_size: {
-            description: "Enable 'Scale to Frame Size' on a project item so it fills the sequence frame",
+            description: "Enable 'Scale to Frame Size' so media fills the sequence frame. Accepts a timeline clip node ID " +
+                "(active sequence, same IDs as get_clip_properties) or a project item node ID or name. A timeline " +
+                "clip is resolved first and its source project item is updated through ProjectItem.setScaleToFrameSize(). " +
+                "ExtendScript exposes no getter for this flag, so the result is committed_unverified unless the timeline " +
+                "clip's Motion > Scale reads back changed (verified). Check with get_clip_properties.",
             parameters: {
                 type: "object",
                 properties: {
                     item_id: {
                         type: "string",
-                        description: "Node ID or name of the project item",
+                        description: "Timeline clip node ID in the active sequence, or project item node ID or name",
                     },
                 },
                 required: ["item_id"],
             },
             handler: async (args) => {
                 const script = buildToolScript(`
-          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
-          if (!item) return __error("Item not found");
+          var requestedId = "${escapeForExtendScript(args.item_id)}";
+          function __motionScale(trackItem) {
+            try {
+              var comps = trackItem.components;
+              for (var ci = 0; ci < comps.numItems; ci++) {
+                var comp = comps[ci];
+                if (comp.displayName !== "Motion" && comp.matchName !== "AE.ADBE Motion") continue;
+                for (var pi = 0; pi < comp.properties.numItems; pi++) {
+                  var prop = comp.properties[pi];
+                  if (prop.displayName === "Scale") return prop.getValue();
+                }
+              }
+            } catch (e) {}
+            return null;
+          }
+          var target = "projectItem";
+          var trackItem = null;
+          var trackInfo = null;
+          var item = null;
+          var found = __findClip(requestedId);
+          if (found) {
+            target = "timelineClip";
+            trackItem = found.clip;
+            trackInfo = { trackType: found.trackType, trackIndex: found.trackIndex, clipIndex: found.clipIndex };
+            try { item = trackItem.projectItem; } catch (e) { item = null; }
+            if (!item) return __error("Timeline clip " + requestedId + " has no source project item");
+          } else {
+            item = __findProjectItem(requestedId);
+          }
+          if (!item) return __error("Item not found: no timeline clip in the active sequence or project item matches " + requestedId);
+          var scaleBefore = trackItem ? __motionScale(trackItem) : null;
           item.setScaleToFrameSize();
-          return __result({ set: true, item: item.name });
+          var scaleAfter = trackItem ? __motionScale(trackItem) : null;
+          var changed = scaleBefore !== null && scaleAfter !== null && scaleBefore !== scaleAfter;
+          var out = {
+            set: true,
+            target: target,
+            item: item.name,
+            projectItemNodeId: __nodeIdOf(item),
+            status: changed ? "verified" : "committed_unverified",
+            motionScaleBefore: scaleBefore,
+            motionScaleAfter: scaleAfter
+          };
+          if (trackItem) {
+            out.clipNodeId = String(trackItem.nodeId);
+            out.clipName = trackItem.name;
+            out.trackType = trackInfo.trackType;
+            out.trackIndex = trackInfo.trackIndex;
+            out.clipIndex = trackInfo.clipIndex;
+          }
+          if (!changed) out.note = "ExtendScript has no getter for Scale to Frame Size; confirm with get_clip_properties.";
+          return __result(out);
         `);
                 return sendCommand(script, bridgeOptions);
             },

package/dist/tools/metadata.js

@@ -485,7 +485,8 @@ export function getMetadataTools(bridgeOptions) {
           } catch (e) {
             return __error("Premiere could not load the Adobe XMP library; no metadata was changed: " + e.toString());
           }
-          if (typeof XMPMeta !== "function" || typeof XMPUtils === "undefined" || typeof XMPUtils.appendProperties !== "function") {
+          if (typeof XMPMeta !== "function" || typeof XMPUtils === "undefined" || typeof XMPUtils.appendProperties !== "function" ||
+              typeof XMPConst === "undefined" || typeof XMPConst.APPEND_ALL_PROPERTIES !== "number" || typeof XMPConst.APPEND_REPLACE_OLD_VALUES !== "number") {
             return __error("Premiere's XMP merge APIs are unavailable; no metadata was changed.");
           }
 
@@ -496,7 +497,9 @@ export function getMetadataTools(bridgeOptions) {
             var patchXmp = new XMPMeta("${escapeForExtendScript(args.xmp_xml)}");
             // Copy every supplied top-level field into the existing packet, replacing
             // only fields named by the patch and retaining unrelated metadata.
-            XMPUtils.appendProperties(patchXmp, existingXmp, true, true, false);
+            // AdobeXMPScript signature: appendProperties(source, dest, options: Number).
+            var appendOptions = XMPConst.APPEND_ALL_PROPERTIES | XMPConst.APPEND_REPLACE_OLD_VALUES;
+            XMPUtils.appendProperties(patchXmp, existingXmp, appendOptions);
             item.setXMPMetadata(existingXmp.serialize());
 
             // Reparse the host readback so a malformed or rejected packet never