Skip to main content
Glama
README.md
# Visual Production MCP

[![CI](https://github.com/kivervinicius/visual-production-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kivervinicius/visual-production-mcp/actions/workflows/ci.yml)

**v0.2.0 — experimental, local-first production coordinator.** Not a working end-to-end Google Flow / Higgsfield video generator yet.

A provider-neutral Model Context Protocol (MCP) server to help coding agents such as Codex and Antigravity plan audiovisual productions, share **immutable character identities** across episodes, track account-local projects, allocate independent per-account budgets and preserve downloaded results.

**Important:** A canonical production in this repository is **not** a Google Flow project. Provider-local projects must be created, populated and verified separately. This project does not transfer Google credits between accounts, bypass provider restrictions or make private APIs official.

## What works now

- Local `production.json` import/export with path validation and SHA-256-addressed reference files.
- Versioned cross-project character registry using an explicit `libraryId` (e.g. `arquivo-amanha/vesper`) and immutable `version` / reference hashes; projects without `libraryId` are scoped by project ID.
- Account-specific native project, asset and character bindings. `studio_sync_plan` reports missing dependencies. Bindings are operator-reported until an adapter verifies them.
- Independent, operator-entered credit estimates. Job planning is idempotent, and paid dispatch requires explicit local operator approval. No automatic account rotation or retries after ambiguous submissions.
- Read-only `studio_preflight`: missing references, local upstream configuration and optionally discovered MCP tool names; it does **not** verify login or live balance.
- `studio_ingest_result`: requires a submitted provider operation ID, copies an existing local file into content-addressed storage, validates image signature or uses FFprobe to inspect video, records the hash and sets **editorial review to pending**.
- Local-only operator CLI for reconciliation of uncertain submissions and editorial approval/rejection.
- MCP v2 stdio host with upstream MCP discovery and a restrictive allowlisted dispatch bridge.
- 12 Node built-in tests (local core); provider/browser end-to-end tests remain outstanding.

## Install

Requires Node.js 20+, `npm` and FFprobe for importing videos.

```bash
npm install
npm run check
npm test
cp examples/upstreams.example.json .studio/upstreams.json  # create .studio first
```

Correct first-time setup:

```bash
mkdir -p .studio
cp examples/upstreams.example.json .studio/upstreams.json
```

In Codex, register the server with the absolute path after installing packages:

```bash
codex mcp add visual-production -- node /absolute/path/to/visual-production-mcp/src/server.mjs
```

Antigravity and other MCP hosts should use `command=node`, `args=[absolute path to src/server.mjs]`, and optionally `STUDIO_HOME=/absolute/workspace/.studio`. Avoid running several simultaneous **provider browser sessions** against the same Chrome profile. No Google credentials or cookies should be placed in source control.

## Workflow

1. Build a versioned production manifest from editorial source files (do not invent story details). `studio_import_project` registers the local production.
2. `studio_register_account` for each separately authorized provider session, setting `creditEstimate` from that account (not a global pool).
3. `studio_plan` creates a persistent set of independent shot jobs, defaulting to `awaiting_approval`.
4. For each assigned shot, `studio_sync_plan` describes missing resources on that account. Create them through a verified provider integration and `studio_bind_project` with native IDs.
5. `studio_preflight` checks local prerequisites. A human checks the real provider login, project, available options, expected credit quote and terms.
6. Human approves expenditure: `npm run operator -- approve <jobId>`. Dispatch via `studio_dispatch_job` only if upstream tool name/inputs can be verified. Upstream output is not assumed successful just because it returned text.
7. If a submission was ambiguous, inspect Flow **manually** and run `npm run operator -- reconcile <jobId> <externalJobId>` only after validating the operation. **Do not submit again automatically.**
8. Download the generated file through the provider's supported interface, then `studio_ingest_result` with that local path. Only an existing provider job with a known operation ID can be completed.
9. After inspecting story, continuity and visual quality, human runs `npm run operator -- review <jobId> approved|rejected [note]`.
10. `studio_bundle` exports the original canonical manifest and reference bytes; this does not clone a native Flow project.

## MCP tools (14)

| Tool | Purpose |
| --- | --- |
| `studio_status` | Account/project/job state |
| `studio_library` | Versioned character catalog |
| `studio_import_project` | Canonical manifest import |
| `studio_register_account` | Logical authorized account |
| `studio_update_balance` | Operator-entered balance estimate |
| `studio_bind_project` | Provider-specific native bindings |
| `studio_sync_plan` | Find missing remote characters and references |
| `studio_plan` | Idempotent shot assignment |
| `studio_preflight` | Read-only compatibility check |
| `studio_discover_upstream` | List real available upstream tool schemas |
| `studio_dispatch_job` | Guarded one-shot generation dispatch |
| `studio_record_failure` | Record provider failures/unknown submissions |
| `studio_ingest_result` | Hash and validate an existing media file |
| `studio_bundle` | Export a portable source package |

**Human-only operations are intentionally not exposed via MCP**: approve credit spend, reconcile ambiguous submissions and approve editorial quality. An agent's self-declared `operatorConfirmed=true` is not sufficient authorization.

## Source layout

- `src/core.mjs`: production manifests, character catalog, account bindings, planning and job state.
- `src/upstream.mjs`: local MCP subprocess and guarded generation dispatch.
- `src/preflight.mjs`: read-only diagnostics; never requests paid generation.
- `src/media.mjs`: immutable result ingestion and manual editorial review.
- `src/server.mjs`: MCP tools; `src/cli.mjs`: local operator-only actions.
- `docs/BACKLOG.md`: audited blockers and prioritized milestones.
- `docs/ADAPTER_CONTRACT.md`: expected Google Flow / Higgsfield adapter boundary.
- `docs/REFERENCES.md`: external projects used as references; no third-party code copied.

## Limitations and policy

The server does not yet (a) create projects and upload reference characters into Google Flow, (b) clone projects between accounts, (c) verify live credit balances, (d) download Flow media, (e) generate videos through an authenticated account, or (f) assemble final episodes with FFmpeg. Real integration must be validated separately in each provider's permitted workflows.

Accounts remain separate. Do not automate signups, rotate accounts to evade rate limits, bypass CAPTCHAs, remove provenance marks, or call undocumented private endpoints. Your own account access does not guarantee that multi-account automation is permitted under provider terms.

License: MIT, original source only. State and media under `.studio/` are excluded from Git.

TDQS

B3.2/5.0

Scored across 14 tools

Disambiguation4/5

Most tools map to distinct lifecycle stages, such as importing a project, planning assignments, dispatching a job, recording failure, and ingesting a result. A few planning/inspection tools overlap in phrasing—especially studio_plan vs. studio_sync_plan and studio_preflight vs. studio_sync_plan—so an agent may occasionally hesitate, but the descriptions usually clarify the intended object and scope.

Naming Consistency4/5

All tools share the studio_ prefix and mostly follow a verb_noun pattern like studio_dispatch_job and studio_register_account. There are minor deviations where the suffix is a noun or gerund-like label, such as studio_library, studio_status, and studio_preflight, but the convention remains highly readable.

Tool Count5/5

Fourteen tools is well within the appropriate range for a multi-stage visual production workflow involving accounts, projects, planning, dispatch, failure handling, ingestion, and export. Each tool appears to cover a specific operational need rather than bloating the surface.

Completeness4/5

The tool set covers the core production lifecycle from project import and account registration through planning, dispatch, result ingestion, status, and portable export. Some lifecycle gaps remain, such as explicit project/account deletion or editorial review actions beyond marking a result complete pending review, but these are minor workarounds rather than dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues