{
  "markdown": "# MCP Media Forge\n\n[![npm](https://img.shields.io/npm/v/mcp-media-forge)](https://www.npmjs.com/package/mcp-media-forge)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nMCP server that generates diagrams, charts, HTML pages, and slide decks from text DSLs -- designed for AI coding agents to embed into Markdown.\n\nLLM 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.\n\n## Output Gallery\n\n### Mermaid Flowchart\n<img src=\"docs/generated/example-flowchart.svg\" width=\"400\" alt=\"Mermaid flowchart\">\n\n### Mermaid Sequence Diagram\n<img src=\"docs/generated/example-sequence.svg\" width=\"500\" alt=\"Mermaid sequence diagram\">\n\n### D2 Architecture Diagram\n<img src=\"docs/generated/example-architecture.svg\" width=\"600\" alt=\"D2 architecture diagram\">\n\n### Graphviz Dependency Graph\n<img src=\"docs/generated/example-dependencies.svg\" width=\"500\" alt=\"Graphviz dependency graph\">\n\n### Vega-Lite Bar Chart\n<img src=\"docs/generated/example-bar-chart.svg\" width=\"450\" alt=\"Vega-Lite bar chart\">\n\n## Tools\n\n### Diagram & Chart Renderers (Docker)\n\n| Tool | Input | Formats | Use Case |\n|------|-------|---------|----------|\n| `render_mermaid` | Mermaid code | SVG, PNG | Flowcharts, sequence, ER, state, Gantt, git graphs |\n| `render_d2` | D2 code | SVG, PNG | Architecture diagrams with containers and icons |\n| `render_graphviz` | DOT code | SVG, PNG | Dependency graphs, network diagrams |\n| `render_chart` | Vega-Lite JSON | SVG, PNG | Bar, line, scatter, area, heatmap charts |\n\n### HTML Generators (No Docker)\n\n| Tool | Input | Output | Use Case |\n|------|-------|--------|----------|\n| `render_html_page` | HTML body + theme | Self-contained HTML | Technical docs, reports, dashboards |\n| `render_slides` | JSON slide array + theme | HTML slide deck | Presentations, status updates, walkthroughs |\n\n### Utilities\n\n| Tool | Description |\n|------|-------------|\n| `get_tool_guide` | Usage examples, anti-patterns, complexity limits per tool |\n| `list_assets` | List all generated files in the output directory |\n\n## Quick Start\n\n### 1. Start the rendering container (for diagram tools)\n\n```bash\ncd docker\ndocker compose up -d\n```\n\n> HTML page and slide tools work without Docker.\n\n### 2. Install the MCP server\n\n**Option A -- npx (no install)**\n\n```bash\nnpx mcp-media-forge\n```\n\n**Option B -- Clone and build**\n\n```bash\ngit clone https://github.com/PavelGuzenfeld/mcp-media-forge.git\ncd mcp-media-forge\nnpm install\nnpm run build\n```\n\n### 3. Register with your MCP client\n\nAny MCP-compatible client (Claude Code, Cursor, VS Code + Copilot, Cline, etc.) can use this server. The standard config:\n\n```json\n{\n  \"mcpServers\": {\n    \"media-forge\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-media-forge/dist/index.js\"],\n      \"env\": {\n        \"PROJECT_ROOT\": \"/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\nWhere to add this depends on your client:\n- **Claude Code**: `~/.claude/settings.json`\n- **Cursor**: MCP settings panel\n- **VS Code (Copilot)**: `.vscode/mcp.json`\n- **Cline**: MCP server configuration\n\n### 4. Use it\n\nAsk your AI assistant to generate diagrams, pages, or presentations:\n\n> \"Create a sequence diagram showing the OAuth2 flow and embed it in the README\"\n\n> \"Generate an HTML page summarizing the API architecture with KPI cards\"\n\n> \"Make a slide deck with our Q1 metrics and architecture overview\"\n\nThe agent calls the appropriate tool, gets back a file path, and embeds it in your markdown.\n\n## How It Works\n\n```\nAI Agent (any MCP client)\n    |\n    | MCP Protocol (JSON-RPC over stdio)\n    v\nMCP Media Forge (Node.js on host)\n    |\n    |--- Diagrams: docker exec (sandboxed, no network)\n    |       |\n    |       v\n    |   Rendering Container\n    |     ├── mmdc       (Mermaid CLI + Chromium)\n    |     ├── d2         (D2 diagrams)\n    |     ├── dot/neato  (Graphviz)\n    |     └── vl2svg     (Vega-Lite via vl-convert)\n    |\n    |--- HTML/Slides: template engine (no Docker)\n    |       |\n    |       v\n    |   CSS Design System (4 themes, depth tiers, components)\n    |\n    v\ndocs/generated/\n  mermaid-a1b2c3.svg\n  d2-7f8e9a.svg\n  html_page-d4e5f6.html\n  slides-8b9c0d.html\n```\n\n**Key design decisions:**\n\n- **Text in, file path out** -- returns relative paths, never base64 blobs\n- **Content-hash naming** -- same input = same file = free caching + git-friendly\n- **SVG preferred** -- vector format, small files, diffs cleanly in git\n- **Docker-contained** -- diagram renderers run in a sandboxed container with `network_mode: none`\n- **Self-contained HTML** -- pages and slides have zero external dependencies (inline CSS/JS)\n- **Input pre-validation** -- catches common mistakes before Docker round-trips\n- **Structured errors** -- error responses include `error_type`, `error_message`, and `suggestion` to enable LLM self-correction\n\n## Tool Reference\n\n### get_tool_guide\n\nGet usage guide for any tool before rendering. Returns examples, anti-patterns to avoid, complexity limits, and tips.\n\n```json\n{ \"tool_name\": \"mermaid\" }\n```\n\nAvailable guides: `mermaid`, `d2`, `graphviz`, `vegalite`, `html_page`, `slides`, or `all` for a summary.\n\n### render_mermaid\n\n```json\n{\n  \"code\": \"flowchart TD\\n    A[Start] --> B{Decision}\\n    B -->|Yes| C[Done]\",\n  \"format\": \"svg\",\n  \"theme\": \"default\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `code` | string | required | Mermaid diagram code (must start with diagram type) |\n| `format` | `svg` \\| `png` | `svg` | Output format |\n| `theme` | `default` \\| `dark` \\| `forest` \\| `neutral` | `default` | Mermaid theme |\n\n**Pre-validation catches:** missing diagram type, semicolons, HTML in labels, >25 nodes.\n\n### render_d2\n\n```json\n{\n  \"code\": \"client -> server -> database\",\n  \"format\": \"svg\",\n  \"layout\": \"dagre\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `code` | string | required | D2 diagram code |\n| `format` | `svg` \\| `png` | `svg` | Output format |\n| `theme` | number | -- | Theme ID (0=default, 1=neutral-grey, 3=terminal) |\n| `layout` | `dagre` \\| `elk` \\| `tala` | `dagre` | Layout engine |\n\n**Pre-validation catches:** Mermaid/D2 syntax confusion, unbalanced braces, >3 nesting depth.\n\n### render_graphviz\n\n```json\n{\n  \"dot_source\": \"digraph G { A -> B -> C }\",\n  \"engine\": \"dot\",\n  \"format\": \"svg\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `dot_source` | string | required | Graphviz DOT source code |\n| `engine` | `dot` \\| `neato` \\| `fdp` \\| `sfdp` \\| `twopi` \\| `circo` | `dot` | Layout engine |\n| `format` | `svg` \\| `png` | `svg` | Output format |\n\n**Pre-validation catches:** missing graph wrapper, `->` in undirected graphs, unbalanced braces.\n\n### render_chart\n\n```json\n{\n  \"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\\\"}}}\",\n  \"format\": \"svg\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `spec_json` | string | required | Vega-Lite JSON specification |\n| `format` | `svg` \\| `png` | `svg` | Output format |\n| `scale` | number | 1 | Scale factor for PNG output |\n\n**Pre-validation catches:** invalid JSON, missing `$schema`/`data`/`mark`, >500 inline data rows.\n\n### render_html_page\n\nGenerates a self-contained themed HTML page. No Docker required.\n\n```json\n{\n  \"title\": \"System Overview\",\n  \"body_html\": \"<section id=\\\"metrics\\\"><h2>Metrics</h2><div class=\\\"mf-grid mf-grid-3\\\">...</div></section>\",\n  \"theme\": \"swiss\",\n  \"description\": \"Q1 architecture overview\",\n  \"nav_sections\": [\"Metrics\", \"Architecture\", \"Roadmap\"]\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `title` | string | required | Page title |\n| `body_html` | string | required | HTML body content (inner content only, no `<html>`/`<head>`/`<body>`) |\n| `theme` | `swiss` \\| `midnight` \\| `warm` \\| `terminal` | `swiss` | Visual theme |\n| `description` | string | -- | Page description (meta tag + header) |\n| `nav_sections` | string[] | -- | Section names for floating IntersectionObserver navigation |\n\n**Design system CSS classes:**\n\n| Class | Purpose |\n|-------|---------|\n| `mf-hero` | Primary highlight section (large shadow) |\n| `mf-elevated` | Secondary highlight (medium shadow) |\n| `mf-card` | Bordered content card |\n| `mf-recessed` | De-emphasized content |\n| `mf-grid mf-grid-2` | Responsive 2-column grid |\n| `mf-grid mf-grid-3` | Responsive 3-column grid |\n| `mf-split` | Two equal columns |\n| `mf-kpi` + `mf-kpi-value` + `mf-kpi-label` | Key metric display |\n| `mf-badge-success/warning/error/info` | Status badges |\n\n**Themes:**\n\n| Theme | Style | Best for |\n|-------|-------|----------|\n| `swiss` | White, geometric, blue accent | Technical docs |\n| `midnight` | Deep navy, serif, gold accent | Presentations |\n| `warm` | Cream paper, bold sans, terracotta | Reports |\n| `terminal` | Dark, monospace, cyan accent | Developer content |\n\n### render_slides\n\nGenerates a self-contained HTML slide deck with keyboard/touch navigation. No Docker required.\n\n```json\n{\n  \"title\": \"Q1 Review\",\n  \"slides\": \"[{\\\"title\\\":\\\"Q1 Review\\\",\\\"content\\\":\\\"Engineering update\\\",\\\"type\\\":\\\"title\\\"},{\\\"title\\\":\\\"Metrics\\\",\\\"content\\\":\\\"<ul><li>99.9% uptime</li></ul>\\\",\\\"type\\\":\\\"content\\\"}]\",\n  \"theme\": \"midnight\",\n  \"author\": \"Engineering Team\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `title` | string | required | Presentation title |\n| `slides` | string | required | JSON array of slide objects |\n| `theme` | `swiss` \\| `midnight` \\| `warm` \\| `terminal` | `swiss` | Visual theme |\n| `author` | string | -- | Author (shown on title slide) |\n\n**Slide types:**\n\n| Type | Layout | Best for |\n|------|--------|----------|\n| `title` | Centered large text + subtitle | Opening/closing slides |\n| `section` | Centered heading + description | Topic dividers |\n| `content` | Heading + body (bullets, text) | Most content |\n| `split` | Heading + two columns | Before/after, comparisons |\n| `code` | Heading + code block | Code walkthroughs |\n| `quote` | Large blockquote + attribution | Testimonials, key quotes |\n| `kpi` | Heading + auto-grid metrics | Dashboards, stats |\n| `image` | Heading + centered image | Screenshots, diagrams |\n\n**Navigation:** Arrow keys, Space, PageUp/PageDown, Home/End. Touch: swipe left/right. Click dots to jump.\n\n### list_assets\n\n```json\n{ \"directory\": \"\" }\n```\n\nReturns a JSON array of all generated files with name, path, size, and modification time.\n\n## Error Handling\n\nAll tools return structured errors that help LLMs self-correct:\n\n```json\n{\n  \"status\": \"error\",\n  \"error_type\": \"syntax_error\",\n  \"error_message\": \"First line must declare diagram type. Got: \\\"A --> B\\\"\",\n  \"suggestion\": \"Start with: flowchart TD, sequenceDiagram, erDiagram, ... See https://mermaid.js.org/syntax/\"\n}\n```\n\nError types: `syntax_error`, `rendering_error`, `dependency_missing`.\n\n**Pre-validation** catches common LLM mistakes before hitting the renderer:\n- Mermaid: missing diagram type, semicolons, HTML tags, legacy `graph` syntax\n- D2: Mermaid syntax confusion (`-->`, `subgraph`), unbalanced braces\n- Graphviz: missing `digraph`/`graph` wrapper, `->` in undirected graphs\n- Vega-Lite: invalid JSON, missing required fields, oversized inline data\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PROJECT_ROOT` | `cwd()` | Project root for output path resolution |\n| `OUTPUT_DIR` | `docs/generated` | Output directory relative to PROJECT_ROOT |\n| `MEDIA_FORGE_CONTAINER` | `media-forge-renderer` | Docker container name |\n\n## Development\n\n```bash\nnpm install\nnpm run build          # Build with tsup\nnpm run dev            # Watch mode\nnpm test               # Run all tests (95 total)\nnpm run test:unit      # Unit tests only (no Docker needed)\nnpm run test:component # Integration tests (Docker tools need container)\nnpm run lint           # Type-check with tsc\n```\n\n### Running integration tests\n\n```bash\ncd docker && docker compose up -d   # Start renderer (diagram tools only)\ncd .. && npm run test:component     # All integration tests\n```\n\n> HTML page and slide integration tests run without Docker.\n\n## Examples\n\nSee [examples/](examples/) for sample input files:\n\n| File | Tool | Description |\n|------|------|-------------|\n| [`mermaid/flowchart.mmd`](examples/mermaid/flowchart.mmd) | render_mermaid | Decision flowchart |\n| [`mermaid/sequence.mmd`](examples/mermaid/sequence.mmd) | render_mermaid | Client-server sequence |\n| [`d2/architecture.d2`](examples/d2/architecture.d2) | render_d2 | Backend architecture with containers |\n| [`graphviz/dependencies.dot`](examples/graphviz/dependencies.dot) | render_graphviz | npm dependency graph |\n| [`vegalite/bar-chart.json`](examples/vegalite/bar-chart.json) | render_chart | Tool performance comparison |\n\nSee [examples/README.md](examples/README.md) for MCP tool call examples and expected responses.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 13347,
  "sha": "4331da8f75c49769b8a63ace9708652f406972a27237465466ecc4936680b2b0",
  "repo_slug": "pavelguzenfeld/mcp-media-forge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pavelguzenfeld_media_forge_7dd1d675/readme"
}