AI导哈

图表生成服务

一个基于文本DSL生成图表、HTML页面和幻灯片的MCP服务器，专为AI编码代理设计。

  • by PavelGuzenfeld
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 PavelGuzenfeld/mcp-media-forge

使用说明

MCP媒体锻造

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

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

输出图库

美人鱼流程图

美人鱼序列图

D2架构图

Graphviz依赖关系图

Vega Lite条形图

工具

图表渲染器（Docker）

工具 输入 格式 用例
render_mermaid Mermaid代码 SVG、PNG 流程图、序列图、ER、状态图、甘特图、git图
render_d2 D2代码 SVG、PNG 带容器和图标的架构图
render_graphviz DOT代码 SVG、PNG 依赖关系图、网络图
render_chart Vega Lite JSON SVG、PNG 条形图、折线图、散点图、面积图、热图

HTML生成器（无Docker）

工具 输入 输出 用例
render_html_page HTML正文+主题 独立HTML 技术文档、报告、仪表板
render_slides JSON幻灯片数组+主题 HTML幻灯片 演示文稿、状态更新、演练

公用事业

工具 说明
get_tool_guide 使用示例、反模式、每个工具的复杂性限制
list_assets 列出输出目录中生成的所有文件

快速开始

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"
}
参数 类型 默认值 说明
code string 必填 美人鱼图代码（必须以图类型开头）
format svg png svg
theme default dark forest

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

render_d2

{
  "code": "client -> server -> database",
  "format": "svg",
  "layout": "dagre"
}
参数 类型 默认值 说明
code string 必填 D2图表代码
format svg png svg
theme number -- 主题ID（0=默认，1=中性灰色，3=终端）
layout dagre elk tala

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

render_graphviz

{
  "dot_source": "digraph G { A -> B -> C }",
  "engine": "dot",
  "format": "svg"
}
参数 类型 默认值 说明
dot_source string 必填 Graphviz DOT源代码
engine dot neato fdp
format svg png 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"
}
参数 类型 默认值 说明
spec_json string 必需 Vega Lite JSON规范
format svg png svg
scale number 1 PNG输出的比例因子

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

render_html_page

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

{
  "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"]
}
参数 类型 默认值 说明
title string 必填 页面标题
body_html string 必填 HTML正文内容（仅限内部内容，无 <html>/<head>/<body>)
theme swiss midnight warm
description string -- 页面描述（元标记+页眉）
nav_sections string[] -- 浮动IntersectionObserver导航的部分名称

设计系统CSS类：

类别 目的
mf-hero 主要高亮部分（大阴影）
mf-elevated 次要高光（中等阴影）
mf-card 带边框的内容卡
mf-recessed 弱化内容
mf-grid mf-grid-2 响应式双柱网格
mf-grid mf-grid-3 响应式3柱网格
mf-split 两列相等
mf-kpi + mf-kpi-value + mf-kpi-label 关键指标显示
mf-badge-success/warning/error/info 身份徽章

主题：

主题 风格 最适合
swiss 白色、几何、蓝色调 技术文档
midnight 深海军蓝、衬线、金色调 演示文稿
warm 奶油纸、粗体、赤陶 报道
terminal 深色、单色、青色调 开发者内容

render_slides

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

{
  "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"
}
参数 类型 默认值 说明
title string 必填 演示文稿标题
slides string 必填 幻灯片对象的JSON数组
theme swiss midnight warm
author string -- 作者（显示在标题幻灯片上）

幻灯片类型：

类型 布局 最适合
title 居中的大文本+字幕 打开/关闭幻灯片
section 居中的标题+描述 主题分隔符
content 标题+正文（项目符号、文本） 大部分内容
split 标题+两列 前后对比
code 标题+代码块 代码演练
quote 大宗商品报价+归因 推荐信、关键报价
kpi 标题+自动网格指标 仪表板、统计数据
image 标题+居中图像 截图、图表

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

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无效，缺少必填字段，内联数据过大

环境变量

变量 默认值 描述
PROJECT_ROOT cwd() 输出路径解析的项目根
OUTPUT_DIR docs/generated 相对于PROJECT_ROOT的输出目录
MEDIA_FORGE_CONTAINER media-forge-renderer Docker容器名称

发展

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的情况下运行。

例子

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

文件 工具 描述
mermaid/flowchart.mmd render_mermaid 决策流程图
mermaid/sequence.mmd render_mermaid 客户端-服务器序列
d2/architecture.d2 render_d2 带有容器的后端架构
graphviz/dependencies.dot render_graphviz npm依赖关系图
vegalite/bar-chart.json render_chart 工具性能比较

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

许可证

麻省理工学院

相关 MCP