Skip to content

MCP Server

Archi edited this page Oct 18, 2026 · 1 revision

MCP Server

demoflow mcp runs a local MCP server over stdio, so an AI agent such as Claude Code can queue a demo, poll it, and get the paths of the finished video. It wraps the same demoflow run you use by hand, so nothing is uploaded and nothing leaves your machine.

Overview

  • Transport: stdio only. The server is a child process of the MCP client, not a network service (ADR-0008).
  • Capabilities: tools only. There are no MCP resources and no prompts.
  • Tools: generate_demo, get_task, cancel_task, validate_scenario, list_demos, check_project.
  • Execution: each task is a demoflow run child process. Tasks run one at a time, in the order they were queued.
  • Results: artifact paths are absolute local paths, in the same run directory a manual demoflow run writes. See Run Artifacts.

How it works

sequenceDiagram
    participant Agent as "MCP client (agent)"
    participant Server as "demoflow mcp"
    participant Run as "demoflow run (child)"
    Agent->>Server: generate_demo(file or scenario)
    Server-->>Agent: taskId, status queued, position
    Server->>Run: run --run-id taskId --project root --json
    Agent->>Server: get_task(taskId, waitSeconds 50)
    Run-->>Server: exit, result.json
    Server-->>Agent: status completed, stages, artifacts
Loading
  1. The client calls generate_demo with a project and either a scenario file or an inline scenario. The server checks the input, picks a task ID (it is also the run ID), and queues the task. It replies at once with { taskId, status, position }.
  2. An inline scenario is written to <home>/mcp/<taskId>.demo.json, outside runs/. The engine copies it into the run directory as scenario.json.
  3. When the task reaches the front of the queue, the server starts demoflow run --run-id <taskId> --project <root> --json in the project root.
  4. The client polls get_task. With waitSeconds the reply is held until the task finishes or the wait runs out, whichever comes first.
  5. When the task ends, the staged inline scenario is deleted, and only then is the terminal status set. So a task that reports finished has no staged copy left (spec 92).
  6. A task the server has forgotten is read back from disk.
    • This covers a task run by an earlier server, from <home>/runs/<taskId>/result.json.
    • The home is found when its project is the server's working directory, or a project this server has already used.

Using it

Register the server with Claude Code (this is the line in demoflow mcp --help):

claude mcp add demoflow -- npx demoflow mcp

The server's working directory is the default project. Every tool also takes project, an absolute path to a directory that contains demoflow.config.json.

A typical agent flow:

  1. check_project: confirm the config is valid, list the scenarios, and see whether FFmpeg and Chromium are available.
  2. validate_scenario: check an inline scenario before you queue it.
  3. generate_demo: queue the run and keep the taskId.
  4. get_task with waitSeconds: 50, repeated until status is terminal.
  5. Read artifacts.video, or report failedStep back to the person.

Tools

Tool Inputs Returns
generate_demo project?, scenario? (inline scenario), file? (a *.demo.json inside the project, relative to its root or absolute), timeoutMinutes? (integer 1–60, default 15) { taskId, status, position }
get_task taskId, waitSeconds? (0–50, default 0) a task view (below)
cancel_task taskId { taskId, status }
validate_scenario project?, scenario?, file? { valid: true }, or an invalid-scenario error with issue paths
list_demos project?, limit? (integer 1–100, default 20) { demos: [...] }, newest first
check_project project? { root, configValid, scenarios, ffmpeg, browser }

Input rules:

  • Every input object is strict: unknown keys are rejected.
  • generate_demo and validate_scenario need exactly one of scenario and file.
  • project must be an absolute path.

The task view from get_task:

{
  "taskId": "20261018-200548-clfwzo",
  "status": "failed",
  "stages": { "readiness": {}, "execution": {}, "…": {} },
  "failedStep": { "stepIndex": 3, "message": "…" },
  "artifacts": { "video": "…", "timeline": "…", "source": "…", "runDir": "…" }
}

Only the fields that apply are present:

  • position (tasks ahead of this one) appears only while the task is queued.
  • message explains a failure that has no result.json.
  • failedStep is the first stage error, in pipeline order, that names a step.
  • artifacts appears once the run directory exists. Inside it, video, timeline and source appear only for files that exist.

Other tools' results:

  • list_demos: each entry has taskId, scenarioName, status, startedAt, and, when the run rendered, durationMs and video. Runs without a readable result.json are skipped.
  • check_project:
    • scenarios: the demoflow/**/*.demo.json files, relative to the root.
    • ffmpeg: system, bundled or missing.
    • browser: installed or missing.

Task statuses

Status Means
queued waiting for the task ahead of it
running the demoflow run child is working
completed the run's status is completed or completed_with_warnings
failed the run failed, or ended with no readable result
cancelled cancel_task was called, or the server shut down
timed_out the task ran longer than timeoutMinutes and was killed

Errors

A refused call returns isError: true with { code, message, hint }. The hint tells the agent what to do next.

Code When
invalid-input the arguments do not match the tool's input, or the tool is unknown
both-or-neither-scenario both scenario and file were given, or neither was
project-not-found no project at project (or the working directory)
invalid-project-config demoflow.config.json is invalid
invalid-scenario the scenario fails the schema; issue paths are included
scenario-unreadable the scenario file could not be read
file-not-in-project file is not a *.demo.json inside the project
task-not-found no such task, in memory or on disk

Settings

The server has no settings of its own. It reads the project's demoflow.config.json and finds the artifacts home exactly as demoflow run does. See Project Configuration.

Limit Value
Tasks running at once 1
timeoutMinutes 1–60, default 15
waitSeconds 0–50, default 0 (kept under the 60 s request timeout of MCP clients)
list_demos limit 1–100, default 20
Grace after SIGTERM before SIGKILL 5 s

Limits / what it never does

  • Stopping a task: cancelling a running task or timing it out sends SIGTERM, then SIGKILL after 5 s.
    • On POSIX the child leads its own process group, so FFmpeg is stopped too.
    • On Windows the server uses taskkill /T /F.
  • Shutdown: when the client closes stdin, or the server gets SIGINT, SIGTERM or SIGHUP, queued tasks are cancelled and the running child is killed. Unfinished tasks are gone after a restart.
  • The first run on a machine may download Chromium (~250 MB) and takes longer. See Installing.
  • No cloud: no upload, no share link, and no network listener.
  • Not yet: a DemoFlow page reference for a video waits for the website (Status and Roadmap).

See also

Clone this wiki locally