# GHOST MCP Server

The GHOST MCP server lets any MCP-capable AI (Claude Desktop, Cursor, Codex,
your own agent, or another server) read the extension source **and drive the
live After Effects session** through the GHOST panel.

```
mcp/
  server.js        stdio MCP server (tool registry)
  config.js        sandbox paths + feature switches
  tools/files.js   list_dir · read_file · write_file · search_code · read_cep_log
  tools/project.js panel_info · scan_project
  tools/ae.js      ae_bridge_status · ae_context · ae_call_host · ae_run_extendscript
  tools/terminal.js run_command (whitelisted)
```

## 1. Install

```bash
cd "%APPDATA%\Adobe\CEP\extensions\com.ghost.creativesystem"
npm install
```

## 2. Run

```bash
set GHOST_PROJECT_ROOT=%APPDATA%\Adobe\CEP\extensions\com.ghost.creativesystem
set GHOST_ALLOW_WRITE=1
set GHOST_ALLOW_TERMINAL=0
node mcp/server.js
```

| Variable | Default | Meaning |
| --- | --- | --- |
| `GHOST_PROJECT_ROOT` | current folder | the only folder file tools may touch |
| `GHOST_BRIDGE_DIR` | `%APPDATA%\GHOST\mcp-bridge` | folder shared with the panel |
| `GHOST_ALLOW_WRITE` | off | enables `write_file` and `ae_run_extendscript` |
| `GHOST_ALLOW_TERMINAL` | off | enables `run_command` |

## 3. Register with a client

Claude Desktop / Cursor `mcpServers` entry:

```json
{
  "mcpServers": {
    "ghost": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\AppData\\Roaming\\Adobe\\CEP\\extensions\\com.ghost.creativesystem\\mcp\\server.js"],
      "env": {
        "GHOST_PROJECT_ROOT": "C:\\Users\\<you>\\AppData\\Roaming\\Adobe\\CEP\\extensions\\com.ghost.creativesystem",
        "GHOST_ALLOW_WRITE": "1"
      }
    }
  }
}
```

## 4. Turn on the After Effects bridge

Node cannot call CEP's `evalScript` directly, so the panel does it for us.

1. Open any GHOST panel in After Effects.
2. In the panel console run `GhostMcpBridge.enable()` (the setting is
   remembered, so this is a one-time step per machine).
3. From the MCP client call `ae_bridge_status` — `panelConnected: true` means
   After Effects is reachable.

Protocol (plain JSON files, no ports, no firewall prompts):

```
<bridge>/requests/<id>.json    { id, script, createdAt }     ← MCP server
<bridge>/responses/<id>.json   { id, ok, result | error }    ← GHOST panel
<bridge>/panel.json            { updatedAt, panel, host }    ← heartbeat
```

## 5. Safety model

* File tools are hard-sandboxed to `GHOST_PROJECT_ROOT`; any `..` escape throws.
* Writes and raw ExtendScript are **off** unless explicitly enabled.
* `run_command` only launches `node`, `npm`, `git`, `powershell.exe`, `cmd.exe`.
* Results are truncated so a single tool call cannot flood the model context.
* No API keys, licence keys or user data are exposed by any tool.
