智能开发环境下的 Diagram-as-Code 实践：MCP Mermaid 技术链路拆解

智能开发环境下的 Diagram-as-Code 实践：MCP Mermaid 技术链路拆解

在智能开发环境（IDE + AI Agent）中，Diagram-as-Code（用代码描述图表）已成为高效可视化复杂技术链路的标配。Mermaid 作为最流行的开源 Diagram-as-Code 工具，以 Markdown-like 语法生成流程图、序列图、架构图等，无需绘图工具即可版本控制、协作和自动化渲染。

结合 Anthropic 的 Model Context Protocol (MCP)（2025 年 11 月发布），AI 代理可以通过代码执行模式高效调用外部工具，而 Mermaid 正好适合可视化这种“代码驱动的工具链路”。下面我完整拆解 MCP 的技术链路，并用 Mermaid 实践 Diagram-as-Code 展示对比。

为什么在智能开发环境中用 Mermaid + MCP？

• Mermaid 优势：纯文本、可 git 管理、实时预览（VS Code、Obsidian、Typora 等支持）、AI 一键生成。
• MCP 优势：解决传统工具调用 token 爆炸问题，通过“代码执行”模式让 AI 生成代码调用工具（而非直接工具调用）。
• 结合实践：AI 代理（如 Claude）在 MCP 环境中生成 Mermaid 代码，直接渲染复杂链路（如工具调用、数据流），极大提升架构设计效率。

MCP 技术链路核心拆解

传统工具调用 vs MCP 代码执行模式的对比：

1. 传统模式痛点：

• 所有工具定义一次性加载到上下文 → token 爆炸。
• 中间结果（大文档、表格）反复传递 → 延迟高、成本高、易超上下文窗口。

1. MCP 代码执行模式改进：

• 工具以文件树形式暴露（./servers/tool.ts）。
• AI 生成代码调用工具 → 在沙盒执行环境运行 → 只返回精炼结果。
• 支持渐进发现、数据过滤、循环/条件控制、隐私保护。

Mermaid 实践：MCP 链路可视化

以下是用 Mermaid 生成的两种图表，直接复制到支持 Mermaid 的环境（如 Markdown 编辑器）即可渲染。

1. 流程图：传统 vs MCP 代码执行对比

flowchart TD
    subgraph Traditional [传统工具调用]
        A[AI 模型] --> B[加载所有工具定义<br>(数十万 token)]
        B --> C[直接调用工具]
        C --> D[返回完整结果<br>(大文档反复传递)]
        D --> A
        style Traditional fill:#ffebee,stroke:#f44336
    end

    subgraph MCP_Code [MCP 代码执行模式]
        E[AI 模型] --> F[浏览工具文件树<br>(按需加载)]
        F --> G[生成调用代码]
        G --> H[沙盒执行环境<br>过滤/聚合数据]
        H --> I[返回精炼结果<br>(仅摘要, token 极少)]
        I --> E
        style MCP_Code fill:#e8f5e8,stroke:#4caf50
    end

    Traditional -. 98.7% token 节省 .-> MCP_Code

2. 序列图：MCP 代码执行详细交互

sequenceDiagram
    participant User as 用户/开发者
    participant Agent as AI 代理 (Claude)
    participant MCP as MCP 服务器 (文件树)
    participant Exec as 执行沙盒
    participant Tool as 外部工具 (e.g. Google Drive)

    User->>Agent: 描述任务 (e.g. "从 Drive 读文档更新 Salesforce")
    Agent->>MCP: 列出 ./servers/ 目录
    MCP-->>Agent: 返回工具文件列表
    Agent->>Agent: 生成 TypeScript 代码
    Agent->>Exec: 提交代码执行
    Exec->>Tool: 调用实际 API (e.g. getDocument)
    Tool-->>Exec: 返回完整数据
    Exec->>Exec: 代码中过滤/聚合
    Exec-->>Agent: 返回精炼结果 (e.g. 摘要)
    Agent-->>User: 最终答案 + Mermaid 图表

智能开发环境实践步骤（VS Code + Claude Dev 示例）

1. 安装插件：

• VS Code: “Mermaid Preview” + “Claude Dev” (Anthropic 官方 MCP 支持插件)。

1. 配置 MCP：

• 工具暴露为 ./mcp-servers/tool.ts 文件树。

1. AI 生成 Mermaid：

• 提示 Claude：”用 Mermaid 序列图拆解这个 MCP 任务链路…”
• AI 输出代码 → 实时预览。

1. 自动化：

• 用 MCP 代码执行生成动态图表（e.g. 根据数据库 schema 自动生成 ER 图）。

总结与最佳实践

• MCP + Mermaid 是 2025 年智能开发的核心模式：AI 生成代码 → 执行工具 → 输出可视化图表。
• 优势：token 高效、链路清晰、可复用。
• 建议：所有架构文档都用 Mermaid 编写，结合 MCP 实现“自文档化”工具链。

如果需要：

• 更多图表（ER 图、架构图）
• 完整 TypeScript MCP 示例代码
• VS Code 配置截图

直接告诉我，我继续生成！