media-forge

MCP Media Forge

可根据文本 DSL 生成图表、HTML 页面和幻灯片的 MCP 服务，专为将内容嵌入 Markdown 的 AI 编码 Agent 打造。

大模型 Agent 可通过 render_mermaid、render_html_page 或 render_slides 等工具提供文本输入，并获取可嵌入文档的资源文件路径。

输出示例

Mermaid 流程图

Mermaid 时序图

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 Code：~/.claude/settings.json
• Cursor：MCP 设置面板
• VS Code (Copilot)：.vscode/mcp.json
• Cline：MCP 服务配置

4. 使用

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

“创建一张展示 OAuth2 流程的时序图，并将其嵌入 README”

“生成一个 HTML 页面，用 KPI 卡片概述 API 架构”

“制作一套包含我们 Q1 指标和架构概览的幻灯片”

Agent 会调用相应的工具，获取文件路径，并将其嵌入 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 数据块
• 基于内容哈希命名 -- 相同输入 = 相同文件 = 免费缓存 + 便于 Git 管理
• 优先使用 SVG -- 矢量格式、文件小，且在 Git 中差异清晰
• Docker 隔离 -- 图表渲染器在沙盒容器中运行，并设置 network_mode: none
• 独立 HTML -- 页面和幻灯片没有外部依赖（CSS/JS 均内联）
• 输入预校验 -- 在 Docker 往返调用之前捕获常见错误
• 结构化错误 -- 错误响应包含 error_type、error_message 和 suggestion，便于大模型自我纠正

工具参考

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	字符串	必填	Mermaid 图表代码（必须以图表类型开头）
format	svg | png	svg	输出格式
theme	default | dark | forest | neutral	default	Mermaid 主题

预验证会检查： 缺少图表类型、分号、标签中的 HTML、超过 25 个节点。

render_d2

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

参数	类型	默认值	描述
code	字符串	必填	D2 图表代码
format	svg | png	svg	输出格式
theme	数字	--	主题 ID（0=默认，1=中性灰，3=终端）
layout	dagre | elk | tala	dagre	布局引擎

预验证会检查： Mermaid/D2 语法混淆、大括号不匹配、嵌套深度超过 3 层。

render_graphviz

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

参数	类型	默认值	描述
dot_source	字符串	必填	Graphviz DOT 源代码
engine	dot | neato | fdp | sfdp | twopi | circo	dot	布局引擎
format	svg | png	svg	输出格式

预验证会检查： 缺少图形包装器、无向图中出现 ->、大括号不匹配。

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

参数	类型	默认值	描述
spec_json	字符串	必填	Vega-Lite JSON 规范
format	svg | png	svg	输出格式
scale	数字	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	字符串	必填	页面标题
body_html	字符串	必填	HTML 正文内容（仅限内部内容，不含 <html>/<head>/<body>）
theme	swiss | midnight | warm | terminal	swiss	视觉主题
description	字符串	--	页面描述（meta 标签 + 页眉）
nav_sections	string[]	--	用于浮动 IntersectionObserver 导航的版块名称

设计系统 CSS 类：

类	用途
mf-hero	主要高亮区块（大阴影）
mf-elevated	次要高亮区块（中等阴影）
mf-card	带边框的内容卡片
mf-recessed	弱化显示的内容
mf-grid mf-grid-2	响应式双列网格
mf-grid mf-grid-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 | terminal	swiss	视觉主题
author	string	--	作者（显示在标题幻灯片上）

幻灯片类型：

类型	布局	适用场景
title	居中的大字文本 + 副标题	开场/结束幻灯片
section	居中的标题 + 描述	主题分隔页
content	标题 + 正文（项目符号、文本）	大多数内容
split	标题 + 两栏	前后对比、比较
code	标题 + 代码块	代码讲解
quote	大型引用块 + 出处	用户评价、重要引语
kpi	标题 + 自动网格指标	仪表板、统计数据
image	标题 + 居中图像	截图、图表

**导航：**方向键、空格、PageUp/PageDown、Home/End。触控：向左/向右滑动。点击圆点即可跳转。

list_assets

{ "directory": "" }

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

错误处理

所有工具都会返回结构化错误，帮助大模型自行纠正：

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

预验证会在调用渲染器之前捕获常见的大模型错误：

• 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 即可运行。

示例

请参阅 examples/ 中的示例输入文件：

文件	工具	描述
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	工具性能比较

请参阅 examples/README.md，了解 MCP 工具调用示例和预期响应。

许可证

MIT