@reeligence/mcp — MCP server for external AI agents

Lets any MCP-capable agent (Claude Desktop, Claude Code, Cursor, …) drive the Reeligence product-video pipeline end to end through the platform's API:

upload_asset → generate_script → edit_scene / edit_script
  → render_script → get_render_status (poll)
  → get_campaign → get_embed_snippet → get_analytics

It is a stdio MCP server and a pure HTTP client of the platform's /api surface — no database access, nothing runs locally except the tool calls.

Setup

1. Get an agent token — in the web app: Settings → Agent tokens → Create token. Copy the ak_… value (shown once). Scope it to what the agent should do (read, generate, edit, render, publish).
2. Configure your agent. For Claude Code / Cursor, a .mcp.json:

{
  "mcpServers": {
    "reeligence": {
      "command": "npx",
      "args": ["-y", "@reeligence/mcp"],
      "env": {
        "AIPVE_API_URL": "https://your-app.example.com",
        "AIPVE_AGENT_TOKEN": "ak_..."
      }
    }
  }
}

For Claude Desktop, the same command/args/env block under mcpServers in claude_desktop_config.json. Requires Node.js ≥ 20.

| Env var | Meaning | |---|---| | AIPVE_API_URL | Base URL of the running app (default http://localhost:5173) | | AIPVE_AGENT_TOKEN | ak_… agent token — required. (Repo checkouts only: falls back to the derived local service token) |

Notes

• Rendering needs a worker on the host running the app: pnpm jobs:work. render_script queues a job; if it stays queued, no worker is running.
• Upload size: on hosted (Vercel) deployments upload_asset bodies are capped (~4.5 MB). Screenshots are fine; upload large clips through the web app's asset page instead.
• Region-backed assets: assets captured with named regions carry exact UI rects — reference their region ids during generation for ground-truth highlight coordinates (see docs/specs/0004-capture-time-regions.md).
• Self-correction: validation failures return the server's structured issues (field path + message) in the tool error text; fix the field and retry. get_script_schema returns the full DemoScript JSON Schema.
• Rate limits: 120 requests/min per token, 10/min on the AI endpoints (generate_script, edit_scene, edit_script).

Development (repo checkout)

Inside the monorepo the server runs from source, and with no token set it falls back to the derived local service token, so it works against pnpm dev with zero config:

pnpm --filter @reeligence/mcp start      # run from source (tsx)
pnpm --filter @reeligence/mcp typecheck
pnpm turbo run build --filter @reeligence/mcp   # tsup → dist/ (bin: reeligence-mcp)
npx @modelcontextprotocol/inspector pnpm --filter @reeligence/mcp start

The published build bundles @reeligence/schema and excludes the @reeligence/auth dev fallback — see tsup.config.ts, spec 0006 and ADR 0007.

Releasing

Dry-run with a local tarball, then publish manually (never from CI):

pnpm turbo run build --filter @reeligence/mcp
cd tools/mcp && pnpm pack        # inspect the tarball; test it via
                                 # npx -y ./reeligence-mcp-<version>.tgz
pnpm publish                     # bump "version" first