Repository navigation
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.
- 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 runchild 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 runwrites. See Run Artifacts.
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
- The client calls
generate_demowith 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 }. - An inline scenario is written to
<home>/mcp/<taskId>.demo.json, outsideruns/. The engine copies it into the run directory asscenario.json. - When the task reaches the front of the queue, the server starts
demoflow run --run-id <taskId> --project <root> --jsonin the project root. - The client polls
get_task. WithwaitSecondsthe reply is held until the task finishes or the wait runs out, whichever comes first. - 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).
- 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.
- This covers a task run by an earlier server, from
Register the server with Claude Code (this is the line in demoflow mcp --help):
claude mcp add demoflow -- npx demoflow mcpThe 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:
-
check_project: confirm the config is valid, list the scenarios, and see whether FFmpeg and Chromium are available. -
validate_scenario: check an inline scenario before you queue it. -
generate_demo: queue the run and keep thetaskId. -
get_taskwithwaitSeconds: 50, repeated untilstatusis terminal. - Read
artifacts.video, or reportfailedStepback to the person.
| 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_demoandvalidate_scenarioneed exactly one ofscenarioandfile. -
projectmust 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. -
messageexplains a failure that has noresult.json. -
failedStepis the first stage error, in pipeline order, that names a step. -
artifactsappears once the run directory exists. Inside it,video,timelineandsourceappear only for files that exist.
Other tools' results:
-
list_demos: each entry hastaskId,scenarioName,status,startedAt, and, when the run rendered,durationMsandvideo. Runs without a readableresult.jsonare skipped. -
check_project:-
scenarios: thedemoflow/**/*.demo.jsonfiles, relative to the root. -
ffmpeg:system,bundledormissing. -
browser:installedormissing.
-
| 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 |
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 |
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 |
-
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).
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference