MVR — My Video Resource

A self-hosted MCP server and local dashboard for building a reusable AI-video reference library.

MVR stores named Elements — characters, products, locations, styles — as structured, versioned reference images (not just text prompts), and hands that context to any MCP-compatible agent through @tags. It is a creative library and agent-context layer, not a video-generation model: the connected agent still does the actual generation, using its own provider integration.

Table of contents

• Why MVR

• How it works

• Core concepts

• Quickstart

• MCP tools

• HTTP API

• Storage

• Security and operations

• Current scope

Related MCP server: engram

Why MVR

AI video prompts repeat the same character, product, and location descriptions constantly. A small wording difference between scenes is often enough to make a character's face or a product's shape drift. Standard practice among AI video creators is to build a reference sheet for every recurring asset — a locked close-up of a face, a front/back turnaround of a body, a multi-angle sheet for a product — and reuse those exact images in every scene instead of re-describing them in words.

MVR turns that practice into a small, self-hosted service:

• Reference images live in one place, organized by named Element and slot (angle/view), not scattered across chat history.

• Each Element kind (character, prop, location, style) comes with a seeded checklist of which angles it needs, based on what actually keeps AI video output consistent.

• Any MCP-compatible agent — Claude Desktop, Claude Code, Cursor, or a custom agent — can query the same library, so the work of building a character or product sheet is done once and reused everywhere.

How it works

Architecture

flowchart TD
    Creator(["🎬 Creator"])
    UI["Local Dashboard\nlocalhost:8080"]
    Agent["MCP-compatible Agent\nClaude · Cursor · custom"]
    MVR["MVR Server\nMCP tools + REST API"]
    DB[("SQLite Vault\nElements · Configs · Providers")]
    Assets[("Asset Storage\nlocal volume or S3")]
    Provider["External AI Provider\nimage / video generation"]
    Output(["🎥 Generated video / image"])

    Creator -->|manages library, keys| UI
    Creator -->|"chats: use @hero + @headphones"| Agent
    UI -->|REST, bearer token| MVR
    Agent -->|MCP tools, stdio or HTTP| MVR
    MVR --> DB
    MVR --> Assets
    Agent -->|its own provider integration| Provider
    Provider --> Output
    Output -.->|shown back to| Creator

The key boundary: MVR never calls the production generation API itself. It resolves @tags into reference assets and a saved model preference, and returns that to the agent — the agent performs the actual call to Higgsfield, OpenAI, or whichever provider it's configured with.

A typical request, step by step

sequenceDiagram
    participant C as Creator
    participant A as AI Agent
    participant M as MVR Server
    participant P as External Provider

    C->>A: "Generate a shot of @hero putting on @headphones"
    A->>M: resolve_prompt(text)
    M-->>A: resolved_text, elements_used (with asset paths),<br/>completeness_warnings
    A->>M: get_active_model("video-generation")
    M-->>A: provider, model, settings
    A->>P: generate(resolved prompt, references, settings)
    P-->>A: generated video / image
    A-->>C: result, plus any "you're missing @hero's back view" reminder

If an Element referenced in the prompt is missing a required reference angle, MVR does not block the request — it attaches a completeness_warnings entry so the agent can pass the reminder along, and the creator decides whether to fix it now or accept the risk.

How an Element is structured

An Element is not one text field — it's a named record plus a set of slots, where each slot is a real, versioned reference image. The required slots depend on the Element's kind:

flowchart LR
    subgraph Element["Element: @hero (kind: character)"]
        direction LR
        S1["face_closeup\n✅ uploaded"]
        S2["body_front\n✅ uploaded"]
        S3["body_back\n⬜ missing"]
    end
    Element --> Check{"check_element_completeness"}
    Check -->|missing required slot| Warn["completeness_warnings\nreturned to agent"]
    Check -->|all required slots present| OK["Element ready to use"]

These recipes are seeded on first run and can be inspected at any time via get_kind_template.

Core concepts

Quickstart

Local

cp .env.example .env
# Replace MVR_ENCRYPTION_KEY and MVR_AUTH_TOKEN with your own secrets.
npm install
npm run build
npm start

npm run dev       # watch mode
npm run build     # TypeScript build
npm test          # Vitest suite
npm run stdio     # run only the stdio MCP server

Docker

cp .env.example .env
# Replace MVR_ENCRYPTION_KEY and MVR_AUTH_TOKEN.
docker compose up --build

Docker Compose persists the database in the mvr-data volume and bind-mounts ./data/assets to /app/data/assets, so reference images stay inspectable on the host.

Connecting an MCP client

stdio (Claude Desktop, Claude Code, and similar):

{
  "mcpServers": {
    "mvr": {
      "command": "node",
      "args": ["/absolute/path/to/MVR/dist/index.js", "--stdio"],
      "env": {
        "MVR_DB_PATH": "/absolute/path/to/MVR/data/mvr.db",
        "MVR_ASSET_PATH": "/absolute/path/to/MVR/data/assets",
        "MVR_ENCRYPTION_KEY": "your-long-random-secret"
      }
    }
  }
}

Authorization: Bearer your-long-random-token
Accept: application/json, text/event-stream

MCP tools

HTTP API

All endpoints are under /api and require the bearer token when MVR_AUTH_TOKEN is set.

Storage

Local (default):

MVR_STORAGE_DRIVER=local
MVR_ASSET_PATH=/app/data/assets
MVR_ASSET_IMPORT_PATH=/app/data/imports

S3-compatible:

MVR_STORAGE_DRIVER=s3
MVR_S3_BUCKET=your-bucket
MVR_S3_REGION=us-east-1
MVR_S3_ACCESS_KEY_ID=...
MVR_S3_SECRET_ACCESS_KEY=...
MVR_S3_ENDPOINT=https://your-s3-compatible-endpoint   # optional

The SQLite database defaults to data/mvr.db locally and /app/data/mvr.db in Docker. Startup automatically migrates an existing Phase 1 database and seeds any missing templates without touching existing ones.

Security and operations

Current scope

Implemented

• Multi-slot Elements with real, versioned, optionally locked PNG assets

• Completeness checks and non-blocking prompt-resolution warnings

• Seeded kind recipes and a seeded Seedance 2.0 prompt format

• Local and S3-compatible asset storage

• MCP over stdio and authenticated Streamable HTTP

• Local dashboard, encrypted provider-key storage, per-task model configurations

Not yet implemented

• Video/image generation orchestration

• Automated evaluation runs or evaluation-driven template updates

• Multi-user authentication and authorization

See ROADMAP.md for what's planned next.

License