# 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.