@amg555/frameforge-mcp 2.3.2 → 2.3.3

package/.mcp.json

@@ -6,7 +6,7 @@
     "remote": "CLOUDFLARE REMOTE MCP: Connects via edge URL. Saves ~80% prompt context tokens in your IDE."
   },
   "_paths": {
-    "agent-first": "Path 1 — your IDE writes scenes, FrameForge renders. Only TTS + image keys needed. No LLM key.",
+    "agent-first": "Path 1 — your IDE writes scenes, FrameForge renders with code-driven animations & user media. Only TTS needed. No LLM key.",
     "auto-research": "Path 2 — FrameForge researches and scripts autonomously. Requires PROVIDER_LLM + its key."
   },
 
@@ -17,8 +17,7 @@
       "command": "node",
       "args": ["src/mcp-server/stdio.js"],
       "env": {
-        "PROVIDER_TTS":   "edge-tts",
-        "PROVIDER_IMAGE": "pollinations"
+        "PROVIDER_TTS":   "edge-tts"
       }
     },
 
@@ -28,7 +27,6 @@
       "args": ["src/mcp-server/server.js"],
       "env": {
         "PROVIDER_TTS":   "edge-tts",
-        "PROVIDER_IMAGE": "pollinations",
         "MCP_PORT":       "3210"
       }
     },

package/CHANGELOG.md

@@ -51,7 +51,7 @@ All notable changes to FrameForge are documented here.
   - `scripts/verify.py` — 7-gate quality verification (same gates as `QualityGate`)
   - `scripts/transcribe.py` — Whisper word-level caption outline generator (`openai-whisper`, free local)
   - `scripts/capture.mjs` — headless Playwright screenshot for b-roll (site, tweet, URL)
-  - `scripts/stock.py` — Pexels stock footage/image downloader (free API key); Pollinations fallback for images
+  - `scripts/stock.py` — Pexels stock footage/image downloader (free API key) with user media asset stubs
   - `scripts/html-renderer/new-project.mjs` updated: copies real engine files instead of writing stubs; includes all 8 scripts
 - **Tool 14: `get_job_status`** — MCP tool to poll a job queued by `queue_full_pipeline`. Returns `{ status, stage, result, error }`. Added to `src/mcp-server/server.js`; automatically available on stdio transport. 5 new tests.
 - **Cloudflare KV rate limiter** — sliding-window 100 req/hr per bearer token. SHA-256-hashed key stored in `RATE_LIMITS` KV namespace. Returns HTTP 429 + `Retry-After` when exceeded. KV binding documented in `cloudflare-mcp/wrangler.toml`. Rate-limiting skipped when KV not bound (local dev).

package/CLAUDE.md

@@ -50,7 +50,7 @@ If you're not sure what a tool does — call it with the obvious parameters. The
 
 1. **Never write driver/helper scripts** to work around a tool's missing parameter. If you think a parameter is missing, check the tool schema again — it's probably there (`voice`, `language`, `orientation`, `parallelism`, `skipImages`, `skipTts`).
 2. **Never write a v2 or v3 of a script.** If the first approach fails, report the error and ask the user what to do.
-3. **Never retry a provider failure yourself.** The pipeline has retry logic built in. If Pollinations rate-limits: report it, suggest `PROVIDER_IMAGE=falai`, and stop.
+3. **Never retry a provider failure yourself.** The pipeline has retry logic built in. If a provider fails: report it and stop.
 4. **Never restart the MCP server.** The server picks up env from its launch context. If a voice or provider needs to change, set the right parameter in the tool call — `voice`, `language`, `parallelism`.
 5. **One tool call, then wait for the result.** Do not queue multiple tool calls before seeing what the first one returned.
 
@@ -60,9 +60,9 @@ If you're not sure what a tool does — call it with the obvious parameters. The
 
 > **The primary path is Path 2 (code-driven animation).** Every frame is a pure function of time `t`, rendered by Playwright + FFmpeg. This is what produces the high-quality, viral-style motion graphics clips. Path 1 (FFmpeg + AI images) is the fast fallback when Playwright is unavailable or the user wants a quick draft. Path 3 (auto-research) is for unattended batch.
 
-### Path 1 — You write the scenes + AI images (quick draft)
+### Path 1 — You write the scenes (code animation & user media)
 
-Your IDE model writes the scenes. FrameForge generates TTS + AI images + renders with FFmpeg.
+Your IDE model writes the scenes. FrameForge synthesizes TTS, binds user media (`image_path` / `video_path`) or procedural kinetic typography, and renders with FFmpeg.
 
 ```
 create_video_from_script({
@@ -70,15 +70,16 @@ create_video_from_script({
     {
       narration: "Text spoken aloud by the voice.",
       caption: "OVERLAY TEXT",                        // max 40 chars, burned into video
-      visual_description: "image prompt for AI"       // be specific and descriptive
+      visual_description: "concept description",      // used for card styling
+      image_path: "assets/photo.jpg",                 // optional: user manual image
+      video_path: "assets/clip.mp4"                   // optional: user manual video clip
     }
   ],
   title: "My Video",
   orientation: "landscape",    // "landscape" (1920×1080) or "portrait" (1080×1920 for Shorts/Reels)
   voice: "ml-IN-MidhunNeural", // optional: any edge-tts voice ID (auto-selected from language if omitted)
   language: "ml",              // optional: BCP-47 code — auto-selects voice (ml, hi, ta, te, zh, ja, ...)
-  imageStyle: "flat design, white background, bold primary colors",
-  parallelism: 1,              // keep at 1 for Pollinations; raise to 4 only with falai/replicate
+  parallelism: 1,
   withMusic: true
 })
 ```
@@ -90,13 +91,13 @@ Output files appear in `.frameforge-files/`:
 - `short_1_<id>.mp4` — auto-extracted vertical Short
 - `video_meta.json` — title, description, tags
 
-> **No API keys needed.** `edge-tts` (voice) and `pollinations` (images) are both free. If Pollinations is slow, tell the user to set `PROVIDER_IMAGE=falai` in `.env`.
+> **No API keys needed.** `edge-tts` (voice) runs offline and visual cards render procedurally with FFmpeg/Playwright. 100% deterministic, zero diffusion artifacts.
 
 ---
 
 ### Path 2 — Code-driven animated video (Playwright + FFmpeg, no AI images)
 
-Use this when: the user wants motion graphics, Pollinations is unavailable, or they ask for "animated", "code-rendered", "explainer", "reel", or "YouTube-style" video. Every frame is a pure function of time `t`.
+Use this when: the user wants motion graphics, explainer, reel, or YouTube-style video. Every frame is a pure function of time `t`.
 
 > **Iron rule:** Never use `Math.random()`, `Date.now()`, `setTimeout`, or module-level mutable state in scene code. Use `hash(i)` from `reel/engine.js` for deterministic randomness.
 
@@ -218,9 +219,9 @@ get_job_status({ jobId })   // poll every 30s until status = "SUCCEEDED"
 | `scaffold_animation_project` | Scaffold a Playwright + FFmpeg animation project (engine, render scripts, STORYBOARD.md) |
 | `validate_storyboard` | Enforce the 4 hard gates before any scene code |
 | `render_animation` | Playwright renderer: `sheet` / `strip` / `storyboard` / `crop` / `full` / `mux` / `kit` / `look` |
-| `multi_voice_tts` | TTS per-call: `edge-tts` · **`voxforge`** · `elevenlabs` · `azure` · `openai` · `webhook` |
+| `multi_voice_tts` | TTS per-call: `edge-tts` · `elevenlabs` · `voxforge` · `azure` · `openai` · `webhook` |
 | `export_to_editor` | Send finished animation to Premiere / Resolve / CapCut / After Effects / Remotion |
-| `external_platform_call` | HTTP bridge to VoxForge, Runway, Kling, Pika, or any platform |
+| `external_platform_call` | HTTP bridge to **any** app — pass `platformUrl` directly, no env setup needed |
 
 **Secondary — FFmpeg + AI images (fast draft, no Playwright needed):**
 
@@ -270,29 +271,106 @@ VOXFORGE_VOICE=my-cloned-voice-id
 
 ---
 
-## EDITOR BRIDGES — send animation to editing apps
+## CUSTOM APP MCP — connect any app instantly
 
-After `render_animation full`, send the finished MP4 into any editing app:
+`external_platform_call` connects to any HTTP app **without touching `.env`** — pass `platformUrl` directly:
 
 ```
-// Export EDL timeline first (for apps that support it)
-render_animation({ projectDir: "...", mode: "kit" })
+// Connect any custom app or MCP-enabled tool right now
+external_platform_call({
+  action: "ingest",
+  platformUrl: "http://localhost:8080",   // your app's base URL
+  platformKey: "optional-api-key",        // omit if no auth
+  files: [".frameforge-files/final.mp4"]
+})
+
+// Drive editing operations in your custom app
+external_platform_call({
+  action: "edit",
+  platformUrl: "http://localhost:8080",
+  operations: [
+    { op: "cut",        at: 4.5 },
+    { op: "color",      clip: 0, lut: "/luts/film.cube" },
+    { op: "caption",    at: 2.0, duration: 3.0, text: "Intro", position: "bottom" },
+    { op: "transition", between: [0, 1], type: "dissolve", duration: 0.5 }
+  ]
+})
+
+// Use a named preset (auto-fills default paths for known apps)
+external_platform_call({
+  action: "render",
+  platformName: "resolve",   // premiere | resolve | runway | voxforge | capcut | ...
+  metadata: { exportPath: "/exports/final.mp4" }
+})
+```
+
+**Your app only needs to accept POST JSON.** FrameForge sends:
+- `ingest` → `multipart/form-data` with the files
+- `edit` → `{ operations: [...], source: "frameforge" }`
+- `render` → `{ scenes: [...], productionId: "...", ...metadata }`
+- `status` → `GET /<statusPath>/<jobId>`
+
+---
+
+## EDITOR BRIDGES — import and edit in external apps
+
+`export_to_editor` supports four actions: **import**, **edit**, **render**, **status**.
+
+### Import a finished animation
 
-// Send to DaVinci Resolve (default bridge port :8080)
-export_to_editor({ projectDir: "...", editor: "resolve" })
+```
+// Auto-generates EDL and imports MP4 + EDL into DaVinci Resolve
+export_to_editor({ editor: "resolve", action: "import", projectDir: ".frameforge-files/my-anim/" })
+
+// Premiere Pro (requires CEP companion server)
+export_to_editor({ editor: "premiere", action: "import", projectDir: "..." })
+
+// Explicit video path (no projectDir needed)
+export_to_editor({ editor: "resolve", action: "import", videoPath: "/path/to/output.mp4" })
+```
+
+### Apply editing operations
+
+```
+export_to_editor({
+  editor: "resolve",
+  action: "edit",
+  timelineName: "MyFilm",
+  operations: [
+    { op: "cut",        at: 4.5 },
+    { op: "transition", between: [0, 1], type: "dissolve", duration: 0.5 },
+    { op: "color",      clip: 0, lut: "/path/to/film.cube" },
+    { op: "caption",    at: 2.0, duration: 3.0, text: "Chapter 1", position: "bottom" },
+    { op: "trim",       clip: 1, startDelta: 0.3 },
+    { op: "speed",      clip: 2, factor: 0.5 },
+    { op: "mute",       clip: 3 },
+    { op: "swap",       clip: 0, newPath: "/new/take.mp4" }
+  ]
+})
+```
 
-// Send to Premiere Pro (bridge port :7777)
-export_to_editor({ projectDir: "...", editor: "premiere" })
+### Trigger the editor's own render/export
 
-// Send to CapCut (bridge port :9090)
-export_to_editor({ projectDir: "...", editor: "capcut" })
+```
+export_to_editor({ editor: "resolve", action: "render", exportPath: "/exports/final.mp4" })
+// → returns { jobId }
 
-// Custom endpoint
-export_to_editor({ projectDir: "...", editor: "custom", editorUrl: "http://localhost:4000" })
+export_to_editor({ editor: "resolve", action: "status", jobId: "..." })
+// → returns { status, outputUrl }
 ```
 
-Bridge servers run locally alongside the app. Setup docs: `docs/editor-bridges/`.
-Override ports: `RESOLVE_BRIDGE_URL`, `PREMIERE_BRIDGE_URL`, `CAPCUT_BRIDGE_URL`, `AE_BRIDGE_URL`.
+### What's supported per editor
+
+| Editor | import | edit ops | render | Notes |
+|--------|--------|----------|--------|-------|
+| `resolve` | ✅ | ✅ | ✅ | Built-in REST API (Resolve 18.6+). Enable in Preferences → System → General → "IP Remote Control". No bridge install needed. |
+| `premiere` | ✅ | ✅ | ✅ | Requires CEP companion panel. See `docs/editor-bridges/premiere.md`. |
+| `aftereffects` | ✅ | ✅ | ✅ | Requires AE REST bridge. See `docs/editor-bridges/aftereffects.md`. |
+| `remotion` | ✅ | ✅ | ✅ | Remotion is code — operations patch composition props + trigger CLI render. No bridge. |
+| `capcut` | ✅ | ❌ | ✅ | No public desktop edit API. Import + export only. |
+| `custom` | ✅ | ✅ | ✅ | You define what the endpoint handles. |
+
+**Override ports:** `RESOLVE_BRIDGE_URL`, `PREMIERE_BRIDGE_URL`, `CAPCUT_BRIDGE_URL`, `AE_BRIDGE_URL`
 
 ---
 
@@ -358,9 +436,9 @@ Supply any of these per scene — FrameForge only generates what you don't suppl
 **`create_video_from_script` returns `passed: false`:** Check `qcReport.checks` for the failed gate:
 - `resolution`: an `image_path` file has wrong dimensions — use `visual_description` instead
 - `no_audio`: TTS failed — check `edge-tts` is installed
-- `black_frames`: image generation failed for a scene — tell user about Pollinations and suggest `PROVIDER_IMAGE=falai`
+- `black_frames`: visual asset invalid — verify image_path / video_path file paths or use default code-driven visual cards
 
-**Image generation fails silently:** FrameForge falls back to a dark background automatically. The video still renders.
+**Visual fallback:** FrameForge renders crisp code-driven animated cards automatically when no manual media is supplied. The video always renders cleanly.
 
 **Any other tool error:** Report the exact error message to the user. Do not attempt to fix it by editing source files.
 

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@amg555/frameforge-mcp.svg?label=npm)](https://www.npmjs.com/package/@amg555/frameforge-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
-[![Version](https://img.shields.io/badge/version-2.3.2-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.3.3-blue.svg)](CHANGELOG.md)
 [![MCP Spec](https://img.shields.io/badge/MCP-2024--11--05-blue.svg)](https://modelcontextprotocol.io/)
 [![Tests](https://img.shields.io/badge/tests-512%20passing-brightgreen.svg)](#testing)
 
@@ -135,7 +135,7 @@ short_1_<id>.mp4       →  auto-extracted 9:16 vertical Short
 video_meta.json        →  title, description, tags, chapters
 ```
 
-**No API keys required for this path.** `edge-tts` (voice) and `pollinations` (images) are both free with no account. If Pollinations is slow, add `FALAI_API_KEY` and set `PROVIDER_IMAGE=falai`.
+**No API keys required for this path.** `edge-tts` (voice) runs offline and visual cards render procedurally via FFmpeg/Playwright. 100% deterministic, zero diffusion flaws.
 
 ---
 
@@ -143,7 +143,7 @@ video_meta.json        →  title, description, tags, chapters
 
 ### Your IDE writes the script — no LLM key needed
 
-Your IDE's model writes the scenes. FrameForge only runs FFmpeg, TTS, and image generation. Use `create_video_from_script`. This is the fastest path and what most people want.
+Your IDE's model writes the scenes. FrameForge runs FFmpeg, TTS, and code-driven kinetic animations or user media. Use `create_video_from_script`. This is the fastest path and what most people want.
 
 ### FrameForge researches and scripts itself
 
@@ -226,17 +226,21 @@ Switch any provider with one `.env` change — no code changes.
 
 Set `PROVIDER_TTS=<name>`.
 
-**Images**
+**Visuals & Media**
 
-| Provider | Free? | Key needed |
-|----------|-------|------------|
-| `pollinations` | ✅ free, no account | none — **default** |
-| `falai` | ✅ free tier | `FALAI_API_KEY` at fal.ai |
-| `replicate` | paid | `REPLICATE_API_KEY` |
-| `dalle` | paid | `OPENAI_API_KEY` |
-| `webhook` | — | `WEBHOOK_IMAGE_URL` |
+FrameForge is **code-driven first**: scenes render via crisp vector animations, kinetic typography, and user-provided media (clips, b-roll, photos) — zero diffusion artifacts, zero AI slop, 100% deterministic.
+
+| Visual Mode / Provider | Type | Key needed |
+|------------------------|------|------------|
+| `code-driven` | **Default** — kinetic cards, typography, spring motion | none — **recommended default** |
+| `user-media` | User-supplied `image_path` or `video_path` in scene | none |
+| `pollinations` | Optional AI diffusion (opt-in via `--ai-images`) | none |
+| `falai` | Optional AI diffusion (fast FLUX) | `FALAI_API_KEY` at fal.ai |
+| `replicate` | Optional AI diffusion (FLUX-schnell) | `REPLICATE_API_KEY` |
+| `dalle` | Optional AI diffusion (DALL-E 3) | `OPENAI_API_KEY` |
+| `webhook` | Custom image/video generation endpoint | `WEBHOOK_IMAGE_URL` |
 
-Set `PROVIDER_IMAGE=<name>`.
+Set `ENABLE_AI_IMAGES=true` or pass `--ai-images` only if you explicitly want AI diffusion images. Default is clean code-driven animation.
 
 **LLM — only for the auto-research path**
 

package/SECURITY.md

@@ -49,7 +49,7 @@ prefer to remain anonymous.
 
 ### Network
 - FFmpeg calls use `-nostdin` to prevent interactive prompts from blocking.
-- All outbound HTTP calls (Pollinations, search APIs, webhook endpoints) use
+- All outbound HTTP calls (search APIs, webhook endpoints) use
   Node.js `https` with explicit timeouts and no silent redirects beyond 5 hops.
 
 ### Cloudflare Workers
@@ -64,8 +64,6 @@ prefer to remain anonymous.
 - The LLM fallback in `FactChecker._querySources()` produces synthesized
   sources when no `SEARCH_API_KEY` is set. These are not real citations and
   should not be presented as authoritative without a real search provider.
-- Pollinations.ai image requests are unauthenticated — do not include
-  private or sensitive content in image prompts.
 - `PUBLISH_WEBHOOK_URL` and `REVIEW_NOTIFY_URL` receivers are trusted
   endpoints; ensure they are authenticated on your side before deploying
   to production.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "description": "FrameForge — AI video production engine for agentic IDEs. npx @amg555/frameforge-mcp. FFmpeg + TTS run on your machine. 17 MCP tools.",
   "publishConfig": {
     "access": "public"
@@ -10,10 +10,14 @@
     "frameforge": "src/cli/make.js",
     "frameforge-mcp": "src/mcp-server/stdio.js",
     "frameforge-setup": "src/cli/setup-keys.js",
-    "frameforge-doctor": "src/cli/doctor.js"
+    "frameforge-doctor": "src/cli/doctor.js",
+    "frameforge-harness": "src/harness/bin/harness.mjs"
   },
   "scripts": {
     "make": "node src/cli/make.js",
+    "harness": "node src/harness/bin/harness.mjs",
+    "harness:doctor": "node src/harness/bin/harness.mjs doctor",
+    "harness:verify": "node src/harness/bin/harness.mjs verify",
     "setup": "node src/cli/setup-keys.js",
     "setup:check": "node src/cli/setup-keys.js --check",
     "doctor": "node src/cli/doctor.js",
@@ -26,7 +30,7 @@
     "start:local-render": "cross-env RENDER_MODE=full WORKER_PORT=3211 node src/worker/server-render-free.js",
     "db:migrate": "node scripts/db-migrate.js",
     "validate": "node scripts/deep-validate.js",
-    "test": "node --test src/pipeline/retry-policy.test.js src/pipeline/telemetry.test.js src/pipeline/artifact-manifest.test.js src/pipeline/artifact-retention.test.js src/pipeline/external-adapter.test.js src/workflows/publishing.test.js src/workflows/script.test.js src/animation/animation-system.test.js src/fact-checker/review-gate.test.js src/fact-checker/checker.test.js src/utils/log-redaction.test.js src/worker/server-render-free.test.js src/worker/server.test.js src/mcp-server/server.test.js src/quality-gate/gate.test.js src/shorts-extractor/extractor.test.js src/audio-mixer/mixer.test.js src/video-renderer/renderer.test.js plugins/video-pipeline/skills/video-pipeline/assets/project/reel/engine.test.js src/integration.test.js",
+    "test": "node --test src/pipeline/retry-policy.test.js src/pipeline/telemetry.test.js src/pipeline/artifact-manifest.test.js src/pipeline/artifact-retention.test.js src/pipeline/external-adapter.test.js src/workflows/publishing.test.js src/workflows/script.test.js src/animation/animation-system.test.js src/fact-checker/review-gate.test.js src/fact-checker/checker.test.js src/utils/log-redaction.test.js src/worker/server-render-free.test.js src/worker/server.test.js src/mcp-server/server.test.js src/quality-gate/gate.test.js src/shorts-extractor/extractor.test.js src/audio-mixer/mixer.test.js src/video-renderer/renderer.test.js plugins/video-pipeline/skills/video-pipeline/assets/project/reel/engine.test.js src/harness/lib/pixels.test.js src/harness/lib/verify-purity.test.js src/harness/harness.test.js src/integration.test.js",
     "lint": "echo 'No linter configured — add eslint for production'",
     "check-credentials": "node src/utils/log-redaction.js",
     "generate-assets": "node scripts/generate-initial-assets.js",

package/plugins/video-pipeline/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "video-pipeline",
+  "displayName": "FrameForge Video Pipeline",
+  "version": "2.3.1",
+  "description": "End-to-end AI video production. IDE writes scenes → FrameForge renders. Or: scaffold a Playwright+ffmpeg code-driven animation. Or: auto-research and script the video.",
+  "skills": [
+    {
+      "name": "video-pipeline",
+      "path": "skills/video-pipeline/SKILL.md",
+      "displayName": "Video Pipeline",
+      "description": "17 MCP tools: create_video_from_script, scaffold_animation_project, render_animation, validate_storyboard, multi_voice_tts, ingest_media, edit_scenes, research_topic, write_script, queue_full_pipeline, and more."
+    }
+  ],
+  "mcpServer": {
+    "command": "npx",
+    "args": ["--yes", "--package=@amg555/frameforge-mcp", "frameforge-mcp"],
+    "description": "Starts the FrameForge MCP server. No install needed — npx pulls from npm."
+  }
+}