MCP Media Forge

MCP server that generates diagrams, charts, HTML pages, and slide decks from text DSLs -- designed for AI coding agents to embed into Markdown.

LLM agents call tools like render_mermaid, render_html_page, or render_slides with text input, and get back file paths to assets ready to embed in docs.

Output Gallery

Mermaid Flowchart

<img src="docs/generated/example-flowchart.svg" width="400" alt="Mermaid flowchart">

Mermaid Sequence Diagram

<img src="docs/generated/example-sequence.svg" width="500" alt="Mermaid sequence diagram">

D2 Architecture Diagram

<img src="docs/generated/example-architecture.svg" width="600" alt="D2 architecture diagram">

Graphviz Dependency Graph

<img src="docs/generated/example-dependencies.svg" width="500" alt="Graphviz dependency graph">

Vega-Lite Bar Chart

<img src="docs/generated/example-bar-chart.svg" width="450" alt="Vega-Lite bar chart">

Tools

Diagram & Chart Renderers (Docker)

Tool	Input	Formats	Use Case
render_mermaid	Mermaid code	SVG, PNG	Flowcharts, sequence, ER, state, Gantt, git graphs
render_d2	D2 code	SVG, PNG	Architecture diagrams with containers and icons
render_graphviz	DOT code	SVG, PNG	Dependency graphs, network diagrams
render_chart	Vega-Lite JSON	SVG, PNG	Bar, line, scatter, area, heatmap charts

HTML Generators (No Docker)

Tool	Input	Output	Use Case
render_html_page	HTML body + theme	Self-contained HTML	Technical docs, reports, dashboards
render_slides	JSON slide array + theme	HTML slide deck	Presentations, status updates, walkthroughs

Utilities

Tool	Description
get_tool_guide	Usage examples, anti-patterns, complexity limits per tool
list_assets	List all generated files in the output directory

Quick Start

1. Start the rendering container (for diagram tools)

cd docker
docker compose up -d

HTML page and slide tools work without Docker.

2. Install the MCP server

Option A -- npx (no install)

npx mcp-media-forge

Option B -- Clone and build

git clone https://github.com/PavelGuzenfeld/mcp-media-forge.git
cd mcp-media-forge
npm install
npm run build

3. Register with your MCP client

Any MCP-compatible client (Claude Code, Cursor, VS Code + Copilot, Cline, etc.) can use this server. The standard config:

{
  "mcpServers": {
    "media-forge": {
      "command": "node",
      "args": ["/path/to/mcp-media-forge/dist/index.js"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Where to add this depends on your client:

• Claude Code: ~/.claude/settings.json
• Cursor: MCP settings panel
• VS Code (Copilot): .vscode/mcp.json
• Cline: MCP server configuration

4. Use it

Ask your AI assistant to generate diagrams, pages, or presentations:

"Create a sequence diagram showing the OAuth2 flow and embed it in the README"

"Generate an HTML page summarizing the API architecture with KPI cards"

"Make a slide deck with our Q1 metrics and architecture overview"

The agent calls the appropriate tool, gets back a file path, and embeds it in your markdown.

How It Works

AI Agent (any MCP client)
    |
    | MCP Protocol (JSON-RPC over stdio)
    v
MCP Media Forge (Node.js on host)
    |
    |--- Diagrams: docker exec (sandboxed, no network)
    |       |
    |       v
    |   Rendering Container
    |     ├── mmdc       (Mermaid CLI + Chromium)
    |     ├── d2         (D2 diagrams)
    |     ├── dot/neato  (Graphviz)
    |     └── vl2svg     (Vega-Lite via vl-convert)
    |
    |--- HTML/Slides: template engine (no Docker)
    |       |
    |       v
    |   CSS Design System (4 themes, depth tiers, components)
    |
    v
docs/generated/
  mermaid-a1b2c3.svg
  d2-7f8e9a.svg
  html_page-d4e5f6.html
  slides-8b9c0d.html

Key design decisions:

• Text in, file path out -- returns relative paths, never base64 blobs
• Content-hash naming -- same input = same file = free caching + git-friendly
• SVG preferred -- vector format, small files, diffs cleanly in git
• Docker-contained -- diagram renderers run in a sandboxed container with network_mode: none
• Self-contained HTML -- pages and slides have zero external dependencies (inline CSS/JS)
• Input pre-validation -- catches common mistakes before Docker round-trips
• Structured errors -- error responses include error_type, error_message, and suggestion to enable LLM self-correction

Tool Reference

get_tool_guide

Get usage guide for any tool before rendering. Returns examples, anti-patterns to avoid, complexity limits, and tips.

{ "tool_name": "mermaid" }

Available guides: mermaid, d2, graphviz, vegalite, html_page, slides, or all for a summary.

render_mermaid

{
  "code": "flowchart TD\n    A[Start] --> B{Decision}\n    B -->|Yes| C[Done]",
  "format": "svg",
  "theme": "default"
}

Parameter	Type	Default	Description
code	string	required	Mermaid diagram code (must start with diagram type)
format	svg | png	svg	Output format
theme	default | dark | forest | neutral	default	Mermaid theme

Pre-validation catches: missing diagram type, semicolons, HTML in labels, >25 nodes.

render_d2

{
  "code": "client -> server -> database",
  "format": "svg",
  "layout": "dagre"
}

Parameter	Type	Default	Description
code	string	required	D2 diagram code
format	svg | png	svg	Output format
theme	number	--	Theme ID (0=default, 1=neutral-grey, 3=terminal)
layout	dagre | elk | tala	dagre	Layout engine

Pre-validation catches: Mermaid/D2 syntax confusion, unbalanced braces, >3 nesting depth.

render_graphviz

{
  "dot_source": "digraph G { A -> B -> C }",
  "engine": "dot",
  "format": "svg"
}

Parameter	Type	Default	Description
dot_source	string	required	Graphviz DOT source code
engine	dot | neato | fdp | sfdp | twopi | circo	dot	Layout engine
format	svg | png	svg	Output format

Pre-validation catches: missing graph wrapper, -> in undirected graphs, unbalanced braces.

render_chart

{
  "spec_json": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{\"values\":[{\"x\":1,\"y\":10}]},\"mark\":\"bar\",\"encoding\":{\"x\":{\"field\":\"x\"},\"y\":{\"field\":\"y\"}}}",
  "format": "svg"
}

Parameter	Type	Default	Description
spec_json	string	required	Vega-Lite JSON specification
format	svg | png	svg	Output format
scale	number	1	Scale factor for PNG output

Pre-validation catches: invalid JSON, missing $schema/data/mark, >500 inline data rows.

render_html_page

Generates a self-contained themed HTML page. No Docker required.

{
  "title": "System Overview",
  "body_html": "<section id=\"metrics\"><h2>Metrics</h2><div class=\"mf-grid mf-grid-3\">...</div></section>",
  "theme": "swiss",
  "description": "Q1 architecture overview",
  "nav_sections": ["Metrics", "Architecture", "Roadmap"]
}

Parameter	Type	Default	Description
title	string	required	Page title
body_html	string	required	HTML body content (inner content only, no <html>/<head>/<body>)
theme	swiss | midnight | warm | terminal	swiss	Visual theme
description	string	--	Page description (meta tag + header)
nav_sections	string[]	--	Section names for floating IntersectionObserver navigation

Design system CSS classes:

Class	Purpose
mf-hero	Primary highlight section (large shadow)
mf-elevated	Secondary highlight (medium shadow)
mf-card	Bordered content card
mf-recessed	De-emphasized content
mf-grid mf-grid-2	Responsive 2-column grid
mf-grid mf-grid-3	Responsive 3-column grid
mf-split	Two equal columns
mf-kpi + mf-kpi-value + mf-kpi-label	Key metric display
mf-badge-success/warning/error/info	Status badges

Themes:

Theme	Style	Best for
swiss	White, geometric, blue accent	Technical docs
midnight	Deep navy, serif, gold accent	Presentations
warm	Cream paper, bold sans, terracotta	Reports
terminal	Dark, monospace, cyan accent	Developer content

render_slides

Generates a self-contained HTML slide deck with keyboard/touch navigation. No Docker required.

{
  "title": "Q1 Review",
  "slides": "[{\"title\":\"Q1 Review\",\"content\":\"Engineering update\",\"type\":\"title\"},{\"title\":\"Metrics\",\"content\":\"<ul><li>99.9% uptime</li></ul>\",\"type\":\"content\"}]",
  "theme": "midnight",
  "author": "Engineering Team"
}

Parameter	Type	Default	Description
title	string	required	Presentation title
slides	string	required	JSON array of slide objects
theme	swiss | midnight | warm | terminal	swiss	Visual theme
author	string	--	Author (shown on title slide)

Slide types:

Type	Layout	Best for
title	Centered large text + subtitle	Opening/closing slides
section	Centered heading + description	Topic dividers
content	Heading + body (bullets, text)	Most content
split	Heading + two columns	Before/after, comparisons
code	Heading + code block	Code walkthroughs
quote	Large blockquote + attribution	Testimonials, key quotes
kpi	Heading + auto-grid metrics	Dashboards, stats
image	Heading + centered image	Screenshots, diagrams

Navigation: Arrow keys, Space, PageUp/PageDown, Home/End. Touch: swipe left/right. Click dots to jump.

list_assets

{ "directory": "" }

Returns a JSON array of all generated files with name, path, size, and modification time.

Error Handling

All tools return structured errors that help LLMs self-correct:

{
  "status": "error",
  "error_type": "syntax_error",
  "error_message": "First line must declare diagram type. Got: \"A --> B\"",
  "suggestion": "Start with: flowchart TD, sequenceDiagram, erDiagram, ... See https://mermaid.js.org/syntax/"
}

Error types: syntax_error, rendering_error, dependency_missing.

Pre-validation catches common LLM mistakes before hitting the renderer:

• Mermaid: missing diagram type, semicolons, HTML tags, legacy graph syntax
• D2: Mermaid syntax confusion (-->, subgraph), unbalanced braces
• Graphviz: missing digraph/graph wrapper, -> in undirected graphs
• Vega-Lite: invalid JSON, missing required fields, oversized inline data

Environment Variables

Variable	Default	Description
PROJECT_ROOT	cwd()	Project root for output path resolution
OUTPUT_DIR	docs/generated	Output directory relative to PROJECT_ROOT
MEDIA_FORGE_CONTAINER	media-forge-renderer	Docker container name

Development

npm install
npm run build          # Build with tsup
npm run dev            # Watch mode
npm test               # Run all tests (95 total)
npm run test:unit      # Unit tests only (no Docker needed)
npm run test:component # Integration tests (Docker tools need container)
npm run lint           # Type-check with tsc

Running integration tests

cd docker && docker compose up -d   # Start renderer (diagram tools only)
cd .. && npm run test:component     # All integration tests

HTML page and slide integration tests run without Docker.

Examples

See examples/ for sample input files:

File	Tool	Description
mermaid/flowchart.mmd	render_mermaid	Decision flowchart
mermaid/sequence.mmd	render_mermaid	Client-server sequence
d2/architecture.d2	render_d2	Backend architecture with containers
graphviz/dependencies.dot	render_graphviz	npm dependency graph
vegalite/bar-chart.json	render_chart	Tool performance comparison

See examples/README.md for MCP tool call examples and expected responses.

License

MIT