jhonny-editor/code/CONTRIBUTING.md

Contributing to Premiere Pro MCP Server

Thanks for your interest in contributing! This guide covers how to get set up and submit changes.

Development Setup

Prerequisites

• Node.js 18+
• Adobe Premiere Pro 2020+ (for testing)
• An MCP-compatible client (Claude Desktop, Windsurf, Cursor, GitHub Copilot, etc.)

Getting started

git clone https://github.com/leancoderkavy/premiere-pro-mcp.git
cd premiere-pro-mcp
npm install
npm run dev          # Watch mode — recompiles on changes
npm run install-cep  # Install CEP plugin into Premiere Pro

After making changes, restart your MCP client to pick up the new tools.

Project Architecture

src/
├── index.ts              # Entry point
├── server.ts             # Registers all tools with the MCP SDK
├── bridge/
│   ├── file-bridge.ts    # File-based IPC (.jsx → .json)
│   └── script-builder.ts # Generates ES3 ExtendScript with helpers
└── tools/                # 29 tool modules

How tools work

Each tool module exports a getXTools(bridgeOptions) function that returns a Record<string, ToolDef>. A tool definition has:

• description — shown to the AI client
• parameters — JSON Schema object (converted to Zod at registration)
• handler — async function that builds ExtendScript and sends it via the bridge

Example:

my_tool: {
  description: "Does a thing in Premiere Pro",
  parameters: {
    type: "object" as const,
    properties: {
      name: { type: "string", description: "Name of the thing" },
    },
    required: ["name"],
  },
  handler: async (args: { name: string }) => {
    const script = buildToolScript(`
      var result = app.project.name;
      return __result({ projectName: result, input: "${escapeForExtendScript(args.name)}" });
    `);
    return sendCommand(script, bridgeOptions);
  },
},

ExtendScript rules

All generated scripts must be ES3-compatible:

• Use var, not let/const
• No arrow functions — use function(x) { ... }
• No template literals — use string concatenation
• No Array.forEach/map/filter — use manual for loops
• No destructuring, spread, or default parameters
• Always use escapeForExtendScript() for user-provided strings

Helper functions

buildToolScript() prepends these helpers to every script:

• __result(data) — return success JSON
• __error(msg) — return error JSON
• __findProjectItem(nameOrId) — find project item by name or node ID
• __findClip(nodeId) — find clip on timeline by node ID
• __findSequence(nameOrId) — find sequence by name or ID
• __ticksToSeconds(ticks) / __secondsToTicks(seconds) — time conversion
• __getClipComponents(clip) — enumerate effect components

Adding a New Tool

1. Find the right module in src/tools/ or create a new one if it's a new capability area
2. Add the tool definition following the pattern above
3. If creating a new module, register it in src/server.ts:

   import { getMyTools } from "./tools/my-module.js";
   // ... in createServer():
   ...getMyTools(bridgeOptions),
   

4. Build and test: npm run build
5. Test in Premiere Pro by calling the tool from your MCP client

Submitting Changes

Pull requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-new-tool
3. Make your changes
4. Run npm run build to verify compilation
5. Test with Premiere Pro if possible
6. Submit a pull request with a clear description

Commit messages

Use clear, descriptive commit messages:

Add stabilize_clip tool using Warp Stabilizer effect
Fix set_clip_properties Position X/Y handling
Add workspace.ts module with get/set workspace tools

Code style

• Follow existing patterns in the codebase
• Keep tool descriptions concise but informative
• Use TypeScript types for handler arguments
• Don't add comments unless they explain non-obvious behavior

Reporting Issues

When filing an issue, please include:

• Premiere Pro version
• OS (macOS/Windows)
• MCP client (Claude Desktop, Windsurf, Cursor, GitHub Copilot, etc.)
• The tool name and parameters you used
• The error message or unexpected behavior
• Whether the CEP panel shows "Running"

QE DOM Notes

The QE DOM is undocumented. If you discover new QE methods or behaviors:

1. Test thoroughly — QE operations can be destructive
2. Document what you find in RESEARCH.md
3. Mark QE-based tools with "Uses QE DOM" in their descriptions
4. Always call app.enableQE() before using QE objects

License

By contributing, you agree that your contributions will be licensed under the MIT License.