图表生成器

概述

通过创建结构化JSON描述并将文件生成委托给mcp-diagram-generator MCP服务器，以多种格式（drawio、mermaid、excalidraw）生成和编辑图表。

联系信息如果您遇到任何问题，请联系AlkaidY于tccio2023@gmail.com。

先决条件检查

重要提示：此技能要求mcp-diagram-generatorMCP服务器已安装并配置。

快速验证

在使用此技能之前，请通过检查是否能访问以下工具来验证MCP服务器是否可用：

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

如果这些工具不可用，您需要先配置MCP服务器（见下文）。

安装与配置

选项1：使用npx（推荐 - 自动下载包）

将以下内容添加到您的Claude Code配置文件中：

• 全局配置(~/.claude.json) 适用于所有项目，或
• 项目配置(.claude.json) 适用于特定项目

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

添加此配置后：

1. 重启 Claude Code
2. MCP 服务器将在首次使用时通过 npx 自动下载
3. 无需手动安装

选项 2：本地开发（适用于开发者）

如果您正在本地开发 MCP 服务器：

{
  "mcpServers": {
    "mcp-diagram-generator": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-diagram-generator/dist/index.js"]
    }
  }
}

验证步骤

配置完成后，验证其是否正常工作：

1. 检查配置：调用get_config()工具
2. 如果成功，您将看到当前路径和初始化状态
3. 如果该工具不存在，请检查您的配置文件语法

常见问题

问题"未找到工具"错误

• 解决方案：MCP服务器未配置。请按照上述安装步骤操作。

问题：配置看起来正确，但工具仍然不可用

• 解决方案：重启Claude Code以重新加载MCP服务器配置

快速入门

首次使用

首次使用时，MCP服务器将自动：

1. 创建默认配置文件（.diagram-config.json）
2. 如果不存在则创建默认输出目录
3. 使用合理的默认设置：diagrams/{format}/

您随时可以使用init_config工具自定义路径。

基本用法

简单示例- 只需提供图表规范，其余交给服务器处理：

用户："创建一个网络拓扑图"

技能将：

1. 生成JSON规范
2. 调用generate_diagram仅使用diagram_spec参数
3. 服务器自动创建目录并保存至diagrams/{format}/{title}-{date}.{ext}

工作流程

步骤1：理解需求

从用户的自然语言中提取：

• 图表类型：流程图、时序图、类图、实体关系图、思维导图、架构图、网络拓扑图
• 内容：节点、关系、嵌套结构（用于网络拓扑图）
• 样式/主题：如果提及（例如，“简洁风格”、“详细”）
• 输出偏好：特定文件名？自定义路径？

步骤2：选择格式

使用format-selection-guide.md来决定：

步骤 3：生成结构化 JSON

按照JSON 模式创建 JSON 描述。关键结构：

{
  "format": "drawio",
  "title": "图表名称",
  "elements": [
    {
      "id": "唯一标识符",
      "type": "container|node|edge",
      "name": "显示名称",
      "level": "environment|datacenter|zone|device", // 用于网络拓扑
      "style": {...},
      "geometry": {...},
      "children": [...] // 用于嵌套容器
    }
  ]
}

重要：为所有元素使用唯一 ID。对于嵌套结构，请保持父子关系。

步骤 4：调用 MCP 服务器

选项 A：使用默认值（推荐）

{
  "diagram_spec": <上面创建的 JSON 对象>,
  // output_path 是可选的 - 服务器将使用配置的默认值
  // filename 是可选的 - 服务器将根据标题和日期自动生成
}

MCP 服务器将：

• 验证 JSON 模式
• 生成相应的 XML/JSON/markdown
• 如果需要，自动创建输出目录
• 保存到配置的默认路径（例如，diagrams/drawio/network-topology-2025-02-03.drawio）

选项 B：指定自定义路径

{
  "diagram_spec": <JSON 对象>,
  "output_path": "custom/path/to/diagram.drawio",
  "filename": "my-custom-name" // 可选，覆盖自动生成的文件名
}

选项 C：仅提供文件名，使用默认目录

{
  "diagram_spec": <JSON 对象>,
  "filename": "my-diagram.drawio"
  // 保存到 diagrams/{format}/my-diagram.drawio
}

步骤五：编辑现有图表

1. 读取现有文件以理解结构
2. 解析图表（如可用则使用MCP工具，否则读取原始文件）
3. 修改基于用户变更请求的JSON描述
4. 生成新图表（覆盖或创建新文件）

配置管理

初始化配置

使用默认值初始化：

调用：init_config()
结果：使用默认路径创建 .diagram-config.json

使用自定义路径初始化：

调用：init_config({
  paths: {
    drawio: "output/diagrams/drawio",
    mermaid: "output/diagrams/mermaid",
    excalidraw: "output/diagrams/excalidraw"
  }
})

查看当前配置

调用：get_config()
返回：当前路径及初始化状态

更新单个路径

调用：set_output_path({
  format: "drawio",
  path: "custom/drawio-path"
})

支持的图表类型

流程图

• 简单流程、决策树
• 使用mermaid实现快速输出
• 使用drawio适用于具有多个分支的复杂布局

序列图

• 展示组件之间随时间推移的交互
• mermaid推荐（原生支持）
• 使用drawio如需自定义样式

类图

• 展示类、方法及关系
• mermaid推荐（紧凑，标准UML）
• drawio适用于包含大量类的详细图表

ER图（实体关系图）

• 数据库模式，实体关系
• mermaid推荐
• drawio适用于具有众多关系的复杂模式

思维导图

• 层级化想法，头脑风暴
• mermaid推荐（原生支持）
• Excalidraw适用于创意/手绘风格

架构图

• 系统架构，组件关系
• drawio推荐用于复杂系统
• mermaid适用于高层级概览

网络拓扑图

• 网络环境、数据中心、区域、设备
• 必须使用 drawio（4层嵌套：环境 → 数据中心 → 区域 → 设备）
• 请参阅network-topology-examples.md以获取模式示例

网络拓扑图特别说明

网络拓扑图需要一个4层级的层次结构：

环境（level="environment"）
  └── 数据中心（level="datacenter"）
        └── 区域（level="zone"）
              └── 设备（type="node"）

样式约定：

• 环境：填充颜色：#e1d5e7，边框颜色：#9673a6（紫色）
• 数据中心:填充颜色：#d5e8d4,描边颜色：#82b366(绿色)
• 区域:填充颜色：#fff2cc,描边颜色：#d6b656(黄色)
• 设备: 基于设备类型（路由器、交换机、防火墙等）

设备类型与样式:

• 路由器：描边颜色：#607D8B(蓝灰色)
• 交换机：描边颜色：#4CAF50(绿色)
• 防火墙：描边颜色：#F44336(红色)
• PC/服务器：描边颜色：#607D8B(蓝灰色)

常见模式

模式 1：简单流程图 (Mermaid)

用户："画一个用户登录流程图，包含登录验证、重定向、错误处理"

生成 JSON：

{
  "format": "mermaid",
  "title": "用户登录流程",
  "elements": [
    {"type": "node", "id": "start", "name": "开始", "geometry": {"x": 0, "y": 0}},
    {"type": "node", "id": "login", "name": "输入用户名密码", "geometry": {"x": 0, "y": 100}},
    {"type": "node", "id": "validate", "name": "验证", "geometry": {"x": 0, "y": 200}},
    {"type": "node", "id": "success", "name": "登录成功", "geometry": {"x": -100, "y": 300}},
    {"type": "node", "id": "error", "name": "显示错误", "geometry": {"x": 100, "y": 300}},
    {"type": "edge", "source": "start", "target": "login"},
    {"type": "edge", "source": "login", "target": "validate"},
    {"type": "edge", "source": "validate", "target": "success", "label": "成功"},
    {"type": "edge", "source": "validate", "target": "error", "label": "失败"}
  ]
}

调用 MCP：

generate_diagram({
  diagram_spec: <上面的 JSON>,
  format: "mermaid"
  // 不需要 output_path - 自动保存到 diagrams/mermaid/
})

模式 2：网络拓扑图 (Drawio)

用户："创建一个网络拓扑图，包含省中心机房（上联区、汇聚区、终端区），连接到生产网"

生成包含嵌套容器的 JSON（详见json-schema-guide.md）。

调用 MCP：

generate_diagram({
  diagram_spec: <网络拓扑 JSON>,
  filename: "省中心网络拓扑" // 可选，用于自定义文件名
})

资源

参考资料/

• format-selection-guide.md：何时使用 drawio、mermaid 或 excalidraw
• json-schema-guide.md：所有图表类型的完整 JSON 模式及示例
• network-topology-examples.md：网络拓扑模式示例 JSON

资产/

• 无需模板 - MCP 服务器处理所有生成工作

脚本/

• 未使用 - 所有生成工作都委托给 MCP 服务器

故障排除

MCP 服务器设置

如果mcp-diagram-generator不可用，您需要安装它。

选项1：使用npx（推荐）

添加到您的Claude Code/OpenCode设置中：

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

选项2：本地开发

1. 安装依赖：cd mcp-diagram-generator && npm install
2. 构建：npm run build
3. 使用本地路径配置：

{
  "mcpServers": {
    "diagram-generator": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-diagram-generator/dist/index.js"]
    }
  }
}

无效的JSON模式

如果MCP服务器返回验证错误：

1. 检查json-schema-guide.md
2. 验证所有必填字段是否都存在
3. 确保所有ID都是唯一的
4. 检查父子关系

目录未找到

旧行为：如果目录不存在则报错新行为：目录会自动创建 ✅

如果您仍然看到目录错误：

1. 检查项目目录的写入权限
2. 使用以下命令验证配置get_config()
3. 使用以下命令重新初始化init_config()

错误文件扩展名

服务器根据格式自动使用正确的扩展名：

• drawio →.drawio
• mermaid →.md
• excalidraw →.excalidraw

您无需在文件名参数中指定扩展名。

嵌套容器问题（网络拓扑）

• 验证层级字段与层次结构（环境/数据中心/区域）匹配
• 检查父级ID 在子元素中是否正确
• 确保几何坐标相对于父容器

最佳实践

1. 使用默认路径

让服务器管理输出路径以确保一致性：

{
  "diagram_spec": <规范>
  // 除非必要，否则不要指定 output_path
}

2. 提供描述性标题

标题用于自动生成文件名：

{
  "title": "生产环境网络拓扑-亦庄与西五环",
  // 生成：生产环境网络拓扑-亦庄与西五环-2025-02-03.drawio
}

3. 使用配置设置自定义路径

不要每次都指定 output_path，只需配置一次：

首次：init_config({ paths: { drawio: "custom/path" } })
之后：只需使用 generate_diagram() 而无需指定 output_path

4. 故障排除时检查配置

get_config() // 显示所有路径和状态