narrateai-demomaker 0.11.0

MCP server that records and narrates demo, tutorial, and onboarding videos of your web app through the NarrateAI pipeline

NarrateAI DemoMaker

"A demo video creator and narrator that lives in your codebase."

An MCP server for Cursor / Claude Code that records narrated demo videos of your app. Your coding agent already knows your routes, selectors, auth, and test data — give it NarrateAI DemoMaker, and it produces a fully narrated MP4 of any flow you describe, end-to-end.

┌──────────────────┐     ┌─────────────────────────┐     ┌──────────────────────┐
│  You ask Cursor  │────▶│  Agent reads codebase   │────▶│  check_app(url)      │
│  for a demo video│     │  (routes, selectors,    │     │  → confirms reachable│
└──────────────────┘     │   auth, fixtures)       │     └──────┬───────────────┘
                         └─────────────────────────┘            │
                                                                ▼
┌──────────────────┐     ┌─────────────────────────┐     ┌──────────────────────┐
│  Final MP4 URL   │◀────│  NarrateAI narration    │◀────│  NarrateAI records   │
│  (narrated)      │     │  pipeline               │     │  your session →      │
└──────────────────┘     └─────────────────────────┘     │  WebM → MP4          │
                                                         └──────────────────────┘

---

What it does

• Records your running app or a live notebook tutorial (vscode.dev) in an isolated headless browser session — real cursor motion, viewport capture, no manual screen recording.
• Narrates the recording through NarrateAI's full narration pipeline: frame analysis, transcript generation, TTS with your chosen voice, final video assembly.
• Reads your codebase to find routes, data-testid selectors, test credentials, auth flows, and DOM ready signals — so the agent plans selectors it can actually hit.
• Handles iframes (website builders like Odoo / Webflow, embedded checkouts, Storybook, etc.) via the frame field in the plan schema.
• Handles auth — email/password inline, or one-shot save_auth_session for OAuth / magic links / 2FA.
• Handles notebook tutorials — open vscode.dev, type + run Jupyter cells, produce a how-to video with the right narrator cadence.
• Picks the narrator's voice mode — demo for product showcases, how_to for tutorials, story for narrative / presentation videos.

---

Install (one line)

uvx narrateai-demomaker init

This command:

1. Detects your agent (Cursor or Claude Code) from the current project.
2. Creates / merges an mcp.json entry for narrateai-demomaker.
3. Drops SKILL.md + all reference docs into your agent's skills folder (progressive disclosure, so only what's needed enters context).
4. Prompts for your NarrateAI API key (stored in the config file's env block).

Then restart your agent. Ask:

"Make a 30-second demo of someone signing in and uploading a doc."

The agent will read your codebase, propose a plan, record it, narrate it, and hand you an MP4 URL.

Options

uvx narrateai-demomaker init --global           # install for all projects
uvx narrateai-demomaker init --api-key sk_...   # non-interactive key
uvx narrateai-demomaker init --agent cursor     # force agent choice

Re-running init is safe — it merges with your existing config rather than overwriting.

---

Prerequisites

• Python 3.11+ (handled by uvx automatically)
• ffmpeg on PATH — brew install ffmpeg / apt install ffmpeg. A bundled fallback is attempted via imageio-ffmpeg, but a real system install is more reliable.
• A NarrateAI API key — sign up at narrateai.app. The init command prompts for it; you can also set NARRATEAI_API_KEY in your agent's MCP env block manually.

The required Chromium binary is downloaded automatically the first time you run a recording (~170 MB, one-time).

---

Tools exposed to your agent

check_app(url, viewport_width=1440, viewport_height=900, take_screenshot=False)

Cheap probe (~3s). Returns reachability, page title, and up to 60 stable interactive selectors. The agent always calls this before planning.

save_auth_session(start_url, label, done_when_url="", done_when_selector="", timeout_seconds=300)

One-time per app. Opens a headed browser so the user can sign in through OAuth / magic link / 2FA flows manually. The session is saved to ~/.narrateai-demomaker/auth/<label>.json and reused by future recordings when you pass auth_session=<label> to create_demo_video.

create_demo_video(url, plan, narration_type="demo", voice_type="male1", language="en", auth_session="", headless=True)

The main tool. Validates the plan → records → transcodes → uploads → narrates → polls → returns video_url. Runs as a long-running task with progress reporting.

• plan is a JSON object — the agent builds this from reading your codebase (see skill/SKILL.md).
• narration_type changes the narrator's voice: "how_to" for tutorials, "demo" for product showcases (default), "story" for narrative videos.

---

What this is NOT for

• Editing existing videos — use the regular narrateai MCP (narrate_video_full, dub_video_full, etc.).
• Transcribing meetings — narrateai MCP's transcribe_video.
• Recording native desktop apps (VS Code Desktop, Cursor itself, Electron apps) — NarrateAI DemoMaker drives browsers only. For notebook tutorials use vscode.dev (browser) or a local JupyterLab server.
• Scraping arbitrary public URLs you don't own — flaky, OAuth-blocked, not the design goal.

---

On-disk artifacts

• Recordings: ~/.narrateai-demomaker/runs/<timestamp>/demo.mp4 (plus the source .webm)
• Failed-step screenshots: ~/.narrateai-demomaker/runs/<timestamp>/step_NN_failed.png
• Auth sessions: ~/.narrateai-demomaker/auth/<label>.json

All safe to clean up any time.

---

Troubleshooting

"ffmpeg not found" — install ffmpeg (brew install ffmpeg).

"Browser engine not installed" — happens on first run. The MCP self-installs Chromium; allow 1–2 minutes.

"API key required" — NARRATEAI_API_KEY is missing from your agent's mcp.json env block. Re-run narrateai-demomaker init to be prompted.

Recording succeeds but narration fails — the MP4 is still on disk at the mp4_path returned in the error. You can re-narrate it via the regular narrateai MCP (narrate_video_full(video_path=...)).

A step keeps failing — have the agent call check_app(take_screenshot=True) for fresh confirmed selectors. Most common cause: a guessed selector vs. one the recorder can actually find. data-testid is your friend.

"Element not found" on an iframe target (Odoo's editor preview, Stripe Checkout, Storybook preview panes) — the agent needs to set the frame field on the step. See skill/references/iframe-targeting.md.

---

Under the hood

For the curious — you don't need to care about any of this to use the MCP:

• The recorder is built on Playwright + headless Chromium. We chose Playwright because it's mature, maintained by Microsoft, and supports storageState / frame_locator out of the box.
• The narration pipeline is NarrateAI's proprietary backend — frame analysis, transcript generation, voice synthesis, and video assembly all happen server-side and are what the API key gates.
• ffmpeg handles the WebM → MP4 transcode (via imageio-ffmpeg with a system-binary fallback).
• The MCP server uses FastMCP over stdio — no network ports opened locally.

If you want to debug the browser layer, standard Playwright diagnostics work (the recorder writes failed-step screenshots to ~/.narrateai-demomaker/runs/.../).

---

License

See the parent repo for licensing. The NarrateAI narration API is a hosted service gated by API key; the MCP itself is client code you're free to inspect.