João Henrique
b541f502ba
- Adicionado estrutura completa do projeto - Configurado MCP server para Premiere Pro - Adicionado documentação e skills - Configurado Gitignore para o projeto
154 lines
4.6 KiB
Markdown
Executable File
154 lines
4.6 KiB
Markdown
Executable File
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```typescript
|
|
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`:
|
|
```typescript
|
|
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.
|