@synthetic-ai/premiere-mcp 2.0.0

package/dist/tools/media.js

@@ -0,0 +1,493 @@
+import { buildToolScript, escapeForExtendScript } from "../bridge/script-builder.js";
+import { sendCommand } from "../bridge/file-bridge.js";
+export function getMediaTools(bridgeOptions) {
+    return {
+        import_media: {
+            description: `Import one or more media files into the Premiere Pro project panel.
+
+Preconditions: A project must be open. File paths must be absolute paths accessible from the machine running Premiere Pro (not the MCP server).
+
+After import, use list_project_items to get the node IDs of the imported clips, which are needed for add_to_timeline and other operations.
+
+Supported formats: Video (MP4, MOV, MXF, AVI, R3D, BRAW), Audio (WAV, AIFF, MP3, AAC), Images (JPG, PNG, TIFF, PSD), and all other formats Premiere Pro supports.
+
+Parameters:
+- file_paths: Array of absolute file paths to import. Use forward slashes on macOS, backslashes on Windows.
+- target_bin: Optional bin name to import into (organize media). If omitted, imports to project root.
+- suppress_ui: Whether to skip import dialogs (default: true — recommended for automation).
+
+Example: import_media({ file_paths: ["C:\\\\Media\\\\interview.mp4", "C:\\\\Media\\\\broll.mp4"] })
+Example: import_media({ file_paths: ["/Users/me/footage/clip.mov"], target_bin: "B-Roll" })`,
+            parameters: {
+                type: "object",
+                properties: {
+                    file_paths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Array of file paths to import",
+                    },
+                    target_bin: {
+                        type: "string",
+                        description: "Optional bin name or node ID to import into. Imports to root if omitted.",
+                    },
+                    suppress_ui: {
+                        type: "boolean",
+                        description: "Suppress import dialogs (default: true)",
+                    },
+                },
+                required: ["file_paths"],
+            },
+            handler: async (args) => {
+                const paths = args.file_paths.map((p) => `"${escapeForExtendScript(p)}"`).join(", ");
+                const suppress = args.suppress_ui !== false ? "true" : "false";
+                const binLookup = args.target_bin
+                    ? `var targetBin = __findProjectItem("${escapeForExtendScript(args.target_bin)}");
+             if (!targetBin) return __error("Bin not found: ${escapeForExtendScript(args.target_bin)}");`
+                    : `var targetBin = app.project.rootItem;`;
+                const script = buildToolScript(`
+          ${binLookup}
+          var filePaths = [${paths}];
+          // Check which files actually exist before importing
+          var existingPaths = [];
+          var missingPaths = [];
+          for (var i = 0; i < filePaths.length; i++) {
+            var f = new File(filePaths[i]);
+            if (f.exists) {
+              existingPaths.push(filePaths[i]);
+            } else {
+              missingPaths.push(filePaths[i]);
+            }
+          }
+          if (existingPaths.length === 0) {
+            return __error("No files found on disk. Check paths. Missing: " + missingPaths.join(", "));
+          }
+          var countBefore = targetBin.children ? targetBin.children.numItems : app.project.rootItem.children.numItems;
+          var importSuccess = app.project.importFiles(existingPaths, ${suppress}, targetBin, false);
+          var countAfter = targetBin.children ? targetBin.children.numItems : app.project.rootItem.children.numItems;
+          var actualImported = countAfter - countBefore;
+          var result = { imported: actualImported, requested: filePaths.length, files: existingPaths };
+          if (missingPaths.length > 0) result.missing = missingPaths;
+          if (actualImported === 0 && !importSuccess) return __error("Import failed — Premiere rejected all files");
+          return __result(result);
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        import_folder: {
+            description: "Import an entire folder of media into the project",
+            parameters: {
+                type: "object",
+                properties: {
+                    folder_path: {
+                        type: "string",
+                        description: "Path to the folder to import",
+                    },
+                },
+                required: ["folder_path"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var folder = new Folder("${escapeForExtendScript(args.folder_path)}");
+          if (!folder.exists) return __error("Folder not found: ${escapeForExtendScript(args.folder_path)}");
+
+          var files = folder.getFiles();
+          var filePaths = [];
+          for (var i = 0; i < files.length; i++) {
+            if (files[i] instanceof File) {
+              filePaths.push(files[i].fsName);
+            }
+          }
+
+          if (filePaths.length === 0) return __error("No files found in folder");
+
+          var countBefore = app.project.rootItem.children.numItems;
+          var importSuccess = app.project.importFiles(filePaths, true, app.project.rootItem, false);
+          var countAfter = app.project.rootItem.children.numItems;
+          var actualImported = countAfter - countBefore;
+          return __result({ imported: actualImported, requested: filePaths.length, folder: "${escapeForExtendScript(args.folder_path)}" });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        create_bin: {
+            description: "Create a new bin (folder) in the project panel",
+            parameters: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Name of the new bin",
+                    },
+                    parent_bin: {
+                        type: "string",
+                        description: "Optional parent bin name or node ID. Creates in root if omitted.",
+                    },
+                },
+                required: ["name"],
+            },
+            handler: async (args) => {
+                const parentLookup = args.parent_bin
+                    ? `var parent = __findProjectItem("${escapeForExtendScript(args.parent_bin)}");
+             if (!parent) return __error("Parent bin not found");`
+                    : `var parent = app.project.rootItem;`;
+                const script = buildToolScript(`
+          ${parentLookup}
+          var newBin = parent.createBin("${escapeForExtendScript(args.name)}");
+          return __result({ created: true, name: "${escapeForExtendScript(args.name)}", nodeId: newBin.nodeId });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        move_item_to_bin: {
+            description: "Move a project item to a different bin",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the item to move",
+                    },
+                    target_bin: {
+                        type: "string",
+                        description: "Name or node ID of the target bin",
+                    },
+                },
+                required: ["item_id", "target_bin"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found: ${escapeForExtendScript(args.item_id)}");
+          
+          var targetBin = __findProjectItem("${escapeForExtendScript(args.target_bin)}");
+          if (!targetBin) return __error("Target bin not found: ${escapeForExtendScript(args.target_bin)}");
+          
+          item.moveBin(targetBin);
+          return __result({ moved: true, item: item.name, toBin: targetBin.name });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        relink_media: {
+            description: "Relink an offline media item to a new file path",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the item to relink",
+                    },
+                    new_path: {
+                        type: "string",
+                        description: "New file path for the media",
+                    },
+                },
+                required: ["item_id", "new_path"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found: ${escapeForExtendScript(args.item_id)}");
+          
+          var success = item.changeMediaPath("${escapeForExtendScript(args.new_path)}", true);
+          return __result({ relinked: success, item: item.name, newPath: "${escapeForExtendScript(args.new_path)}" });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        refresh_media: {
+            description: "Refresh a project item to pick up changes to the source file",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the item to refresh",
+                    },
+                },
+                required: ["item_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found: ${escapeForExtendScript(args.item_id)}");
+          item.refreshMedia();
+          return __result({ refreshed: true, item: item.name });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        check_offline_media: {
+            description: "Check for offline (missing) media in the project",
+            parameters: {},
+            handler: async () => {
+                const script = buildToolScript(`
+          var offlineItems = [];
+          
+          function checkItem(item) {
+            if (item.type === 1) {
+              try {
+                if (__readMaybe(item, "isOffline", false)) {
+                  offlineItems.push({
+                    nodeId: item.nodeId,
+                    name: item.name,
+                    mediaPath: item.getMediaPath ? item.getMediaPath() : ""
+                  });
+                }
+              } catch(e) {}
+            }
+            if (item.type === 2 && item.children) {
+              for (var i = 0; i < item.children.numItems; i++) {
+                checkItem(item.children[i]);
+              }
+            }
+          }
+          
+          var root = app.project.rootItem;
+          for (var i = 0; i < root.children.numItems; i++) {
+            checkItem(root.children[i]);
+          }
+          
+          return __result({ offlineCount: offlineItems.length, items: offlineItems });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        set_offline: {
+            description: "Set a project item to offline status (unlinks its media)",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item",
+                    },
+                },
+                required: ["item_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found: ${escapeForExtendScript(args.item_id)}");
+          item.setOffline();
+          return __result({ offline: true, item: item.name });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        has_proxy: {
+            description: "Check if a project item has a proxy attached",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item",
+                    },
+                },
+                required: ["item_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found");
+          
+          var info = { item: item.name };
+          try { info.hasProxy = item.hasProxy(); } catch(e) { info.hasProxy = false; }
+          try { info.canProxy = item.canProxy(); } catch(e) { info.canProxy = false; }
+          try { info.proxyPath = item.getProxyPath(); } catch(e) {}
+          
+          return __result(info);
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        detach_proxy: {
+            description: "Detach/remove the proxy from a project item",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item",
+                    },
+                },
+                required: ["item_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found");
+          item.detachProxy();
+          return __result({ detached: true, item: item.name });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        set_override_frame_rate: {
+            description: "Override the frame rate of a project item (useful for image sequences or misinterpreted media)",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item",
+                    },
+                    frame_rate: {
+                        type: "number",
+                        description: "Frame rate to set (e.g., 23.976, 24, 29.97, 30, 60)",
+                    },
+                },
+                required: ["item_id", "frame_rate"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found");
+          item.setOverrideFrameRate(${args.frame_rate});
+          return __result({ set: true, item: item.name, frameRate: ${args.frame_rate} });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        set_override_pixel_aspect_ratio: {
+            description: "Override the pixel aspect ratio of a project item",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item",
+                    },
+                    numerator: {
+                        type: "number",
+                        description: "PAR numerator (e.g., 1 for square pixels)",
+                    },
+                    denominator: {
+                        type: "number",
+                        description: "PAR denominator (e.g., 1 for square pixels)",
+                    },
+                },
+                required: ["item_id", "numerator", "denominator"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found");
+          item.setOverridePixelAspectRatio(${args.numerator}, ${args.denominator});
+          return __result({ set: true, item: item.name, par: "${args.numerator}:${args.denominator}" });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        set_scale_to_frame_size: {
+            description: "Enable 'Scale to Frame Size' on a project item so it fills the sequence frame",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item",
+                    },
+                },
+                required: ["item_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found");
+          item.setScaleToFrameSize();
+          return __result({ set: true, item: item.name });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        get_item_info: {
+            description: "Get detailed type info about a project item (is it a sequence, multicam, merged clip, etc.)",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item",
+                    },
+                },
+                required: ["item_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found");
+          
+          var info = {
+            name: item.name,
+            nodeId: item.nodeId,
+            type: item.type === 1 ? "clip" : item.type === 2 ? "bin" : item.type === 3 ? "sequence" : "unknown",
+            treePath: item.treePath
+          };
+          info.isSequence = __readMaybe(item, "isSequence", false);
+          info.isMulticamClip = __readMaybe(item, "isMulticamClip", false);
+          info.isMergedClip = __readMaybe(item, "isMergedClip", false);
+          info.isOffline = __readMaybe(item, "isOffline", false);
+          try { info.mediaPath = item.getMediaPath(); } catch(e) {}
+          try { info.hasProxy = item.hasProxy(); } catch(e) {}
+          try { info.canProxy = item.canProxy(); } catch(e) {}
+          
+          return __result(info);
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        select_item: {
+            description: "Select a project item in the Project panel",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item to select",
+                    },
+                },
+                required: ["item_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found");
+          item.select();
+          return __result({ selected: true, item: item.name });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        set_start_time: {
+            description: "Set the start time (timecode offset) for a project item",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item",
+                    },
+                    start_seconds: {
+                        type: "number",
+                        description: "Start time in seconds",
+                    },
+                },
+                required: ["item_id", "start_seconds"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Item not found");
+          
+          var ticks = __secondsToTicks(${args.start_seconds}).toString();
+          item.setStartTime(ticks);
+          return __result({ set: true, item: item.name, startSeconds: ${args.start_seconds} });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+    };
+}
+//# sourceMappingURL=media.js.map

package/dist/tools/metadata.d.ts

@@ -0,0 +1,178 @@
+import { BridgeOptions } from "../bridge/file-bridge.js";
+export declare function getMetadataTools(bridgeOptions: BridgeOptions): {
+    get_metadata: {
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                item_id: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        handler: (args: {
+            item_id: string;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+    };
+    set_metadata: {
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                item_id: {
+                    type: string;
+                    description: string;
+                };
+                field_name: {
+                    type: string;
+                    description: string;
+                };
+                value: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        handler: (args: {
+            item_id: string;
+            field_name: string;
+            value: string;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+    };
+    set_color_label: {
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                item_id: {
+                    type: string;
+                    description: string;
+                };
+                color_index: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        handler: (args: {
+            item_id: string;
+            color_index: number;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+    };
+    get_color_label: {
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                item_id: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        handler: (args: {
+            item_id: string;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+    };
+    get_footage_interpretation: {
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                item_id: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        handler: (args: {
+            item_id: string;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+    };
+    set_footage_interpretation: {
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                item_id: {
+                    type: string;
+                    description: string;
+                };
+                frame_rate: {
+                    type: string;
+                    description: string;
+                };
+                pixel_aspect_ratio: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        handler: (args: {
+            item_id: string;
+            frame_rate?: number;
+            pixel_aspect_ratio?: number;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+    };
+    get_xmp_metadata: {
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                item_id: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        handler: (args: {
+            item_id: string;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+    };
+    set_xmp_metadata: {
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                item_id: {
+                    type: string;
+                    description: string;
+                };
+                xmp_xml: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        handler: (args: {
+            item_id: string;
+            xmp_xml: string;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+    };
+    get_color_space: {
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                item_id: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        handler: (args: {
+            item_id: string;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
+    };
+};
+//# sourceMappingURL=metadata.d.ts.map