PowerDirector MCP
by JasonYu-cl
README.md
# PowerDirector MCP
A Windows x64 MCP server that lets MCP-capable assistants launch CyberLink PowerDirector and edit video projects — inspect the timeline and media, add tracks and clips, stabilize footage, and export finished videos. It ships as a Claude Desktop MCPB extension and also registers with OpenAI Codex (CLI and IDE/desktop) as a stdio MCP server.
The MCP server is written in Node.js. In Claude Desktop it is started with the bundled Node runtime; in Codex it is started with the system Node.js (20+) executable. The server talks to PowerDirector directly over the `\\.\pipe\PowerDirectorMCP` named pipe: the first tool call launches PowerDirector in MCP mode (`clpdrMCP` plus the server's PID), and PowerDirector exits automatically when the server does.
End users do not need Python, uv, or any separate helper process. Claude Desktop additionally does not require a system Node.js installation; Codex does.
This release supports 64-bit Windows on x64 processors. Windows ARM64 is not currently supported.
## Architecture
```mermaid
graph TD
subgraph "MCP Host"
A[Claude Desktop / Codex / Claude Code]
end
subgraph "MCP Server Bundle"
B[Node.js MCP Server<br/>server.js]
end
subgraph "Target Application"
D[CyberLink PowerDirector]
end
A -->|1. Launches via Stdio| B
B -->|2. Launches with clpdrMCP + server PID| D
B -->|3. Sends JSON Command + \n| C["\\.\pipe\PowerDirectorMCP"]
C --> D
D -->|4. Watches server PID and exits with it| B
```
## Capabilities
- Launches PowerDirector automatically on the first tool call
- Reads the timeline structure — every track and clip with its GUID, type, and timing
- Reads metadata of the user's uploaded media (duration, resolution, audio streams)
- Adds video, audio, effect, and subtitle tracks to the timeline
- Adds and trims clips on the timeline
- Stabilizes shaky footage on selected clips
- Exports the timeline to an H.264 MP4 file and returns the output path
## End-user installation
### Claude Desktop
Install `PowerDirector.mcpb` in Claude Desktop. Claude Desktop launches the packaged server with:
```json
{
"command": "node",
"args": ["${__dirname}/server/server.js"]
}
```
For a Node-type MCPB, `node` selects Claude Desktop's bundled Node runtime. It does not depend on the user's `PATH`.
If the packaged-extension file picker in Claude Desktop fails, use **Extensions > Install Unpacked Extension...** and select `staging`.
### Codex (CLI and IDE/desktop)
Codex shares one configuration file across the CLI and the IDE extension at `~/.codex/config.toml` (or `%CODEX_HOME%\config.toml`). The install script copies the built server to `%LOCALAPPDATA%\PowerDirectorMCP` and registers a stdio MCP server:
```toml
[mcp_servers.PowerDirector]
command = "C:/Program Files/nodejs/node.exe"
args = ["C:/Users/<you>/AppData/Local/PowerDirectorMCP/server/server.js"]
startup_timeout_sec = 30
tool_timeout_sec = 120
```
Codex does not bundle Node.js, so Node 20+ must be installed and on `PATH`. After running the build, register and unregister with:
```powershell
install-codex-mcp.bat
uninstall-codex-mcp.bat
```
After installing, restart Codex and run `/mcp` to confirm the `PowerDirector` server is active.
### Codex plugin (MCP server + skills)
Instead of registering only the MCP server, you can install a full Codex **plugin** that bundles the MCP server together with skills that teach Codex how to drive PowerDirector. The plugin is assembled into a local marketplace and installed with the Codex CLI:
```powershell
install-codex-plugin.bat
uninstall-codex-plugin.bat
```
This requires the Codex CLI (`npm i -g @openai/codex`) and Node 20+ on `PATH`. The installer:
1. Assembles the plugin under `%LOCALAPPDATA%\PowerDirectorMCP\codex-plugin` (manifest, `skills/`, `.mcp.json`, and the Node server).
2. Registers a local marketplace named `CyberLink`.
3. Runs `codex plugin add powerdirector@CyberLink`.
The bundle layout follows the Codex plugin spec:
```
marketplace/
.agents/plugins/marketplace.json
plugins/powerdirector/
.codex-plugin/plugin.json # plugin manifest
.mcp.json # bundled MCP server (command + args)
skills/
powerdirector-control/SKILL.md
powerdirector-produce/SKILL.md
server/ # server.js
assets/icon.png
```
After installing, restart Codex and run `/plugins` to confirm `PowerDirector` is enabled, or type `$` to invoke its skills (`powerdirector-control`, `powerdirector-produce`).
### Claude Code (CLI) MCP server
To register only the MCP server with the Claude Code CLI (no skills), run:
```powershell
install-claude-mcp.bat
uninstall-claude-mcp.bat
```
This requires the Claude Code CLI and Node 20+ on `PATH`. The installer copies the server to `%LOCALAPPDATA%\PowerDirectorMCP\claude-mcp` and registers it at user scope with `claude mcp add PowerDirector --scope user -- <node> <server.js>`. Confirm with `claude mcp list` or `/mcp` inside Claude Code.
### Claude Code plugin (MCP server + skills)
You can also install a full Claude Code **plugin** that bundles the MCP server together with the same skills. The plugin is assembled into a local marketplace and installed with the Claude Code CLI:
```powershell
install-claude-plugin.bat
uninstall-claude-plugin.bat
```
This requires the Claude Code CLI and Node 20+ on `PATH`. The installer:
1. Assembles the plugin under `%LOCALAPPDATA%\PowerDirectorMCP\claude-plugin` (manifest, `skills/`, `.mcp.json`, and the Node server).
2. Registers a local marketplace named `CyberLink`.
3. Runs `claude plugin install powerdirector@CyberLink`.
The bundle layout follows the Claude Code plugin spec:
```
marketplace/
.claude-plugin/marketplace.json
plugins/powerdirector/
.claude-plugin/plugin.json # plugin manifest
.mcp.json # bundled MCP server (mcpServers map)
skills/
powerdirector-control/SKILL.md
powerdirector-produce/SKILL.md
server/ # server.js
assets/icon.png
```
After installing, restart Claude Code and run `/plugin` to confirm `PowerDirector` is enabled.
### Local Installation & Uninstallation (Claude Desktop)
For local development installs after running a release build, run:
```powershell
install-claude-mcpb.bat
```
To uninstall the extension and clean up all Claude Desktop settings and staged files, run:
```powershell
uninstall-claude-mcpb.bat
```
> [!NOTE]
> Both `install-claude-mcpb.bat` and `uninstall-claude-mcpb.bat` will check if Claude Desktop is currently running. If it is, they will display a warning and wait for you to close it before proceeding.
### PowerDirector Lifetime Management
PowerDirector is launched by the Node.js MCP server in named-pipe MCP mode (`clpdrMCP <server pid>`):
* PowerDirector watches the server's PID and exits automatically when the server does (e.g., when Claude Desktop is closed) — there is no manual close step.
## Developer setup
Development requires Node.js 20 or later.
```powershell
npm install
npm run build
npm test
```
Run the development server:
```powershell
npm start
```
## Project layout
- `src/`: Node.js MCP server source.
- `assets/`: Packaged extension assets such as the icon.
- `plugin/`: Shared plugin template used by both `install-codex-plugin.bat` and `install-claude-plugin.bat`. Holds the Codex manifest under `.codex-plugin/`, the Claude Code manifest under `.claude-plugin/`, and a single shared `skills/` folder.
- `scripts/`: Build verification helpers.
- `tests-node/`: Node test code for the server and the PowerDirector named-pipe client.
- `dist/`: Generated bundled server output.
- `staging/`: Generated unpacked MCPB contents used for local install and packaging.
## Release build
```powershell
npm run build:mcpb
```
The build:
1. Installs the locked npm dependencies.
2. Bundles the JavaScript server into one file.
3. Creates `staging` with only the server, manifest, icon, and license.
4. Performs a real MCP stdio handshake.
5. Creates `PowerDirector.mcpb`.
`build.bat` is kept as a Windows convenience wrapper around `npm run build:mcpb`.
## License
This project is commercially licensed. See `LICENSE` for the distribution terms.
## Tools
Tool definitions (name, description, input/output schema) are generated from PowerDirector's Iris skill catalog by `scripts/generate-tools.js` into `src/tools.generated.js`; run `npm run gen:tools` to refresh them (the `build` script does this automatically). `src/server.js` adds only MCP-specific metadata (titles, read-only/destructive hints, and a few polished descriptions).
- Connectivity: `ping_powerdirector`
- Inspect: `get_media_info`, `get_timeline_info`
- Build: `add_track`, `add_clip`, `set_project_settings`, `set_video_stabilizer`, `clear_timeline`
- Effects: `list_effect_categories`, `list_effects`, `add_effect`, `remove_effect`
- Transitions: `list_transition_categories`, `list_transitions`, `add_transition`
- Music: `add_bgm`
- AI generation (consume CyberLink credits): `list_auto_edit_themes`, `gen_auto_edit`, `list_image_by_text_styles`, `gen_image_by_text`, `edit_video_by_text`
- Export: `export_timeline_to_video`
`get_timeline_info`, `add_track`, and `add_clip` return GUIDs; subsequent calls target tracks and clips by those GUIDs. Inspect the timeline with `get_timeline_info` before editing.
Not every tool is served by every PowerDirector build — the server advertises the full catalog, and tools the installed build has not registered on the pipe return an error when called.