🎬 PoC Recorder MCP Server for Python

Python MCP server for inspecting web PoCs and recording automated, client-ready .mp4 and .gif walkthroughs of localhost or remote web services. It exposes a Model Context Protocol server over stdio powered by Headless Chromium (Playwright) and FFmpeg.

Note: All examples in this repository use placeholder URLs and paths (http://localhost:47891, /home/user/project/scenarios, acme-corp.test). Replace them with your own target URLs and output directories.

✨ Features

• Record Web PoCs to MP4 & GIF: Capture smooth headless Chromium walkthroughs and transcode them automatically into H.264 .mp4 (yuv420p + faststart) and two-pass palette-optimized .gif (palettegen + paletteuse).

• Visual Cursor & Click Ripples: Injects an animated virtual pointer with click ripple effects and smooth mouse trajectories (page.mouse.move), solving Playwright's native invisible-cursor limitation.

• Step HUD Captions: Optional translucent subtitle pill at the bottom of the viewport (caption per step) to guide clients through each feature being demonstrated.

• Zero-Leak Dummy Data Injection: Replace real telemetry or development data before frame 0 using local_storage, session_storage, mock_routes (HTTP API interception), html_replacements (on-the-fly document rewriting), or post_load_js.

• Live DOM Selector Discovery: Inspect any localhost or remote URL with inspect-page to retrieve verified CSS selectors for tabs, buttons, inputs, and filter chips before recording.

• Reusable Scenario Files: Store and replay repeatable *.scenario.json demo flows across builds.

• Zero System-FFmpeg Requirement: Uses system ffmpeg when available on PATH and transparently falls back to the bundled static binary from imageio-ffmpeg.

• Normalized Outputs: Return structured JSON results containing success, summary, artifacts, details, warnings, and timings.

Related MCP server: Agent Demo Studio

📦 Requirements

• Python: 3.10 or newer

• Package Manager: uv

• Browser Engine: Playwright Chromium

Install the Chromium browser binary once via uv:

uv run playwright install chromium

Runtime auto-install is also available as an opt-in setting: set POC_RECORDER_MCP_AUTO_INSTALL_BROWSER=1 (or auto_install_browser = true under [recorder] in poc-recorder-mcp.toml).

🚀 Installation & Running

1. Installation

Install dependencies using uv:

uv sync
uv run playwright install chromium

(If your configured package index does not mirror the MCP Python SDK, point uv at PyPI for the sync: UV_DEFAULT_INDEX=https://pypi.org/simple uv sync)

2. Running the Server

You can run the server directly using uv:

uv run poc-recorder-mcp

Alternatively, run the module directly inside the uv environment: uv run python -m poc_recorder_mcp

⚙️ Configuration

MCP Configuration

Example MCP stdio configuration from this workspace root:

{
  "mcpServers": {
    "poc-recorder": {
      "command": "uv",
      "args": ["run", "poc-recorder-mcp"]
    }
  }
}

Configuration File (poc-recorder-mcp.toml)

Default viewport settings, limits, and scenario roots can be configured in poc-recorder-mcp.toml in the current working directory, or globally in ~/.config/poc-recorder-mcp/config.toml.

See poc-recorder-mcp.example.toml for a commented template:

[workspace]
scenario_roots = [
  "/home/user/project/scenarios"
]

[recorder]
width = 1440
height = 900
fps = 15
show_cursor = true
show_hud = true
auto_install_browser = false

[limits]
run_timeout_seconds = 180
max_steps = 100
max_concurrent_runs = 2

[artifacts]
ttl_hours = 168
max_files = 50

[security]
allow_localhost = true
allowed_hosts = []

Every setting can also be set via environment variables (POC_RECORDER_MCP_WIDTH, POC_RECORDER_MCP_HEIGHT, POC_RECORDER_MCP_FPS, POC_RECORDER_MCP_SHOW_CURSOR, POC_RECORDER_MCP_SHOW_HUD, POC_RECORDER_MCP_AUTO_INSTALL_BROWSER, POC_RECORDER_MCP_RUN_TIMEOUT, POC_RECORDER_MCP_MAX_STEPS, POC_RECORDER_MCP_MAX_CONCURRENT_RUNS, POC_RECORDER_MCP_OUTPUT_DIR, POC_RECORDER_MCP_ALLOW_LOCALHOST, POC_RECORDER_MCP_ALLOWED_HOSTS, POC_RECORDER_MCP_SCENARIO_ROOTS, POC_RECORDER_MCP_LOG_LEVEL), which take precedence over the file.

Note: The installer creates ~/.config/poc-recorder-mcp/config.toml from the template. Local poc-recorder-mcp.toml files and recorded *.mp4 / *.gif / *.webm files are git-ignored so local demos and paths are never committed accidentally.

💻 Local VS Code Installation

From the project root, install dependencies with uv:

UV_DEFAULT_INDEX=https://pypi.org/simple uv sync
uv run playwright install chromium

This repository includes .vscode/mcp.json, allowing VS Code to discover the local MCP server from the workspace:

{
  "servers": {
    "poc-recorder": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "poc-recorder-mcp"]
    }
  }
}

Reload the VS Code window after syncing dependencies. The poc-recorder server should now be available in the MCP servers list.

Global Installation

To install the MCP server in the VS Code user profile so it is available from any workspace:

uv run python scripts/install_vscode.py

(To also install the reusable Copilot prompt and agent globally, append --with-copilot-customizations to the command above).

To install it manually in another local VS Code workspace, change the command args to include --directory:

"args": ["--directory", "/home/user/mcp-poc-recorder", "run", "poc-recorder-mcp"]

🧰 Available Tools

🔍 inspect-page

Opens a target web service (http://localhost:<port> or remote URL) in headless Chromium and returns the page title, headings, localStorage keys, and interactive DOM elements (button, input, select, .tab-btn, .chip, [onclick]) with verified CSS selectors.

• url (required): Target URL to inspect.

• wait_ms (optional): Delay after networkidle before extracting DOM metadata (default 600).

• max_elements (optional): Maximum interactive elements to return (default 60).

🎥 record-poc

Records an automated browser walkthrough with a virtual cursor, click ripples, HUD step captions, and dummy data injection, then converts the recording to .mp4, .gif, or both.

• url (required): Target web service URL (e.g. http://localhost:47891).

• output_path (required): Output file path (or base path when format="both").

• format (optional): "both" (default — emits .mp4 and .gif), "mp4", "gif", or "webm".

• steps (optional): Ordered list of actions (goto, wait, click, type, fill, select, hover, scroll, press, eval, caption).

• local_storage / session_storage (optional): Key-value pairs pre-loaded into browser storage before page scripts execute.

• mock_routes (optional): Intercept matching HTTP requests and fulfill them with synthetic JSON/text payloads.

• html_replacements (optional): Rewrite inline datasets or strings in the main HTML document before rendering.

• post_load_js (optional): JavaScript executed right after initial navigation to hydrate dummy state before choreography steps begin.

Supported Step Actions:

• {"action": "click", "selector": "button.tab-btn:nth-of-type(2)", "caption": "2. Network Intelligence", "ms": 1100}

• {"action": "type", "selector": "#net-search", "text": "ACME-Corp", "delay_ms": 45, "ms": 900}

• {"action": "hover", "selector": ".badge.b-suspicious", "ms": 800}

• {"action": "scroll", "x": 0, "y": 420, "ms": 800}

• {"action": "eval", "js": "openNetworkDossier('00:11:22:33:44:55')", "ms": 1200}

• {"action": "press", "text": "Escape", "ms": 600}

• {"action": "wait", "ms": 1500, "caption": "Executive Risk Overview"}

Example record-poc payload with dummy data:

{
  "url": "http://localhost:47891",
  "output_path": "/home/user/project/poc_demo",
  "format": "both",
  "local_storage": {
    "demo_mode": "true"
  },
  "mock_routes": [
    {
      "url_pattern": "**/api/tags",
      "status": 200,
      "body": {"networks": {"00:11:22:33:44:55": {"label": "ACME-HQ-AP01", "category": "PROPIO"}}}
    }
  ],
  "steps": [
    {"action": "wait", "ms": 1200, "caption": "1. Executive Dashboard — Synthetic Audit Dataset"},
    {"action": "click", "selector": "nav.tabs button:nth-of-type(2)", "ms": 1200, "caption": "2. Inspecting Discovered Access Points"}
  ]
}

📋 list-scenarios & run-scenario

• list-scenarios: Discovers reusable *.scenario.json walkthrough files under a directory or configured scenario_roots.

• run-scenario: Executes a saved *.scenario.json file with optional url, output_path, and format overrides.

📁 list-recordings

Lists generated .mp4, .gif, and .webm artifacts in the output directory with file sizes in bytes and KB.

Agent Skills & Copilot Integration

These workflows use the MCP server configured as poc-recorder; installing a skill or prompt does not install or configure the server. Configure the server in your client first using the MCP configuration above.

VS Code GitHub Copilot

The repository includes a custom agent and a slash-command prompt. From this repository root, copy them into the target workspace:

mkdir -p /path/to/workspace/.github/agents /path/to/workspace/.github/prompts
cp copilot/agents/poc-recorder.agent.md /path/to/workspace/.github/agents/
cp copilot/prompts/record-web-poc.prompt.md /path/to/workspace/.github/prompts/

Select the poc-recorder custom agent in Copilot Chat's agent picker (@poc-recorder where supported), or run /record-web-poc <url> [output_path] in Chat.

Alternatively, install both globally with:

uv run python scripts/install_vscode.py --with-copilot-customizations

Claude Code / Cursor / Windsurf

The universal PoC Recorder skill consolidates DOM inspection, zero-leak dummy data injection, cursor choreography, and dual MP4/GIF generation.

For Claude Code, copy it into the target project's skill directory:

mkdir -p /path/to/workspace/.claude/skills/poc-recorder
cp skills/poc-recorder/SKILL.md /path/to/workspace/.claude/skills/poc-recorder/SKILL.md

Or symlink the skill directory using an absolute source path:

mkdir -p /path/to/workspace/.claude/skills
ln -s /absolute/path/to/mcp-poc-recorder/skills/poc-recorder /path/to/workspace/.claude/skills/poc-recorder

For Cursor, copy or symlink the same directory to .cursor/skills/poc-recorder/; for Windsurf, use .windsurf/skills/poc-recorder/ in the target workspace.

Repository Assets

Skills and Copilot templates remain organized under skills/ and copilot/ at the repository root, separately from the Python packages discovered under src/ in pyproject.toml.

Execution results retain the server's normalized output contract:

{
  "success": true,
  "tool": "record-poc",
  "summary": {
    "url": "http://localhost:47891",
    "title": "SIGINT Wireless Intelligence Console — Wardrive ESP32-S3",
    "format": "both",
    "viewport": "1440x900",
    "fps": 15,
    "steps_total": 8,
    "steps_completed": 8,
    "artifacts_count": 2
  },
  "artifacts": [
    {
      "format": "mp4",
      "path": "/home/user/project/poc_demo.mp4",
      "size_bytes": 412890,
      "size_kb": 403.21
    },
    {
      "format": "gif",
      "path": "/home/user/project/poc_demo.gif",
      "size_bytes": 1154320,
      "size_kb": 1127.27
    }
  ],
  "details": {
    "steps": []
  },
  "warnings": [],
  "timings": {
    "started": "2026-10-20T17:20:00.000000Z",
    "completed": "2026-10-20T17:20:14.000000Z",
    "duration_ms": 14000
  }
}

🐳 Docker

The Docker image installs this Python server, FFmpeg, and Headless Chromium:

docker build -t poc-recorder-mcp-python .
docker run --rm -i --network host poc-recorder-mcp-python

🛠️ Development & Project Structure

Commands:

• Compile-check the sources: uv run python -m compileall src

• Lint with Ruff: uv run ruff check src tests scripts

• Type-check with Mypy: uv run mypy src/poc_recorder_mcp

• Run the test suite: uv run pytest tests/ -q

Structure:

.
├── src/poc_recorder_mcp/      # MCP server, Playwright recorder, FFmpeg converter, overlays, and types
├── scripts/                   # VS Code installer script
├── copilot/                   # Reusable Copilot prompt and agent templates
├── skills/poc-recorder/       # Universal Agent Skill (SKILL.md)
├── tests/                     # Unit tests
├── .vscode/mcp.json           # Workspace MCP server entry
└── poc-recorder-mcp.example.toml # Commented configuration template

mcp-name: io.github.kta41/mcp-poc-recorder

📄 License

Released under the MIT License.