Ceo MCP Media

Standalone durable media-production MCP for ChatGPT/Ceo3. It is deliberately separate from Ceo-MCP-Agent.

V1-V11

• V1 MCP foundation, projects, storyboards, provider contracts, durable jobs, FFmpeg composition.

• V2 Character Bible/Lock, reference images, multi-shot continuity, single-shot regeneration.

• V3 durable voice/music jobs, subtitles, audio composition, 16:9/9:16/1:1 presets, resolution/FPS metadata.

• V4 Auto Director continuity scoring, bounded retry prompts and render QA hooks.

• V5 provider router, Gemini image + Veo long-running adapter, optional Google Flow handoff.

• V6 child-MCP manifest and Ceo3 delegation contract with minimal default tool exposure.

• V7 Durable Director / Auto Movie Pipeline with one-call project → anchor → shots → subtitles → compose orchestration, auto-worker, quota/backoff, guardrail preflight and stale-job recovery.

• V8 Studio Router: provider=auto uses Gemini API when available; without GEMINI_API_KEY, anchor-image work routes to Google AI Studio Web and video shots route to Google Flow Web as durable external actions. CapCut is supported as a durable final-editor handoff.

• V9 Production Workspace: script/scene files, seeded user reference images, persistent manifest.json, compact progress/status, optional durable voice/music stage, and deterministic CapCut/FFmpeg export folders.

• V10 Production hardening: optional Flow Native executable provider, content-addressed Asset Registry, strong idempotency conflict detection, bounded 4-worker execution, pinned ffmpeg-skill 0.15.3 adapter, loudness/delivery checks and contact-sheet verification with legacy FFmpeg fallback when the skill is unavailable.

• V11 Ceo Flow Browser: bundled Playwright/Chrome driver controls Google Flow directly with a dedicated local browser profile, persistent operation state, duplicate-submit protection, polling/download, reference-image upload and manual-only Google sign-in. No useapi.net dependency is required.

• V12 Temporal Continuity Chain: multi-shot movies default to continuityMode=strict; shots run serially, each completed shot is sampled near its final frame, and that end frame becomes the next shot's real Start Frame. Director prompts also lock action momentum, pose logic, screen direction, camera language, lighting and environment.

• V12.1 Flow continuity hardening: the browser/native driver now commits the prompt first, forces Agent mode off on every shot (including Fast Session reuse), confirms the real Start Frame slot and selected handoff asset before submission, and re-commits the prompt after Flow re-renders the composer.

Related MCP server: hyperframes-mcp

One-call production workflow

media.movie.create returns immediately with a movieJobId, workspaceRoot and manifestPath.

API/local path

brief/script -> preflight -> project -> character/reference lock -> storyboard -> anchor -> <=8s shots -> SRT -> optional voice/music -> FFmpeg/CapCut -> export

No-API browser path

brief/script -> manifest -> AI Studio anchor action -> Flow shot action(s) -> SRT/audio -> CapCut action -> export

After creation, Ceo3 should use movieJobId / media.movie.manifest instead of repeatedly resending every scene prompt through chat. The durable production manifest stores the complete local recipe and progress.

V9 production workspace

Each movie gets its own stable workspace under the media data directory:

<workspace>/
  00-script/
    script.md
  01-anchor/
    anchor_prompt.md
    anchor.jpg
  02-flow/
    shot01.md
    shot01.mp4
    shot02.md
    shot02.mp4
    ...
  03-audio/
    voice.wav
    music.wav
  04-capcut/
    subtitle.srt
    capcut-edit.md
  05-export/
    export.json
    final.mp4
  manifest.json

manifest.json records the phase, shot count, output paths, audio readiness and final export state. media.movie.status exposes compact progress and the next browser/CapCut external action.

V10 orchestration hardening

• provider=flow-native executes a configured local/native Flow adapter through structured stdin/stdout JSON; for video, AUTO prefers the local Ceo Flow Browser, then Gemini API, then browser fallback routes.

• Asset Registry assigns stable asset-<sha256> identities and records path, project/job provenance and content hash for generated/downloaded assets.

• Idempotency keys are request-bound: identical requests reuse the existing job; a changed request with the same key fails with IDEMPOTENCY_CONFLICT.

• Durable worker execution is bounded to four concurrent due jobs; browser external actions remain serial/manual and are never auto-resubmitted.

• npm run install:ffmpeg-skill installs upstream ffmpeg-skill 0.15.3 from pinned commit 7dfbdc5b30a622dbb3c7029e690280b7ac43615e. It does not follow upstream main.

• When that exact skill pin is usable, FFmpeg composition uses declarative render + probe + delivery/loudness check + contact-sheet look verification. When the skill is unavailable, the V9 legacy FFmpeg composer remains the fallback.

• MCP tools expose asset registry and ffmpeg-skill status/doctor/contract/render/probe/check/look operations without accepting raw shell command strings.

V11 Ceo Flow Browser

• media.flow.local_status reports Chrome detection, local state/profile paths and authentication readiness without generating media.

• media.flow.local_auth with action=open opens the dedicated Ceo Flow profile for the user to sign in manually; action=check verifies the session. Passwords, OTPs and CAPTCHA answers are never typed or stored by Ceo MCP Media.

• Flow generation/polling defaults to one normal visible Chrome session exposed only on local CDP (127.0.0.1, default port 9223). This avoids relying on the headless-only path and keeps authentication/project state in the dedicated Ceo Flow profile.

• The driver classifies Flow blockers explicitly (FLOW_UNUSUAL_ACTIVITY, FLOW_PERSON_POLICY, FLOW_GENERATION_RECORD_MISSING) and fails closed. It never retries these states automatically or attempts to bypass Google anti-abuse/policy checks.

• The bundled driver stores operation state under %LOCALAPPDATA%\Ceo\media-data\flow-native and uses %LOCALAPPDATA%\Ceo\flow-browser-profile for the dedicated browser profile by default.

• Video submission uses an exact-once guard immediately before the credit-spending Generate click. If submission state becomes uncertain, the operation fails closed rather than automatically spending credits twice.

• AUTO video routing is authenticated local Flow Native driver -> Gemini API fallback -> Flow Web external action; image/anchor work still prefers Gemini or AI Studio Web because the bundled V11 Flow driver currently exposes video generation only.

Reference images / character continuity

V12 makes temporal continuity a mandatory default for multi-shot movies. With continuityMode="strict" (default), Shot N+1 is not submitted until Shot N is complete and its end-frame handoff image exists. The previous end frame is supplied through the provider's real Start Frame / first-frame input, while the prompt separately locks pose, action momentum, camera/screen direction, lighting and environment. Set continuityMode="off" only when shots are intentionally independent.

media.movie.create.character.referenceImages accepts up to three local seed images. These are used while creating the continuity anchor, then the generated anchor plus seed references are reused across later shots. This is intended for workflows where the user supplies their own character/person reference images.

Optional audio stage

Set generateVoice=true and/or generateMusic=true to insert durable audio jobs after all video shots and subtitles are ready. CapCut handoff receives voice/music paths; FFmpeg composition can use voice plus ducked background music. Real production TTS/music depends on configured providers; the mock provider remains test-only.

Studio Router

Useful tools:

• media.studio.status — inspect AUTO route choices.

• media.studio.route — resolve image/video route without generating.

• media.flow.local_status - inspect the local Ceo Flow Browser driver and authentication readiness.

• media.flow.local_auth - open/check the dedicated Google Flow browser profile for manual sign-in.

• media.external.next — read the next browser/CapCut action Ceo3 should perform.

• media.external.complete — attach the downloaded/exported local file and resume the movie workflow.

• media.external.fail — record a browser/editor failure without corrupting the parent workflow.

• media.movie.manifest — read the persistent production recipe/progress for a movie job.

Default AUTO routing when no Gemini API credential is available:

• Image / anchor: Google AI Studio Web.

• Video: authenticated local Ceo Flow Browser (flow-native) first; Google Flow Web remains fallback.

• Final editor for browser-mode movies: CapCut handoff (configurable).

• Verification/fallback: FFmpeg/ffprobe.

Browser providers are modeled as durable external actions. Ceo3/Playwright or Browser Companion owns signed-in browser interaction and returns local assets to the child workflow. Browser actions do not store or type Google credentials; if Google requests sign-in, pause for manual user sign-in and resume the same durable action.

Durable execution

Long generation never waits inside one MCP request. Jobs persist with idempotency keys, retry/backoff, cancellation, timeout and resumability. Stale running jobs are recoverable after CEO_MEDIA_RUNNING_LEASE_MS. Provider polling has its own error budget and does not consume normal submit retry attempts. External browser/CapCut actions are excluded from auto-worker polling until completed/failed explicitly.

Quota and provider behavior

• 429/Retry-After applies a job retry delay and provider-wide cooldown.

• Explicit provider: "gemini" does not silently fall back to Mock.

• provider: "auto" can choose web studio routes when Gemini API is unavailable.

• Guardrail/non-retryable provider errors fail fast instead of wasting paid retries.

• media.preflight.check detects common third-party character/franchise references and can rewrite them toward an original design before generation.

CapCut

When finalEditor=capcut, V9 emits a capcut.compose external action containing ordered clips, SRT, optional voice/music assets, production manifest and expected final path. Ceo3 should run CapCut doctor/version checks first and prefer a compatible current project template. Automatic publishing/upload remains blocked.

Persistence

If CEO_MEDIA_DATA_DIR is blank/unset, Windows defaults to %LOCALAPPDATA%\Ceo\media-data, so managed child-MCP updates do not erase projects/jobs/assets/workspaces.

Setup

npm install
npm run install:ffmpeg-skill
Copy-Item .env.example .env
npm run typecheck
npm test
npm run build

A Gemini API key is optional. Without it, leave GEMINI_API_KEY blank. For local Google Flow video automation, run npm run flow:auth, sign in manually in the dedicated Ceo profile, and leave that Ceo Flow browser open while media jobs are running. Then run npm run flow:auth-check. The driver reuses that visible authenticated session through local CDP; Flow Web remains available as fallback.

Start MCP stdio server:

npm start

See docs/ARCHITECTURE.md, docs/ROADMAP.md, docs/SECURITY.md, docs/CEO3-DELEGATION.md, and docs/API-NOTES.md.