图表生成器

用途

通过将用户意图转化为结构化的 JSON 规范，再交由 mcp-diagram-generator MCP 服务器执行文件生成，从而创建和编辑图表。

支持的格式：

• Draw.io：.drawio
• Mermaid：.mmd 或 Markdown 格式的 Mermaid 内容
• Excalidraw：.excalidraw

支持的工作场景：

• 基于自然语言的图表创建
• 对现有 .drawio、.mmd 和 .excalidraw 文件进行编辑
• 默认输出路径为 diagrams/{format}/
• 支持自定义文件名与输出路径

必需的 MCP 工具

在生成图表前，请确认 MCP 服务器工具已就绪：

• mcp__mcp-diagram-generator__get_config
• mcp__mcp-diagram-generator__generate_diagram
• mcp__mcp-diagram-generator__init_config

若缺少任一工具，请配置 MCP 服务器。

推荐的远程配置如下：

{
  "mcpServers": {
    "mcp-diagram-generator": {
      "command": "npx",
      "args": ["-y", "mcp-diagram-generator"]
    }
  }
}

修改配置后，请重启 agent 环境。首次使用时，服务器将自动创建 .diagram-config.json 及默认输出目录。本地开发配置请参阅“故障排除”中的“工具缺失”条目。

主工作流

1. 输入采集（Intake）

对于新建图表，在接受或处理完整图表提示前，需先收集以下基础选项：

• 图表类型
• 输出格式
• 布局方向
• 使用上下文
• 可选的文件名或输出目录

提问前请先阅读 references/interaction-intake-guide.md。

若用户已明确提供全部必要选项及完整提示，则跳过输入采集环节；对于已有文件的编辑任务，仅当目标文件或所需变更信息缺失时，才需向用户确认。

2. 分派至对应手册（Playbook）

根据图表类型，**严格选择且仅选择一个**主手册：

仅阅读当前图表所需的手册内容。若手册中引用了 json-schema-guide.md 或 network-topology-examples.md，也只需阅读相关章节。如需显式控制几何布局，还需额外查阅 references/layout-quality-guide.md。

3. 选择格式

除非用户明确指定，否则采用以下默认设置：

使用上下文可覆盖上述默认值：

• Word 文档：优先选用适合纵向排版的垂直布局。
• PPT 演示文稿：当提升可读性时，允许使用水平布局。
• 代码仓库与文档：简单流程图、序列图、类图、ER 图优先选用 Mermaid。
• 白板协作场景：优先选用 Excalidraw。
• 复杂网络或架构图：优先选用 Draw.io，除非用户明确要求使用 Excalidraw。

4. 构建 JSON 规范

请依据 references/json-schema-guide.md 中定义的 Schema 编写。核心结构如下：

{
  "format": "drawio",
  "diagramType": "architecture",
  "title": "图表标题",
  "elements": [
    {
      "id": "unique-id",
      "type": "container",
      "name": "显示名称",
      "level": "environment",
      "geometry": { "x": 0, "y": 0, "width": 800, "height": 600 },
      "children": []
    },
    {
      "type": "edge",
      "source": "source-id",
      "target": "target-id"
    }
  ]
}

通用规则：

• elements 必须为数组。
• ID 必须全局唯一。
• 边（edge）必须作为顶层元素存在，不可嵌套于 children 中。

完整字段说明请参阅：references/json-schema-guide.md。

5. 质量门控（Quality Gate）

调用 MCP 服务器前，请验证以下各项：

• 所选格式与输入采集结果及手册一致。
• 当支持时，diagramType 字段必须显式声明。
• 布局方向应在坐标或生成器特定字段中体现。
• 复杂的 Draw.io 和 Excalidraw 图表必须包含显式的 geometry 字段。
• 容器层级关系合法有效。
• 边（edge）均为顶层元素。
• 文本与连接线规则符合所选格式规范。

生成完成后，应检查已保存文件，确保其具备该格式所需的特定属性。若对 MCP 服务器代码进行了修改，还需在 mcp-diagram-generator/ 目录下运行 npm run test:diagrams。

6. 执行生成

首选调用方式：

{
  "diagram_spec": ""
}

指定可选文件名：

{
  "diagram_spec": "",
  "filename": "my-diagram.drawio"
}

指定可选输出路径：

{
  "diagram_spec": "",
  "output_path": "custom/path/to/diagram.drawio"
}

MCP 服务器将校验 Schema，自动创建缺失目录；若未提供 output_path，则写入配置中指定的默认目录。

配置辅助工具

初始化默认配置：

init_config()

设置自定义路径：

{
  "paths": {
    "drawio": "output/diagrams/drawio",
    "mermaid": "output/diagrams/mermaid",
    "excalidraw": "output/diagrams/excalidraw"
  }
}

查看当前配置：

get_config()

更新单个格式路径：

{
  "format": "drawio",
  "path": "custom/drawio-path"
}

故障排除

工具缺失：

• 使用上方所示远程（npx）配置块配置 MCP 服务器，并重启 agent 环境。
• 本地开发时，请改用 "command": "node", "args": ["/absolute/path/to/mcp-diagram-generator/dist/index.js"]。

Schema 校验失败：

• 通读 references/json-schema-guide.md。
• 检查必填字段、ID 唯一性、边的 source/target 是否有效、父子结构是否合规。

目录错误：

• 确认写入权限。
• 运行 get_config() 查看当前路径配置。
• 必要时，运行 init_config() 重新初始化。

扩展名错误：

• Draw.io 使用 .drawio 扩展名。
• Mermaid 使用 .mmd 扩展名，或直接输出 Markdown 格式内容。
• Excalidraw 使用 .excalidraw 扩展名。

嵌套容器问题：

• 子元素坐标系以直接父容器为原点（相对坐标）。
• 容器尺寸必须能容纳所有子元素边界并留有足够内边距（padding）。
• 网络拓扑结构必须严格遵循 environment → datacenter → zone → device 的层级顺序。

参考索引

按需查阅以下文档：

• references/interaction-intake-guide.md：交互式输入采集的默认行为与提问模板。
• references/format-selection-guide.md：格式选择对照矩阵。
• references/playbook-network-topology.md：Draw.io 与 Excalidraw 网络拓扑绘制规则。
• references/playbook-architecture.md：分层架构图绘制规则。
• references/playbook-flowchart.md：流程与决策逻辑绘制规则。
• references/playbook-swimlane.md：泳道图与跨团队交接流程绘制规则。
• references/playbook-uml.md：序列图、类图、ER 图绘制规则。
• references/playbook-excalidraw.md：Excalidraw 白板草图与绑定规则。
• references/layout-quality-guide.md：显式几何布局、间距与连接线可读性规则。
• references/json-schema-guide.md：Schema 详细定义与示例。
• references/network-topology-examples.md：网络拓扑 JSON 模式范例。

输出规范

向用户响应时，请遵守以下原则：

• 明确确认所选图表类型、格式、布局方向及输出文件名。
• 除非用户主动要求，否则不得粘贴完整 JSON 内容。
• 提供已保存文件的完整路径。
• 说明是否执行了任何校验或回归测试命令（如 npm run test:diagrams）。