Diagrams MCP Server

图表 MCP 服务

一个本地优先的 MCP 服务工程文档，用于将 PlantUML 和 Mermaid 图表保存在其所描述的代码旁

该服务为 MCP 客户端提供受控接口，用于读取和维护图表源文件， 并将其与代码库进行比较 它还会生成便于审查的图表草稿和渲染导出文件 源文件始终是可编辑的架构记录

阅读路径

从安装和 图表工作流开始，连接客户端并审查更改 从支持的客户端中选择编辑器或助手 阅读系统模型和配置， 以了解进程边界和渲染器要求 集成或排查问题时，请参阅工具契约和运行限制 参与贡献时，请遵循源代码组织 并查看工程文档索引 该索引将当前指南与历史设计和交接记录分开

项目状态

该项目处于技术预览阶段 版本零点十一点零包含十五个工具 对照本指南检查其行为时，请查看已安装的软件包版本

版本零点十点零新增可为空和数组的脚手架标签，并修正了 跨文件调用者名称冲突时的序列发送方归属问题

该软件包声明 Node 18 或更高版本为运行时要求 当前主分支持续集成会在 Ubuntu 和 Windows 上检查 Node 20、Node 22 和 Node 24 TypeScript 编译器是开发依赖项，而非必需的 生产依赖项

安装和客户端连接

使用 npm 安装已发布的服务：

npm install -g diagrams-mcp-server

在项目目录中运行引导式设置：

diagrams-mcp-server setup

支持的 MCP 客户端

从下方选择客户端以进行非交互式设置 使用其集成前，请先安装所选客户端 该表介绍此服务实现的设置方法

客户端	设置命令	设置行为
Claude Code	diagrams-mcp-server setup --client claude-code --yes	运行 claude mcp add，或在无法执行注册时打印该命令
Codex	diagrams-mcp-server setup --client codex --yes	运行 codex mcp add，或在无法执行注册时打印该命令
Cursor	diagrams-mcp-server setup --client cursor --yes	将 diagrams 条目写入 Cursor 配置
VS Code	diagrams-mcp-server setup --client vscode --yes	将 diagrams 条目写入工作区配置
OpenCode	diagrams-mcp-server setup --client opencode --yes	打印 opencode mcp add 的操作说明，需要手动完成一步
Antigravity	diagrams-mcp-server setup --client antigravity --yes	将 diagrams 条目写入 Antigravity 配置

项目范围和验证

针对当前项目固定 Cursor 配置：

diagrams-mcp-server setup --client cursor --scope project --yes

默认采用全局范围，且不会将 PROJECT_ROOT 写入服务条目 此时，服务会使用启动客户端提供的工作目录 项目范围会将 PROJECT_ROOT 写入配置，使服务固定关联到一个代码库 显式指定 --project-root 也会固定根目录 VS Code 设置会写入项目配置 OpenCode 设置只会打印操作说明，因此，当需要固定的 PROJECT_ROOT 时， 请手动配置其项目环境

设置后，重新加载客户端配置并检查可用工具 创建文件前，使用 diagrams_list 确认图表根目录 对于新项目，清单为空也是正常情况 其他 stdio MCP 客户端可以直接启动 diagrams-mcp-server，也可以使用参数 -y diagrams-mcp-server 运行 npx 服务器命令不会通过普通 CLI 参数接收工具请求 工具调用通过 MCP 连接传输

查看可用的启动和设置选项：

diagrams-mcp-server --help
diagrams-mcp-server setup --help

使用图表

首先使用 diagrams_list 查找现有图表 提出更改前，使用 diagrams_get 读取选定的源文件 使用 diagrams_diff 比较现有源文件与拟议的修订 然后通过 diagrams_update 应用审核后的修订 新建图表时使用 diagrams_create；明确要删除图表时使用 diagrams_delete

如果目标已存在，Create 会拒绝操作 Update 对现有图表进行操作 存储功能会验证可识别的图表扩展名和源文件结构 这些检查用于确认基本方言格式，而非完整的语言正确性 请使用渲染和人工审核来检查生成的图表

要起草新的架构图，请针对范围较小的代码范围使用 diagrams_generate 要起草调用流程图，请使用 diagrams_generate_sequence 要从空白设计开始，请使用 diagrams_template 这些工具会返回源文件供审核，但不会保存图表 决定保存后，将审核过的源文件传递给 diagrams_create

代码更改后，运行 diagrams_check_consistency，检查图表实体对应的声明证据 将未匹配的名称视为待审核提示 名称未匹配可能是因为语法不受支持或扫描不完整，而非架构缺陷

此工作流通过明确的审核步骤将各工具连接起来 这些箭头描述的是建议的用户工作流，而非自动化流水线 生成和比较不会替你保存文件

flowchart TB
    accTitle: Diagram review workflow
    accDescr: Read or draft source then review and compare before explicitly saving and rendering and checking consistency
    stored["Read existing diagram source"] --> review["Review source"]
    draft["Generate or template a draft"] --> review
    review --> compare["Compare revisions when needed"]
    compare --> save["Explicit create or update"]
    save --> render["Render and inspect"]
    render --> check["Check consistency against code"]
    check -->|Revise when needed| review

系统模型

MCP 客户端会将服务器作为子进程启动，并通过标准输入和标准输出交换协议消息 启动诊断信息使用标准错误，因此不会占用协议流

项目根目录定义代码分析边界 图表根目录定义图表存储边界 自定义模板定义会在项目根目录下单独读取 服务器启动时会解析这些根目录，之后不再更改 提供给工具的图表路径相对于图表根目录 提供给分析工具的代码范围相对于项目根目录

架构将协议处理与服务和外部资源分离 响应通过工具适配器返回给已连接的客户端

flowchart TB
    accTitle: System architecture
    accDescr: MCP requests pass through strict schemas and adapters to storage and analysis and rendering services
    client["MCP client"] <-->|stdio| server["CLI and MCP server"]
    server --> schemas["Strict input schemas"]
    schemas --> adapters["Tool adapters"]
    adapters --> store["Diagram storage"]
    adapters --> analysis["Analysis and generation"]
    adapters --> rendering["Rendering service"]
    store --> diagrams[("Diagrams root")]
    analysis --> code[("Project root")]
    rendering --> external["Local commands or opt in PlantUML endpoint"]

工具适配器负责协议契约和响应格式化 服务负责文件系统操作、分析和源文件生成 渲染器通过独立的命令边界调用外部命令行工具 预期的领域错误会转换为工具错误 意外错误会返回通用错误，并通过共享错误处理层记录

配置与渲染

PROJECT_ROOT 用于选择分析所针对的代码库 默认值为服务器进程的工作目录

DIAGRAMS_DIR 用于选择图表根目录 默认值为 PROJECT_ROOT 下的 diagrams 目录 相对路径会在 PROJECT_ROOT 下解析 绝对路径会指定单独的存储位置 更改任一根目录后，请重启服务器

渲染需要 PATH 中有可正常工作的外部渲染器 PlantUML 使用 plantuml 命令 Mermaid 使用 Mermaid CLI 包中的 mmdc 命令 服务器包不会替你安装这两种渲染器 外部渲染器包有各自的运行时要求

安装 Mermaid 命令：

npm install -g @mermaid-js/mermaid-cli

PlantUML 渲染优先使用本地命令 如果缺少该命令，则除非 ALLOW_REMOTE_PLANTUML 的值严格为 true，否则不会启用远程回退 将 DISABLE_REMOTE_PLANTUML 严格设置为 true 会覆盖该许可 启用回退后，PLANTUML_SERVER_URL 用于指定远程端点 默认端点是公共 PlantUML 渲染服务

远程回退会将图表源代码发送到配置的服务 Mermaid 渲染始终使用本地命令 本地渲染器执行失败会被视为错误，而不会触发远程重试 渲染会使用临时文件，并在操作完成后清理

渲染器选择遵循下方的决策图 远程许可是指 ALLOW_REMOTE_PLANTUML 的值严格为 true，且 DISABLE_REMOTE_PLANTUML 不为 true 只有缺少本地 PlantUML 命令时，才会进入该决策流程

flowchart TB
    accTitle: Renderer selection
    accDescr: Mermaid uses mmdc while PlantUML uses a local CLI or an explicitly permitted remote endpoint
    dialect{"Dialect"} -->|Mermaid| mermaid["Run local mmdc"]
    dialect -->|PlantUML| local{"Local plantuml command"}
    local -->|Available| plantuml["Run local plantuml"]
    local -->|Missing| permission{"Remote fallback allowed"}
    permission -->|No| failure["Return a render error"]
    permission -->|Yes| remote["Send source to configured endpoint"]

工具契约

该图表按主要用途对 15 个工具进行分组 它描述的是工具接口，而不是项目完成情况

pie showData
    accTitle: Tool categories
    accDescr: Five storage tools and three rendering tools and two analysis tools and four diagram drafting and template tools and one code drafting tool
    title Tool categories
    "Diagram storage" : 5
    "Rendering and sharing" : 3
    "Analysis and comparison" : 2
    "Diagram drafting and templates" : 4
    "Code drafting" : 1

清单与源代码访问

diagrams_list 支持 type_filter 和从 0 开始的偏移分页 显式指定的 limit 接受 1 到 500 省略 limit 时会返回所有剩余匹配项 响应会区分当前页数量与总数，并报告 has_more，以便调用方继续获取，无需猜测

diagrams_get 会返回完整源代码，除非 max_chars 用于请求一个窗口 显式指定的窗口接受 1 到 100000 个 UTF-16 代码单元 响应会同时报告 offset、returned_chars 和 total_chars， 以及 is_partial 和 has_more 超出源代码范围的 offset 会导致错误

diagrams_create、diagrams_update 和 diagrams_delete 是明确的 图表变更工具 当前检出版本中的全部 15 个工具都会拒绝未知输入参数 客户端应将 MCP 发现功能公开的工具架构作为准确的 参数参考

分析与比较

diagrams_check_consistency 会将提取出的图表名称与源代码中的 声明证据进行比较，并报告匹配文件和分析器层级 其提取器包括特定于语言的声明模式，以及通用的 整词回退匹配 可选的 TypeScript 编译器能够改进部分分析路径 结果仍是启发式分析，并不能证明运行时正确性

diagrams_diff 接受两侧输入 每侧必须且只能提供一个已存储路径或内联源代码 内联源代码必须标明可识别的图表方言 在读取任一已存储侧之前，会先检查输入格式

默认比较会报告新增和移除的名称，并以启发式方式配对重命名 它不会比较布局、成员签名或解析后的类型 将 compare_call_order 设为 true，还会按源代码顺序比较可识别的调用 名称，同时保留重复项 该模式每侧最多接受 10000 个可识别调用，超过上限时会报错， 而不是返回部分比较结果 它不能证明运行时的执行顺序

从版本 zero eleven zero 开始，include_rename_evidence 会为配对的 重命名名称添加两侧图表中精确的调用标签计数 重复的可识别调用会分别计数，匹配区分大小写 证据最多包含 100 对，并提供 pairs_available 和 pairs_capped 启用此选项时，每侧最多接受 10000 个可识别调用 结果会拒绝超出上限的调用，不会返回部分计数 此证据不会扫描代码，也无法证明身份或更改重命名匹配结果 它不会更改 is_same，也不会启用 call_order 输出

图表生成与模板

diagrams_generate 会根据源代码声明返回类图草稿 如果可选编译器可用，还可以包含有证据支持的 TypeScript 继承和实现关系 如果不支持，则会返回基于声明的输出，并明确说明关系 不可用 它不会执行完整的类型解析 diagrams_generate_sequence 会返回静态调用流程草稿 它会报告未解析的被调用方，而不是虚构参与者 从版本 0.10.0 开始，即使另一个文件声明了同名调用方，每个发送方仍与包含调用位置的文件保持关联 被调用方查找仍使用第一个不区分大小写的声明参与者 从版本 0.11.0 开始，ambiguous_callees 会标识扫描范围内由多个不同参与者声明的已输出操作名称 同名文件会先合并，再进行此项检查，且选定目标保持稳定 此列表会在两项输出上限应用后，按首次输出顺序保留精确拼写 延迟调用、未解析调用以及因上限而被丢弃的调用均不会计入 callee_evidence 列表会按首次输出顺序，说明每个不同已输出被调用方的声明匹配情况 每个条目都会报告 selected_participant 和 candidate_participants，以及 candidates_available、candidates_capped 和设为 20 的 candidate_limit 候选名称是逻辑文件基名，尚未转换为 Mermaid 标识符 候选项包含输出参与者上限以外的已扫描参与者 resolution_basis 为 case-insensitive-declaration 这些诊断提供声明依据，但不会解析运行时接收方 回调中的调用会被保守地视为延迟调用，并从有序消息中排除 此策略并不表示所有回调都会异步执行 include_call_parentheses 只会更改消息标签 版本 0.11.0 还会在使用回退调用读取器时，保留与函数声明位于同一行的真实递归调用 声明本身仍会从消息列表中排除 已赋值箭头表达式中的同名调用遵循现有的延迟调用规则，并计入 deferred_count，而非消息

diagrams_template 会以 puml 或 mermaid 格式生成 class、sequence 或 c4_context 起始源文本 它接受 1 到 20 个不重复的 ASCII 标识符名称，每个名称最多 60 个字符；标题为可选项，且不得为空白，最多 200 个字符

对于项目模板，请将 template 设为 custom，并提供一个 custom_template 标识符 定义文件是项目根目录下名为 diagrams-templates（前面带点）的隐藏目录中的 JSON 文件 每个文件名均由标识符后接 JSON 扩展名组成 标识符仅接受 ASCII 字母、数字、下划线和连字符，长度为 1 到 64 个字符

定义支持可选的 puml 和 mermaid 部分 每个提供的部分都必须包含 source 和 entity 字符串 支持的占位符为 {{title}}、{{entities}} 和 {{name}} 扩展仅执行一遍，不会执行代码 定义必须是常规文件，不能是符号链接 读取上限为 65536 字节，扩展后的源文本上限为 1000000 个 UTF-16 代码单元

diagrams_list_templates 会发现内置类型和自定义文件名候选项，但不会读取自定义定义文件的内容 发现过程最多检查 1000 个目录项，外加一个前瞻目录项 diagrams_template 实例化自定义定义时会验证其内容 发现过程不会创建缺失的模板目录

渲染和共享

diagrams_render 会通过配置的渲染器返回 SVG 或 PNG diagrams_export 会返回独立的 HTML 文档，但不会持久化导出目标 这两种操作共用上述渲染器选择策略

HTML 导出会将 SVG 嵌入为 base64 图像，而非内联 SVG 标记 这会将图像与周围文档隔离，但并非 SVG 清理器 渲染图像中的文本不可选择 严格的内容安全策略会限制包装文档

include_source 默认为 true，并会在可折叠部分中嵌入转义后的源文本 将其设为 false 会完全省略源文本部分 最终 HTML 文档必须不超过 5000000 个 UTF-8 字节 超出大小的导出会失败，而不会返回部分文档 diagrams_save_export 会通过显式的 output_path，在 diagrams 根目录下保存相同的 HTML 包 目标路径必须使用 HTML 扩展名，且文件必须尚不存在 大小检查会在创建输出目录或输出文件之前执行 响应包含确认信息和元数据，而非 HTML 已保存的 HTML 文件不会成为清单或 CRUD 工具中的图表

从图表生成代码框架

diagrams_scaffold 返回供审阅的源代码 language 选项默认为 typescript 从版本 zero eleven zero 起，javascript 会选择空的导出类框架 JavaScript 使用相同的安全名称筛选规则，以及源代码和实体数量限制 在读取之前，它会拒绝 include_members、include_types 和 include_relations JavaScript 不会输出任何成员签名、字段类型或关系 它会读取一个已存储的图表，但不会保存或执行建议的代码 默认输出由根据启发式名称候选项生成的空导出类组成 无效名称和保留名称会被跳过并报告 候选项为空时会生成空源代码

include_members 启用一个有限解析器，用于解析普通的顶层多行类 代码块 它会将字段输出为 unknown，并将方法输出为抛出异常的存根 不会还原参数或实现行为

include_types 会隐式启用 include_members 它仅保留 string、number、boolean、bigint，或与已输出类名完全一致且可带一个数组后缀的类型 从版本 zero ten zero 起，此模式还接受类型任一侧恰好有一个 null 分支，并输出类型后接 | null 例如，标记为 string | null 的字段在草稿中会保留为可空类型 同一模式还接受标记为 Array<T> 和 ReadonlyArray<T> 的字段 T 必须是受支持的基本类型或已输出的类名 第一种形式会输出 T[]，第二种形式会输出 readonly T[] 两种形式都可带一个 null 分支，且都不接受嵌套数组或其他泛型 从版本 zero eleven zero 起，字面形式的 readonly T[] 标记使用相同的基础规则，readonly 后必须恰好有一个空格，并可带一个 null 分支 readonly 标量和嵌套 readonly 数组仍不受支持 包装类型和可空类型标记必须使用冒号字段表示法，且长度不超过 82 个字符 分隔符周围的空白也计入该限制 其他联合类型和裸 null 仍不受支持 不受支持的字段标记仍会输出为 unknown 已接受的字段会使用确定赋值断言，但不提供运行时值

include_relations 会隐式启用前两种模式 它接受显式声明且会输出的普通类之间带标签的 --> 关联 角色标签会成为建议字段 受支持的目标多重性可能会生成数组字段 现有代码块成员优先于关系字段，已接受的名称会保留首次出现的项 结果不会还原所有权或强制执行基数

代码框架默认最多包含 30 个类，最多允许 60 个 每个类最多接受 30 个已输出成员 关系模式下，整个结果最多追加 300 个关系字段 元数据会区分被跳过的候选项与因上限而遗漏的项 读取已存储文件后，超过 1000000 个 UTF-8 字节的源代码会被拒绝 此上限限制的是已处理输入，而非读取原始文件所需的内存

操作限制与故障恢复

一致性扫描和代码生成扫描最多检查 5000 个源文件 目录遍历会跳过隐藏目录和已知的依赖目录及构建目录，例如 node_modules、dist、build、out 和 target 只会收集具有已识别代码扩展名的文件 被排除文件中的未匹配名称不属于扫描结果 超过 1000000 字节的文件会被跳过 扫描器将并发文件读取数限制为 32 一致性证据对每个实体最多保留 10 个匹配文件引用，同时报告完整匹配数 类生成默认生成 30 个实体，上限为 60 个 最多输出 60 个关系，并省略端点超出上限的边 序列生成默认包含 8 个参与者和 20 条消息 其上限为 20 个参与者和 50 条消息 在将任何结果视为完整结果之前，请检查 truncated、scan_warning 和工具特定的上限元数据

本地渲染器命令的默认超时时间为 20000 毫秒 捕获的渲染器流每个上限为 1000000 个字符 从版本 0.9.0 起，本地 SVG 和 PNG 图像文件在进行 base64 编码或 HTML 打包之前， 大小上限为 5000000 字节 超出大小上限的图像文件将被拒绝，临时渲染目录也会被移除 请拆分或简化图表后重试 远程 PlantUML 请求同样有 20000 毫秒的超时时间和 5000000 字节的响应上限 从版本 0.9.0 起，超时时间涵盖响应头和完整的响应正文下载， 字节上限会在解码后的数据块到达时执行 超出大小上限或下载失败时，下载会停止，未使用的 HTTP 错误响应正文 会被丢弃 这些限制并不会让外部渲染器变成应用程序沙盒

工具执行失败时，isError 会设置为 true 处理程序运行前就可能发生架构拒绝 找不到图表时，应重新检查清单 如果创建目标已存在，应使用新路径或有意更新该目标 如果导出目标已存在，应使用其他输出路径，或在导出工具之外明确移除该目标 找不到渲染器时，应安装该命令，并检查启动 MCP 客户端的环境中的 PATH 扫描结果达到上限时，应缩小范围后再得出结论

存储和范围服务会拒绝超出其配置根目录的路径，并在文件系统边界处 检查符号链接 服务器仍以其进程的操作系统权限运行 请将图表源和外部渲染器配置视为适合该执行环境的可信输入

源代码组织与开发

src 目录包含运行时源代码和同目录测试 src 下的 tools 目录为每个工具提供一个适配器 src 下的 services 目录包含存储、分析、渲染、 导出和脚手架模块 src 下的 setup 目录负责客户端配置工作流 src 下的 integration 目录用于测试 MCP 传输契约

scripts 目录负责清理构建和发现编译后的测试 dist 目录是生成的构建输出 docs 目录包含详细的架构文档和项目交接记录 架构文档介绍模块职责和请求路径 路线图文档记录已完成的里程碑和未来候选事项 发布检查清单记录软件包验证和发布步骤 CONTRIBUTING 描述贡献工作流 RELEASE_NOTES 记录版本变更 清理交接和后续功能文档保留历史背景， 阅读时应结合其中记录的范围和日期

要在当前源代码检出版本上进行开发，请在仓库根目录中按顺序运行以下命令：

npm ci
npm run lint
npm run format:check
npm run build
npm test

测试从编译后的输出运行，因此请先进行构建再运行测试 构建会在编译前移除过时的输出 对于本地 MCP 客户端，请将 node 配置为服务命令，并将 dist 下已编译的 index JavaScript 文件 的绝对路径作为其参数 将 PROJECT_ROOT 设置为此本地服务应分析的代码库 此本地入口使用当前源代码检出版本 否则，已发布的安装命令会通过 npx 安装已发布的软件包，以生成服务入口 在检出目录中运行 npm ci 也会安装用于编译器支持分析的 TypeScript 开发编译器 已发布的安装通常使用备用提取器 仅在被分析的项目中安装 TypeScript，并不能保证服务包能够解析它

持续集成会在测试套件运行前执行 lint 和格式检查、构建以及入口点帮助检查 通过受控依赖覆盖渲染器行为，无需在测试作业中全局安装渲染器或进行网络渲染 仍需在目标运行时环境中验证外部渲染器的安装

扩展项目时，应明确指定工具架构和响应元数据 将可复用行为放在所属服务中，并在每个新的存储边界保留文件系统范围检查 通过有针对性的测试覆盖可观察行为，并在同一变更中更新相关工程文档

LICENSE

根据 MIT 许可证发布 完整条款请参阅 LICENSE