MCP Media Forge

MCP媒体锻造

MCP服务器，从文本DSL生成图表、HTML页面和幻灯片，专为AI编码代理嵌入Markdown而设计。

LLM代理调用以下工具 render_mermaid, render_html_page，或 render_slides 使用文本输入，并返回准备嵌入文档的资产的文件路径。

输出图库

美人鱼流程图

美人鱼序列图

D2架构图

Graphviz依赖关系图

Vega Lite条形图

工具

图表渲染器（Docker）

HTML生成器（无Docker）

公用事业

快速开始

1.启动渲染容器（用于图表工具）

cd docker
docker compose up -d

HTML页面和幻灯片工具可以在没有Docker的情况下工作。

2.安装MCP服务器

选项A--npx（不安装）

npx mcp-media-forge

选项B——克隆和构建

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

3.向您的MCP客户注册

任何兼容MCP的客户端（Claude Code、Cursor、VS Code+Copilot、Cline等）都可以使用此服务器。标准配置：

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

在哪里添加取决于您的客户：

• 克劳德代码: ~/.claude/settings.json
• 光标：MCP设置面板
• VS代码（副本）: .vscode/mcp.json
• 克莱恩：MCP服务器配置

4.使用它

让你的AI助手生成图表、页面或演示文稿：

“创建一个显示OAuth2流的序列图，并将其嵌入README中”

“生成一个HTML页面，用KPI卡总结API体系结构”

“用我们的第一季度指标和架构概述制作幻灯片”

代理调用相应的工具，获取文件路径，并将其嵌入到您的markdown中。

运作原理

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

关键设计决策：

• 文本输入，文件路径输出 --返回相对路径，从不返回base64 blob
• 内容哈希命名 --相同的输入=相同的文件=免费缓存+git友好
• 首选SVG --矢量格式，小文件，git中清晰的差异
• Docker包含 --图表渲染器在沙盒容器中运行 network_mode: none
• 自包含HTML --页面和幻灯片没有外部依赖（内联CSS/JS）
• 输入预验证 --在Docker往返之前发现常见错误
• 结构化错误 --错误响应包括 error_type, error_message，以及 suggestion 启用LLM自校正

工具参考

get_tool_guide

在渲染之前获取任何工具的使用指南。返回示例、要避免的反模式、复杂性限制和提示。

{ "tool_name": "mermaid" }

可用指南： mermaid, d2, graphviz, vegalite, html_page, slides，或 all 总结一下。

render_mermaid

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

预验证捕获： 缺少图表类型、分号、标签中的HTML、>25个节点。

render_d2

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

预验证捕获： Mermaid/D2语法混乱，大括号不平衡，嵌套深度>3。

render_graphviz

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

预验证捕获： 缺少图形包装器， -> 在无向图中，不平衡的大括号。

渲染图

{
  "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"
}

预验证捕获： JSON无效，缺失 $schema/data/mark，>500个内联数据行。

render_html_page

生成一个自包含的主题HTML页面。不需要Docker。

{
  "title": "System Overview",
  "body_html": "

Metrics

...

",
  "theme": "swiss",
  "description": "Q1 architecture overview",
  "nav_sections": ["Metrics", "Architecture", "Roadmap"]
}

设计系统CSS类：

主题：

render_slides

生成一个带有键盘/触摸导航的独立HTML幻灯片。不需要Docker。

{
  "title": "Q1 Review",
  "slides": "[{\"title\":\"Q1 Review\",\"content\":\"Engineering update\",\"type\":\"title\"},{\"title\":\"Metrics\",\"content\":\"

99.9% uptime

\",\"type\":\"content\"}]",
  "theme": "midnight",
  "author": "Engineering Team"
}

幻灯片类型：

导航： 箭头键、空格键、向上翻页/向下翻页、主页/结束。触摸：向左/向右滑动。单击点以跳跃。

list_资产

{ "directory": "" }

返回所有生成文件的JSON数组，包括名称、路径、大小和修改时间。

错误处理

所有工具都返回有助于LLM自我纠正的结构化错误：

{
  "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/"
}

错误类型： syntax_error, rendering_error, dependency_missing.

预验证 在进入渲染器之前捕获常见的LLM错误：

• Mermaid：缺少图表类型、分号、HTML标签、遗留问题 graph 语法
• D2：Mermaid语法混乱(-->, subgraph)，不平衡的牙套
• Graphviz：缺失 digraph/graph 包装， -> 在无向图中
• Vega Lite：JSON无效，缺少必填字段，内联数据过大

环境变量

发展

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

运行集成测试

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

HTML页面和幻灯片集成测试在没有Docker的情况下运行。

例子

看 示例/ 对于示例输入文件：

看 示例/README.md MCP工具调用示例和预期响应。

许可证

麻省理工学院