Facebook Creator Agent

Turn a topic into a scripted, licensed, edited video package for a Facebook Page — then review it, approve it explicitly, and publish it (dry-run by default) from any MCP-capable coding agent (OpenCode, Codex, VS Code, Claude, Antigravity, Cursor, …).

This repository is the product:

• MCP server (facebook_creator_agent, Python, stdio + streamable HTTP) exposing 18 typed creator_* tools

• OpenCode operator agent (.opencode/agents/facebook-creator.md) that drives the workflow

• 62 automated tests (unit / security / MCP / real-FFmpeg integration / end-to-end)

• Per-client setup for Codex, VS Code, Claude, Antigravity, Cursor, generic MCP (below)

New here? Install → Configure → Connect your coding agent → Make a video.

Contents

1. Functions & features

2. How it works

3. How to install

4. How to configure

5. How to use it

6. Supported coding agents & clients

7. Tool reference (18)

8. Workspace layout

9. Testing

10. Security model

11. Known limitations

Related MCP server: StarReel MCP

Functions & features

Production pipeline (what it can produce):

Safety features (implemented, tested):

• Explicit-approval publishing — an approval is cryptographically bound to the exact Page, media SHA-256, caption/metadata SHA-256, action, expiry and a one-time nonce; single-use; any change invalidates it.

• Dry-run by default — real uploads require both FCA_ENABLE_LIVE_PUBLISH=1 and a configured token.

• Unknown-outcome protection — upload attempts are journaled before the network call; UNKNOWN results are reconciled via creator_get_publish_status instead of blind retries (no duplicate posts).

• Default-deny media rights — unknown or ambiguous licenses are rejected / flagged for manual review; every asset keeps provenance.

• Secret hygiene — tokens/keys live only in environment/.env; logs are redaction-filtered; nothing sensitive in project files or manifests.

• Path jail, host allowlists, size caps, content-type + magic-byte checks, hashed filenames for all writes and downloads; subprocesses run as argv arrays (never a shell).

Reliability features: explicit state machine, stage manifests + resume, idempotency, cancellation (terminates FFmpeg), bounded timeouts/retries, structured error taxonomy {code, safe_explanation, retryable, stage, next_action}, creator_doctor diagnostics.

Offline-friendly: with no cloud credentials you can still run everything except script generation (needs an LLM endpoint) and live publishing — using fixture folder media + a narration file you supply.

How it works

topic / prompt
   │
   ▼
[1] creator_doctor             environment & config diagnostics
[2] creator_create_project     workspace/projects/<project-id>/
[3] creator_generate_script    brief → script → storyboard      (OpenAI-compatible endpoint, schema-validated)
[4] creator_search_media       allowlisted providers + license policy (default deny)
[5] creator_download_assets    host/size/type checks, SHA-256, provenance
[6] creator_generate_narration TTS command engine — or your own audio file
[7] creator_build_timeline     deterministic edit decision list (EDL)
[8] creator_render_preview     FFmpeg: 9:16 / 16:9, mix, captions → preview.mp4 + final.mp4
[9] creator_validate_render    ffprobe streams/duration + decode test
[10] creator_get_review_package preview + caption + metadata + asset manifest + hashes
──────────────  YOU REVIEW  ──────────────
[11] creator_approve_publish   approval bound to Page + media hash + payload hash + expiry + nonce
[12] creator_publish_video     dry-run by default → journal → upload → SUCCEEDED / FAILED / UNKNOWN
[13] creator_get_publish_status reconcile UNKNOWN outcomes; never blind-retry

State machine per project: NEW → SCRIPT_READY → ASSETS_READY → NARRATION_READY → RENDERED → REVIEW_REQUIRED → APPROVED → PUBLISHING → PUBLISHED (+ FAILED, CANCELLED and documented resume edges — see ARCHITECTURE.md §6).

The application enforces the rules, not the model: the publisher independently revalidates the approval, hashes, Page and token at upload time. A model (or client) cannot bypass the guard by asserting that the user approved.

Design details: ARCHITECTURE.md · PRD.md · status matrix: IMPLEMENTATION_STATUS.md.

How to install

Requirements

Windows (from the repository folder):

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"
.venv\Scripts\python.exe -m facebook_creator_agent tools     :: offline sanity check → 18 tools
.venv\Scripts\python.exe -m facebook_creator_agent doctor    :: diagnostics (JSON; exit 0 ready/partial, 2 blocked)

macOS / Linux:

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m facebook_creator_agent tools
.venv/bin/python -m facebook_creator_agent doctor

No global install is needed — MCP clients launch the venv Python directly.

How to configure

Copy .env.example → .env (git-ignored) and fill in what you have. Non-secret settings also work via environment variables or tool arguments. The server loads .env from its base directory (default: its working directory; pin it with FCA_BASE_DIR).

Diagnostics: .venv\Scripts\python.exe -m facebook_creator_agent doctor --probe-network (also tests the LLM endpoint). Print the effective redacted config with ... print-config.

No TTS engine? Pass narration_path to creator_generate_narration with your own audio file.

How to use it

1. Connect a coding agent

The server speaks standard stdio MCP — any MCP client can launch it with:

command: C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs/.venv/Scripts/python.exe
args:    ["-m", "facebook_creator_agent"]

Plus set FCA_BASE_DIR (and cwd where the client supports it) to this folder. Per-client blocks: see the next section.

2. Ask for a video

Talk to your agent in plain language:

• "make a facebook video about three facts about MCP servers"

• "make a 30-second facebook reel about home coffee brewing, in Hindi, bold tone"

• "show me the review package for project coffee-reel"

With the shipped OpenCode agent, that's:

facebook-creator agent → "make a facebook video about three facts about MCP servers"

The agent runs the pipeline (doctor → project → script → media → narration → timeline → render → validation → review package) and stops at review. If the topic is missing it asks exactly one question.

3. Review & approve

Nothing is published until you say so. Review the preview and caption, then:

"approve it and publish" — or — "change the caption to … and re-render"

The agent records your approval via creator_approve_publish (bound to the exact payload you reviewed) and calls creator_publish_video. Any later change to media/caption/Page invalidates the approval (PUBLISH_APPROVAL_STALE).

4. Publishing for real

Publishing stays dry-run until all three hold:

1. FCA_FACEBOOK_ACCESS_TOKEN is set (official Meta OAuth — never a password; use creator_connect_facebook for the exact official steps),

2. FCA_FACEBOOK_PAGE_ID is set,

3. FCA_ENABLE_LIVE_PUBLISH=1.

Then the publisher revalidates token, Page, permissions, and hashes before upload, journals the attempt, and reports SUCCEEDED / FAILED / UNKNOWN — with creator_get_publish_status for reconciliation.

5. CLI quick reference

.venv\Scripts\python.exe -m facebook_creator_agent                  :: MCP server, stdio (what clients spawn)
.venv\Scripts\python.exe -m facebook_creator_agent serve --transport streamable-http --port 8765
.venv\Scripts\python.exe -m facebook_creator_agent doctor [--probe-network]
.venv\Scripts\python.exe -m facebook_creator_agent tools
.venv\Scripts\python.exe -m facebook_creator_agent print-config     :: redacted effective config
.venv\Scripts\python.exe scripts\verify_mcp_boot.py                 :: MCP handshake + tools/list proof

Supported coding agents & clients

The server is a standard stdio MCP server, so it works with any MCP-capable client. Configs below follow each client's current official MCP documentation. Verified live in this repository: OpenCode. The launch command is identical everywhere — only the config file and key names differ.

Replace C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs in the examples if you move the folder. JSON path separators: forward slashes work on Windows.

OpenCode ✅ (verified live in this repo)

Already shipped — opencode.json. Server name facebook, so the tools appear as facebook_creator_*. Project agent: .opencode/agents/facebook-creator.md.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "facebook": {
        "type": "local",
        "command": ["C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs/.venv/Scripts/python.exe", "-m", "facebook_creator_agent"],
        "cwd": ".",
        "environment": { "FCA_BASE_DIR": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs" }
      }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml (global) or .codex/config.toml (project-scoped):

[mcp_servers.facebook-creator]
command = "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs/.venv/Scripts/python.exe"
args = ["-m", "facebook_creator_agent"]
cwd = "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs"
env = { "FCA_BASE_DIR" = "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs" }
tool_timeout_sec = 300

(tool_timeout_sec is raised because renders can exceed the 60 s default. Codex CLI, the IDE extension, and the ChatGPT desktop app share config.toml.)

VS Code (GitHub Copilot, agent mode)

Workspace .vscode/mcp.json:

{
  "servers": {
    "facebook-creator": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/Scripts/python.exe",
      "args": ["-m", "facebook_creator_agent"],
      "cwd": "${workspaceFolder}",
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Open the file → Start → approve the trust prompt → the tools appear in Copilot Chat (agent mode). The portable workspace-root .mcp.json (top-level mcpServers, no cwd) also works — set FCA_BASE_DIR in env there.

Claude Code

claude mcp add facebook-creator -e FCA_BASE_DIR=C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs -- C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs/.venv/Scripts/python.exe -m facebook_creator_agent

Or commit a project .mcp.json:

{
  "mcpServers": {
    "facebook-creator": {
      "command": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs/.venv/Scripts/python.exe",
      "args": ["-m", "facebook_creator_agent"],
      "env": { "FCA_BASE_DIR": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs" }
    }
  }
}

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "facebook-creator": {
      "command": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs/.venv/Scripts/python.exe",
      "args": ["-m", "facebook_creator_agent"],
      "env": { "FCA_BASE_DIR": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs" }
    }
  }
}

Restart Claude Desktop after editing.

Google Antigravity

~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace), or via … → MCP Servers → Manage MCP Servers → View raw config:

{
  "mcpServers": {
    "facebook-creator": {
      "command": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs/.venv/Scripts/python.exe",
      "args": ["-m", "facebook_creator_agent"],
      "cwd": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs",
      "env": { "FCA_BASE_DIR": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs" }
    }
  }
}

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "facebook-creator": {
      "command": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs/.venv/Scripts/python.exe",
      "args": ["-m", "facebook_creator_agent"],
      "env": { "FCA_BASE_DIR": "C:/Users/KRUNAL/Downloads/facebook_creator_agent_docs" }
    }
  }
}

Any other MCP client

• Transport: stdio (command + args) — no HTTP needed. A streamable-HTTP mode also exists (serve --transport streamable-http --port 8765) for clients that prefer URLs.

• Launch: <repo>/.venv/Scripts/python.exe (Windows) or <repo>/.venv/bin/python (macOS/Linux) with args -m facebook_creator_agent.

• Env: set FCA_BASE_DIR to the repo folder unless the client launches with that working directory.

• Tool names: canonical creator_*; most clients prefix with the server name (e.g. facebook_creator_* in OpenCode).

Tool reference (18)

Every tool returns a structured envelope: status (ok/error), tool, project_id, artifacts, warnings, next_action, error = {code, safe_explanation, retryable, stage, next_action}, and data.

Project workspace layout

workspace/projects/<project-id>/
  project.json brief.md research.json script.md storyboard.json
  assets/{manifest.json, assets.json, candidates.json, clips/, images/, audio/}
  narration/{narration.*, narration.json}
  captions/subtitles.srt
  timeline/{edit_decision_list.json, segments_v*.txt}
  renders/{final.mp4, preview.mp4, cover.jpg, v<N>/…}
  review/{publish_payload.json, review_package.json, approval.json, approvals_log.jsonl, publish_attempts.json}
  logs/

Secret tokens and API keys never live inside workspace/.

Testing

.venv\Scripts\python.exe -m pytest -q              :: 62 tests
.venv\Scripts\python.exe scripts\verify_mcp_boot.py :: MCP handshake + tools/list proof

• tests/unit — config validation, redaction, path jail, state machine, approval guard (expiry / hash-mismatch / replay), error contract

• tests/security — license default-deny; downloader host allowlist, redirects, size caps, content-type + magic bytes (mocked HTTP)

• tests/mcp — stdio boot, tool discovery = 18, invalid args → structured errors

• tests/integration — real FFmpeg 9:16 render with narration mix, ffprobe + decode validation

• tests/e2e — full pipeline with a deterministic fake LLM + mocked Facebook network: dry-run → live → idempotent replay; user-media intake behind the rights gate; negatives PUBLISH_APPROVAL_REQUIRED, PUBLISH_APPROVAL_STALE

Security model

1. Approval gate — publication is impossible without an approval matching the exact Page, media SHA-256, payload SHA-256, action and unexpired nonce; single-use; revalidated independently at upload time.

2. Dry-run default — live uploads double-gated (FCA_ENABLE_LIVE_PUBLISH=1 + token).

3. UNKNOWN outcomes — journaled, reconciled, never blind-retried.

4. Default-deny media rights — allowlisted providers/licenses only; provenance + hashes preserved; ambiguous rights → manual review.

5. Secrets — environment/.env only; redacted logs; never in project files or prompts.

6. Filesystem — canonicalized path jail under the workspace root; hashed filenames for downloads; safe overwrite rules.

7. Network — host allowlists per provider, manual redirect validation, size/type limits (SSRF-reducing).

8. Shell — subprocesses run as argv arrays; stdout is reserved for the MCP protocol.

Known limitations

• Live external services are not claimed as verified in this repository — Meta Graph publishing, live Pexels stock, and live TTS engines have no credentials here. Their code paths are capability-gated, mock-tested, and marked in IMPLEMENTATION_STATUS.md. Script generation against a real LLM endpoint is likewise unverified here.

• Reels-specific endpoints and scheduling are feature-gated and not claimed (they depend on Meta app review and granted permissions).

• The 16:9 render path is implemented but only 9:16 is exercised by the automated suite.

• Per-client auto-configuration is not performed automatically; the sections above are the documented setup (matching TASK.md T1001–T1005).

Repository documents

License: proprietary (placeholder — choose before distribution).