feat: initial commit - Jhonny Editor

- Adicionado estrutura completa do projeto - Configurado MCP server para Premiere Pro - Adicionado documentação e skills - Configurado Gitignore para o projeto
2026-09-08 09:59:31 -04:00
commit b541f502ba
1507 changed files with 387650 additions and 0 deletions
@@ -0,0 +1,153 @@
+# 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.