demosmith-mcp

An MCP (Model Context Protocol) server for automated demo recording with video, documentation, and screenshot generation. Perfect for creating product demos, tutorials, and documentation with AI agents.

Demo

Demo: GitHub login flow with animated cursor, click effects, and auto-generated documentation

Features

• Video Recording - Automatic screen recording of browser sessions
• Screenshot Capture - Automatic screenshots at each step
• Animated Cursor - Smooth cursor animations with click effects and sounds
• TTS Narration - AI-powered voiceover with multiple providers (OpenAI, ElevenLabs, Azure, Edge)
• Multiple Output Formats:
  • Video (WebM)
  • Video with Audio (MP4)
  • Playwright Trace (interactive replay)
  • Markdown Guide
  • JSON Steps
  • Narration Script + JSON (with timestamps)
  • Subtitles (SRT/VTT)
  • Interactive HTML Tutorial
  • GIF Preview
• Multi-language Support - English and Chinese
• Multi-tab Support - Work with multiple browser tabs
• Flexible Element Selection - By ref, text, label, placeholder, CSS, XPath

Installation

npm install demosmith-mcp
npx playwright install chromium

Usage

As MCP Server

Add to your Claude Code MCP configuration (~/.claude/mcp.json):

{
  "mcpServers": {
    "demosmith": {
      "command": "npx",
      "args": ["demosmith-mcp"]
    }
  }
}

CLI Mode

# Replay a recorded demo
demosmith replay ./steps.json -o ./output --video

# Generate documentation from steps
demosmith generate ./steps.json -l zh -o ./docs

# Serve generated files locally
demosmith serve ./output

MCP Tools

Session Management

Tool	Description
demosmith_start	Start a new demo recording session
demosmith_end	End session and generate all deliverables
demosmith_status	Get current session status

Navigation & Discovery

Tool	Description
demosmith_navigate	Navigate to a URL
demosmith_snapshot	Get accessibility tree snapshot for element refs

Core Actions

Tool	Description
demosmith_click	Click an element (with animated cursor)
demosmith_fill	Fill a text input (with typing animation)
demosmith_select	Select from dropdown
demosmith_press_key	Press keyboard key or combination
demosmith_hover	Hover over element (for tooltips/menus)
demosmith_drag	Drag and drop
demosmith_upload	Upload file

Page Actions

Tool	Description
demosmith_scroll	Scroll page or element
demosmith_wait	Wait for condition
demosmith_screenshot	Take manual screenshot

Verification

Tool	Description
demosmith_assert	Verify conditions (text, visibility, URL, etc.)

Tab Management

Tool	Description
demosmith_new_tab	Open new browser tab
demosmith_switch_tab	Switch to different tab
demosmith_close_tab	Close a tab
demosmith_list_tabs	List all open tabs

Element Selectors

demosmith supports multiple ways to locate elements:

# By ref (from snapshot)
"1", "2", "3"

# By visible text
"text:Submit"
"text:/Submit|Cancel/"  # regex

# By label
"label:Email"

# By placeholder
"placeholder:Enter your name"

# By role and name
"role:button:Submit"
"role:textbox"

# By test ID
"testid:submit-btn"

# By CSS selector
"css:.btn-primary"

# By XPath
"xpath://button[@type='submit']"

# By alt text
"alt:Logo"

# By title
"title:Close"

Example Workflow

1. demosmith_start(url="https://example.com/login", title="Login Demo")
2. demosmith_snapshot()  → Get element refs
3. demosmith_fill(ref="label:Email", value="user@example.com", description="Enter email")
4. demosmith_fill(ref="label:Password", value="password123", description="Enter password")
5. demosmith_click(ref="text:Sign In", description="Click sign in button")
6. demosmith_assert(type="url", expected="/dashboard", description="Verify redirect")
7. demosmith_end()  → Returns all deliverables

Output Files

After ending a session, the following files are generated:

output/
├── demo.webm              # Screen recording video
├── demo-with-audio.mp4    # Video with TTS narration (if TTS enabled)
├── demo.gif               # Animated GIF preview
├── trace.zip              # Playwright trace (interactive replay)
├── guide.md               # Markdown documentation
├── steps.json             # Structured step data
├── narration.txt          # Voiceover script
├── narration.json         # Timed narration for TTS APIs
├── narration.mp3          # Generated audio (if TTS enabled)
├── subtitles.srt          # SRT subtitles
├── subtitles.vtt          # VTT subtitles
├── tutorial.html          # Interactive HTML tutorial
├── animated-preview.html  # HTML preview (fallback)
└── assets/
    ├── step-001.png
    ├── step-002.png
    └── ...

See examples/github-login-demo/ for a complete example output.

Configuration Options

Start Session Options

Option	Type	Default	Description
title	string	required	Demo title
startUrl	string	required	Starting URL
outputDir	string	temp dir	Output directory
video	boolean	true	Record video
trace	boolean	true	Record Playwright trace
screenshotOnStep	boolean	true	Auto-screenshot each step
headless	boolean	false	Run browser headless
viewport	object	1280x720	Browser viewport size
storageState	string	-	Path to login state file

Animation Options

Click and fill actions support animation options:

Option	Type	Default	Description
animated	boolean	true	Enable cursor animation
moveDuration	number	500	Cursor movement duration (ms)
typeDelay	number	50	Delay between keystrokes (ms)

Assert Types

The demosmith_assert tool supports these verification types:

Type	Description
text	Check element text content
visible	Check element is visible
hidden	Check element is hidden
url	Check current URL
title	Check page title
value	Check input value
checked	Check checkbox is checked
enabled	Check element is enabled
disabled	Check element is disabled
count	Check number of matching elements

Multi-language Support

Generated content supports English and Chinese. Set via CLI:

demosmith generate ./steps.json -l zh  # Chinese
demosmith generate ./steps.json -l en  # English (default)

Custom Templates

You can provide custom templates for output generation using Mustache-like syntax:

# {{session.title}}

{{#each steps}}
## Step {{this.id}}: {{this.description}}

{{#if this.screenshotRelative}}
![Screenshot]({{this.screenshotRelative}})
{{/if}}
{{/each}}

Login Session Support

Save a login session with Playwright:

await context.storageState({ path: 'auth.json' });

Use in demo:

demosmith_start(url="...", title="...", storageState="auth.json")

TTS Narration

Generate AI voiceover for your demos by passing TTS options to demosmith_end:

demosmith_end(tts={
  provider: "openai",
  apiKey: "sk-...",
  voice: "alloy"
})

Supported TTS Providers

Provider	API Key Required	Voices	Notes
openai	Yes	alloy, echo, fable, onyx, nova, shimmer	Best quality
elevenlabs	Yes	Various voice IDs	Most natural
azure	Yes	en-US-JennyNeural, etc.	SSML support
edge	No	en-US-AriaNeural, etc.	Free, requires edge-tts CLI

TTS Options

Option	Type	Description
provider	string	TTS provider (openai, elevenlabs, azure, edge)
apiKey	string	API key (not needed for edge)
voice	string	Voice ID or name
language	string	Language code (e.g., en-US, zh-CN)
speed	number	Speech speed multiplier

Environment Variables

For Azure TTS, set the region:

export AZURE_SPEECH_REGION=eastus

Narration JSON Format

The generated narration.json contains timed segments for custom TTS integration:

{
  "title": "Login Demo",
  "totalDurationMs": 15000,
  "segments": [
    {
      "stepId": 1,
      "startMs": 2000,
      "endMs": 4500,
      "durationMs": 2500,
      "text": "Click the login button"
    }
  ]
}

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run MCP server
pnpm start

# Run CLI
pnpm cli help

License

MIT