creative-pipeline-mcp 0.2.14-alpha.0

package/docs/INSTALL_PREMIERE.md

@@ -0,0 +1,62 @@
+# Premiere Install Notes
+
+The alpha QC path can inspect media with `ffprobe` and FFmpeg without Premiere installed.
+
+For timeline mutation and exports, install Premiere Pro and use a trusted CEP/ExtendScript bridge. `premiere.build_timeline_from_otio` queues a file-based IPC command under `CREATIVE_MCP_PREMIERE_IPC_DIR` for a CEP panel to consume. A minimal panel scaffold is included in `packages/premiere-cep-panel`. Raw ExtendScript execution should remain approval-gated. The Windows adapter package contains guardrails inspired by Windows CEP/WebSocket bridges, but it is not an installer.
+
+Recommended external tools:
+
+- FFmpeg / ffprobe
+- MediaInfo
+- OpenTimelineIO
+- WhisperX, faster-whisper, or whisper.cpp
+- PySceneDetect
+- Auto-Editor
+- pyloudnorm
+- FFmpeg with `libvmaf` for reference-based quality scoring
+
+MCP tools:
+
+- `premiere.transcribe_media`: uses WhisperX when available, otherwise writes an adapter manifest
+- `premiere.detect_scenes`: uses PySceneDetect when available, otherwise writes an adapter manifest
+- `premiere.measure_loudness`: uses pyloudnorm when available, otherwise writes an adapter manifest
+- `premiere.measure_vmaf`: uses FFmpeg `libvmaf` when available, otherwise writes an adapter report
+- `premiere.build_timeline_from_otio`: writes a CEP queue command for the panel scaffold
+- `premiere.build_project_delivery`: writes a project-specific template, OTIO timeline, brand package, export plan, and queues CEP commands
+- `premiere.export_video`: writes an export plan and queues `export_sequence`
+- `premiere.apply_brand_package`: writes a brand package manifest and queues `apply_brand_package`
+- `premiere.read_cep_status`: reads status JSON written by the CEP panel scaffold
+- `premiere.await_cep_status`: polls for a matching CEP status by command id or command type
+- `premiere.finalize_export_qc`: resolves an export status and runs delivery QC after the exported file exists
+
+Generated sample:
+
+```bash
+npm run build
+node examples/premiere-qc-e2e.mjs
+node examples/premiere-project-delivery.mjs
+npm run simulate:premiere-cep -- --queue artifacts/examples/premiere-project-delivery/cep_queue --status artifacts/examples/premiere-project-delivery/cep_status
+```
+
+For a real Premiere project walkthrough, see `docs/PREMIERE_E2E_TEST.md`.
+For CEP status records, see `docs/CEP_STATUS_SCHEMA.md`.
+
+CEP simulator:
+
+```bash
+npm run simulate:premiere-cep -- --queue artifacts/premiere/cep_queue --status artifacts/premiere/cep_status
+```
+
+The simulator loads `packages/premiere-cep-panel/jsx/host.jsx` into a Node VM with a fake Premiere app, dispatches queued commands through the same host functions, writes normalized status JSON, and archives processed command files. It is not a replacement for a real Premiere run, but it verifies host-side command parsing, OTIO clip collection, sequence creation, brand package status, export status, and queue/status file behavior before live testing.
+
+CEP packaging:
+
+```bash
+npm run package:premiere-cep -- --verify
+```
+
+This writes an unsigned package and checksums under `dist/premiere-cep`. To produce a signed ZXP, install Adobe `ZXPSignCmd` and provide a project signing certificate:
+
+```bash
+ZXPSIGNCMD_BIN=/path/to/ZXPSignCmd CEP_SIGN_CERT=/path/to/cert.p12 CEP_SIGN_PASSWORD=secret npm run package:premiere-cep -- --sign
+```

package/docs/LICENSING.md

@@ -0,0 +1,19 @@
+# Licensing
+
+Core packages are Apache-2.0.
+
+GPL tools are not imported into the Apache-2.0 packages. They are represented as optional external adapter manifests and should be installed, run, and distributed according to their own licenses.
+
+## Included Policy
+
+- `creative-mcp-core`: Apache-2.0
+- `blender-pro-mcp`: Apache-2.0
+- `premiere-pro-mcp`: Apache-2.0
+- `premiere-windows-adapter`: Apache-2.0
+- `dashboard`: Apache-2.0
+- `blender-gpl-adapters`: GPL-3.0-or-later package boundary
+
+## Excluded
+
+3D-Agent is excluded. Do not copy its product, UI, workflow, model, branding, or proprietary implementation into this repository.
+

package/docs/PREMIERE_E2E_TEST.md

@@ -0,0 +1,55 @@
+# Premiere E2E Test
+
+This guide verifies the alpha CEP bridge with a real Premiere project.
+
+## Setup
+
+1. Install the CEP panel from `packages/premiere-cep-panel`.
+2. Enable CEP debug mode for your Adobe/Premiere version.
+3. Open a new Premiere project.
+4. Set the panel queue directory to:
+
+```text
+artifacts/premiere/cep_queue
+```
+
+## Run
+
+Build the package and create a generated MP4 sample:
+
+```bash
+npm run build
+node examples/premiere-qc-e2e.mjs
+```
+
+Then run the CEP panel poll action in Premiere.
+
+Expected result:
+
+- media is imported once
+- an active or new sequence receives the clip
+- the clip is inserted at the OTIO timeline position
+- a status JSON file is written under `artifacts/premiere/cep_status`
+
+Read the status:
+
+```bash
+CREATIVE_MCP_PERMISSION=project_write npm run start:premiere
+```
+
+Call `premiere.read_cep_status` or `premiere.await_cep_status` from the MCP client.
+
+## Export Queue
+
+`premiere.export_video` writes an `export_sequence` command with:
+
+```json
+{
+  "outputPath": "artifacts/premiere/exports/final.mp4",
+  "presetPath": ""
+}
+```
+
+The CEP host script attempts `app.encoder.encodeSequence`. If Adobe Media Encoder is unavailable, it records an accepted status instead of claiming a completed export.
+
+After the CEP panel writes an `export_sequence` status, call `premiere.finalize_export_qc` with the `commandId`. The tool resolves `details.outputPath` from the status file, checks that the exported file exists, and writes an export delivery QC report. If the file is still missing, it writes a pending artifact instead of reporting a false pass.

package/docs/RELEASE_PROCESS.md

@@ -0,0 +1,74 @@
+# Release Process
+
+## Local Gates
+
+```bash
+npm test
+npm run check:adapters -- --json
+node examples/blender-e2e.mjs
+node examples/premiere-qc-e2e.mjs
+node examples/premiere-project-delivery.mjs
+npm run simulate:premiere-cep -- --queue artifacts/examples/premiere-project-delivery/cep_queue --status artifacts/examples/premiere-project-delivery/cep_status
+npm run package:premiere-cep -- --verify
+npm pack --dry-run
+```
+
+## Assets
+
+Generate release assets:
+
+```bash
+npm run release:assets
+```
+
+This writes:
+
+```text
+dist/release/
+  creative-pipeline-mcp-<version>.tgz
+  creative-pipeline-mcp-example-artifacts-<version>.zip
+  checksums.txt
+dist/premiere-cep/
+  creative-pipeline-mcp-premiere-cep-panel-<version>.zip
+  premiere-cep-checksums.txt
+```
+
+Upload:
+
+```bash
+gh release upload v<version> dist/release/* --clobber
+```
+
+## npm Publish Readiness
+
+Check name and package metadata:
+
+```bash
+npm view creative-pipeline-mcp version
+npm pack --dry-run
+npm publish --dry-run --provenance
+```
+
+Local publishing requires an authenticated npm session:
+
+```bash
+npm publish --provenance --access public
+```
+
+GitHub Actions publishing uses npm trusted publishing. Configure npmjs.com with:
+
+```text
+Owner: taiyuhiga
+Repository: creative-pipeline-mcp
+Workflow: npm-publish.yml
+Environment: leave empty unless a GitHub environment is added
+```
+
+Then set the repository variable `NPM_TRUSTED_PUBLISHING_ENABLED=true`. The workflow publishes from release tags only after tests, adapter checks, Premiere project-delivery example, CEP package verification, npm pack dry-run, and package-version/tag matching pass.
+
+## Semver
+
+- `0.2.x-alpha`: scaffold, safety, docs, adapter gates
+- `0.3.x-alpha`: real Blender/Premiere E2E
+- `0.4.x-beta`: installers, stable docs, schema tightening
+- `1.0.0`: stable tool schemas and artifact schemas

package/docs/ROADMAP.md

@@ -0,0 +1,53 @@
+# Roadmap
+
+## Completed In This Alpha
+
+- Phase 0 design and licensing posture
+- Phase 1 core registry/router/artifact/QC/approval infrastructure
+- Phase 2 QC-first MVP
+- Phase 3 Blender Pro MCP MVP surface with QC/export fallbacks
+- Phase 4 Premiere Pro MCP MVP surface with ingest/index/rough-cut/caption/audio/export/QC plans
+- Phase 5 macro tool surface
+- Phase 6 optional GPL adapter package boundary
+- Phase 9 safety policy
+- Phase 10 dashboard
+- Phase 11 public repository files
+- Phase 15 v2.0+ manifests for USD/MaterialX/engine profiles, brand packages, social variants, multilingual subtitles, thumbnails, podcast repurposing, Director Agent handoff, production report, and multi-agent review
+- server-side JSON Schema validation
+- artifact path traversal hardening
+- workspace input allowlist
+- symlink realpath escape rejection by default
+- pending approval artifact queue
+- Dashboard localhost bind and token-protected API
+- adapter availability JSON report
+- headless Blender, glTF optimizer, FFmpeg QC, thumbnail, and Premiere CEP queue adapters
+- Blender bridge queue/status adapter surface
+- Blender bridge worker process for queue draining, status writing, processed-command archival, and headless Blender script execution
+- Blender QC coverage for normals, primary UVs, material count, and texture slots
+- Blender optimization size metrics and safe generated Blender script artifacts
+- template-based Blender basic repair for scale, normals, triangulation, and GLB export
+- Blender GLB e2e sample
+- optional WhisperX, PySceneDetect, and pyloudnorm adapter tools
+- optional FFmpeg libvmaf adapter tool
+- Dashboard approval queue UI, artifact previews, and job history
+- Premiere CEP panel MVP for OTIO media import, duplicate import avoidance, sequence creation attempts, timeline-positioned clip insertion attempts, export command handling, brand package command handling, and standardized status JSON
+- Dashboard approval-to-rerun flow for approved elevated tool requests
+- Premiere CEP status reader
+- Premiere CEP status polling and export delivery QC finalization
+- generated-MP4 Premiere QC/CEP queue e2e sample
+- Premiere project-specific delivery builder for template, OTIO timeline, brand package, export plan, and CEP command queue generation
+- Premiere CEP host simulator for queue draining, host.jsx dispatch, status writing, processed-command archival, and project-delivery preflight validation
+- split CI jobs for Node.js 20/22/24 unit tests, package dry-run, adapter check, optional Blender e2e, and Premiere QC e2e
+- dashboard and Premiere real-project e2e docs
+- release asset generation script and npm publish readiness docs
+- npm trusted-publishing workflow with OIDC, release tag/package version guard, and publish gates
+- CEP status, artifact schema, and troubleshooting docs
+- strict public top-level tool schemas with enum and length guards
+- API tool list and compatibility matrix docs
+- Premiere CEP development install/uninstall script
+- Premiere CEP unsigned package generation, manifest validation, checksum output, ZIP verification, and optional ZXP signing hook
+- Premiere CEP queue watcher UI for selected/all pending commands
+
+## External Adapter Work
+
+- project certificate-backed signed Premiere CEP installer and live Premiere runtime validation

package/docs/SAFETY.md

@@ -0,0 +1,21 @@
+# Safety
+
+Permission levels:
+
+- `read_only`: inspect, index, QC
+- `safe_write`: new files, reports, manifests, copies
+- `project_write`: edits to current project or export plans
+- `destructive`: delete, overwrite, final delivery export, publish
+- `admin`: shell, plugin install, system settings
+
+Set the level with `CREATIVE_MCP_PERMISSION`. Default is `safe_write`.
+If a tool requires more permission than the current level, the router writes an approval request under `artifacts/approvals/pending/` instead of running the tool.
+Approval requests include the action, risk, requested input, artifact root, workspace roots, an expiry timestamp, and a one-time approval token for auditability.
+The dashboard exposes those pending approval records, can move them to resolved approval records with an approve/reject decision, and reruns approved tool calls only with the risk level that was approved.
+
+Set readable input roots with `CREATIVE_MCP_WORKSPACE_ROOTS`. Multiple roots use the platform path delimiter (`:` on macOS/Linux, `;` on Windows). By default only the current working directory is readable.
+Symlinks resolving outside those roots are rejected by default. Set `CREATIVE_MCP_ALLOW_SYMLINKS=true` only for trusted workspaces.
+
+The dashboard is local-only. It binds to `127.0.0.1`, requires `CREATIVE_MCP_DASHBOARD_TOKEN`, and can rerun approved elevated tool calls. Do not expose it outside the local machine.
+
+Always test against copies of production files.

package/docs/SECURITY.md

@@ -0,0 +1,14 @@
+# Security
+
+See [../SECURITY.md](../SECURITY.md).
+
+Key controls:
+
+- small macro tool surface
+- approval policy
+- server-side JSON Schema validation
+- workspace input allowlists
+- approval request artifacts for elevated tools
+- artifact logs
+- external adapter separation
+- raw script blocking in the Windows CEP helper

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,46 @@
+# Troubleshooting
+
+## Adapter Check
+
+```bash
+npm run check:adapters -- --json
+```
+
+Missing adapters are allowed unless the workflow explicitly depends on them.
+
+If `ffmpeg-libvmaf` is missing, install an FFmpeg build that includes the `libvmaf` filter. `premiere.measure_vmaf` still writes an adapter report when the filter is unavailable.
+
+## Dashboard
+
+If the dashboard refuses API requests, confirm the token:
+
+```bash
+CREATIVE_MCP_DASHBOARD_TOKEN=change-me npm run start:dashboard
+curl -H "x-creative-mcp-dashboard-token: change-me" http://127.0.0.1:4173/api/reports
+```
+
+The dashboard only accepts localhost host headers.
+
+## Workspace Paths
+
+If an input path is rejected:
+
+- confirm it is under `CREATIVE_MCP_WORKSPACE_ROOTS`
+- avoid symlinks to files outside the workspace
+- set `CREATIVE_MCP_ALLOW_SYMLINKS=true` only for trusted workspaces
+
+## Premiere CEP
+
+If a command remains pending:
+
+- confirm the panel queue directory points to `artifacts/premiere/cep_queue`
+- click refresh queue in the CEP panel
+- run selected or all pending commands
+- inspect `artifacts/premiere/cep_status`
+
+## Release Assets
+
+```bash
+npm run release:assets
+gh release upload v<version> dist/release/* --clobber
+```

package/docs/examples/adapter_check_report.sample.json

@@ -0,0 +1,60 @@
+{
+  "generatedAt": "2026-01-01T00:00:00.000Z",
+  "summary": {
+    "available": 3,
+    "total": 9
+  },
+  "adapters": {
+    "ffprobe": {
+      "available": true,
+      "command": "ffprobe",
+      "status": 0
+    },
+    "ffmpeg": {
+      "available": true,
+      "command": "ffmpeg",
+      "status": 0
+    },
+    "ffmpeg-libvmaf": {
+      "available": false,
+      "command": "ffmpeg",
+      "status": 0,
+      "requiredOutput": "libvmaf"
+    },
+    "blender": {
+      "available": false,
+      "command": "blender",
+      "status": null,
+      "stderr": ""
+    },
+    "gltf-transform": {
+      "available": true,
+      "command": "gltf-transform",
+      "status": 0
+    },
+    "gltfpack": {
+      "available": false,
+      "command": "gltfpack",
+      "status": null,
+      "stderr": ""
+    },
+    "whisperx": {
+      "available": false,
+      "command": "whisperx",
+      "status": null,
+      "stderr": ""
+    },
+    "scenedetect": {
+      "available": false,
+      "command": "scenedetect",
+      "status": null,
+      "stderr": ""
+    },
+    "pyloudnorm+soundfile": {
+      "available": false,
+      "command": "python3",
+      "status": 1,
+      "stderr": "ModuleNotFoundError: No module named 'pyloudnorm'"
+    }
+  }
+}

package/docs/examples/delivery_qc_report.sample.json

@@ -0,0 +1,30 @@
+{
+  "kind": "media",
+  "target": "examples/source.mp4",
+  "summary": {
+    "status": "pass",
+    "pass": 8,
+    "warn": 0,
+    "fail": 0
+  },
+  "checks": [
+    {
+      "id": "probe.ffprobe_available",
+      "status": "pass",
+      "message": "ffprobe metadata captured",
+      "value": true
+    },
+    {
+      "id": "delivery.duration",
+      "status": "pass",
+      "message": "1s; max 2s",
+      "value": 1
+    },
+    {
+      "id": "video.vmaf",
+      "status": "not_applicable",
+      "message": "No reference media supplied for VMAF",
+      "value": null
+    }
+  ]
+}

package/examples/blender-bridge-queue.mjs

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+const root = process.cwd();
+const queueDir = resolve(root, "artifacts", "examples", "blender-bridge", "queue");
+const statusDir = resolve(root, "artifacts", "examples", "blender-bridge", "status");
+mkdirSync(queueDir, { recursive: true });
+mkdirSync(statusDir, { recursive: true });
+
+callTool("blender.create_asset", { prompt: "low-poly bridge sample" }, {
+  CREATIVE_MCP_BLENDER_IPC_DIR: queueDir,
+  CREATIVE_MCP_BLENDER_STATUS_DIR: statusDir
+});
+callTool("blender.read_bridge_status", {}, {
+  CREATIVE_MCP_BLENDER_IPC_DIR: queueDir,
+  CREATIVE_MCP_BLENDER_STATUS_DIR: statusDir
+});
+
+function callTool(name, args, extraEnv = {}) {
+  const request = JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: { name, arguments: args }
+  });
+  const result = spawnSync("node", ["packages/blender-pro-mcp/dist/server.js"], {
+    cwd: root,
+    input: `${request}\n`,
+    encoding: "utf8",
+    env: { ...process.env, ...extraEnv }
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `Tool failed: ${name}`);
+  }
+  process.stdout.write(result.stdout);
+  const response = JSON.parse(result.stdout);
+  if (!response.result?.structuredContent?.ok && name !== "blender.read_bridge_status") {
+    throw new Error(`Tool returned not ok: ${name}`);
+  }
+  return response.result;
+}

package/examples/blender-e2e.mjs

@@ -0,0 +1,53 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const root = process.cwd();
+const artifacts = resolve(root, "artifacts", "examples", "blender-e2e");
+mkdirSync(artifacts, { recursive: true });
+
+const cubeScript = resolve(artifacts, "create-cube.py");
+const cubePath = resolve(artifacts, "cube.glb");
+writeFileSync(
+  cubeScript,
+  `
+import bpy
+bpy.ops.object.select_all(action='SELECT')
+bpy.ops.object.delete()
+bpy.ops.mesh.primitive_cube_add(size=1)
+bpy.context.object.name = "CreativePipelineCube"
+bpy.ops.export_scene.gltf(filepath=${JSON.stringify(cubePath)}, export_format='GLB')
+`,
+  "utf8"
+);
+
+run("blender", ["--background", "--factory-startup", "--python", cubeScript]);
+callTool("blender.render_preview", { path: cubePath });
+callTool("blender.optimize_asset", { path: cubePath });
+callTool("blender.validate_asset", { path: cubePath, maxTriangles: 1000 });
+
+function callTool(name, args) {
+  const request = JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: { name, arguments: args }
+  });
+  const result = spawnSync("node", ["packages/blender-pro-mcp/dist/server.js"], {
+    cwd: root,
+    input: `${request}\n`,
+    encoding: "utf8"
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `Tool failed: ${name}`);
+  }
+  process.stdout.write(result.stdout);
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, { cwd: root, encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `${command} failed`);
+  }
+}
+

package/examples/brief.txt

@@ -0,0 +1,2 @@
+Create a 60-second vertical social edit with captions, normalized audio, and delivery QC.
+

package/examples/minimal.gltf

@@ -0,0 +1,23 @@
+{
+  "asset": { "version": "2.0", "generator": "creative-pipeline-mcp-test" },
+  "nodes": [{ "mesh": 0 }],
+  "meshes": [
+    {
+      "primitives": [
+        {
+          "attributes": { "POSITION": 0 },
+          "indices": 1,
+          "material": 0
+        }
+      ]
+    }
+  ],
+  "accessors": [
+    { "count": 3, "min": [0, 0, 0], "max": [1, 1, 0] },
+    { "count": 3 }
+  ],
+  "materials": [{ "name": "Default" }],
+  "textures": [],
+  "images": []
+}
+

package/examples/premiere-project-delivery.mjs

@@ -0,0 +1,72 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const root = process.cwd();
+const mediaDir = resolve(root, "artifacts", "examples", "premiere-project-delivery");
+const queueDir = resolve(root, "artifacts", "examples", "premiere-project-delivery", "cep_queue");
+const statusDir = resolve(root, "artifacts", "examples", "premiere-project-delivery", "cep_status");
+rmSync(queueDir, { recursive: true, force: true });
+rmSync(statusDir, { recursive: true, force: true });
+mkdirSync(mediaDir, { recursive: true });
+mkdirSync(queueDir, { recursive: true });
+mkdirSync(statusDir, { recursive: true });
+
+const mediaPath = join(mediaDir, "source.mp4");
+writeFileSync(mediaPath, new Uint8Array([0]));
+
+callTool("premiere.build_project_delivery", {
+  path: mediaPath,
+  template: "youtube_16x9",
+  sequenceName: "Creative Pipeline Project Delivery",
+  targetDuration: 30,
+  brand: {
+    primaryColor: "#1f6feb",
+    fontFamily: "Inter",
+    titleStyle: "clean_lower_third"
+  },
+  outputPath: join(mediaDir, "final.mp4")
+}, {
+  CREATIVE_MCP_PERMISSION: "project_write",
+  CREATIVE_MCP_PREMIERE_IPC_DIR: queueDir,
+  CREATIVE_MCP_WORKSPACE_ROOTS: root
+});
+run("node", [
+  "scripts/simulate-premiere-cep.mjs",
+  "--queue",
+  queueDir,
+  "--status",
+  statusDir
+]);
+
+function callTool(name, args, extraEnv = {}) {
+  const request = JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: { name, arguments: args }
+  });
+  const result = spawnSync("node", ["packages/premiere-pro-mcp/dist/server.js"], {
+    cwd: root,
+    input: `${request}\n`,
+    encoding: "utf8",
+    env: { ...process.env, ...extraEnv }
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `Tool failed: ${name}`);
+  }
+  process.stdout.write(result.stdout);
+  const response = JSON.parse(result.stdout);
+  if (!response.result?.structuredContent?.ok) {
+    throw new Error(`Tool returned not ok: ${name}`);
+  }
+  return response.result;
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, { cwd: root, encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `${command} failed`);
+  }
+  process.stdout.write(result.stdout);
+}