Vaults Diagram Tools

Name: Vaults Diagram Tools
Author: Malnati

本地服务

malnati.github.io开发工具025 周前更新

代码仓库访问官网

关于 Vaults Diagram Tools

Vaults Diagram Tools 是用于渲染 Mermaid 资源并根据源代码结构生成图表的工具包。它面向开发团队和 Agent，支持命令行工作流、多个分发方式，以及提供三种图表工具的 MCP 服务。

主要功能

01将 Mermaid 文件渲染为 SVG 和 JPEG
02根据源代码生成 Mermaid 图表
03生成清单及可选的附属输出
04通过命令行、容器或 GitHub Actions 运行
05提供 VS Code 扩展和离线资源

适用场景

01为 Markdown 文档生成可链接的图表资源
02用生成的图表审查源代码结构
03在 GitHub Actions 中自动渲染图表
04让 Agent 通过 MCP 渲染图表

MCP 相关

stdio MCP 服务向 MCP 客户端提供 `render_mermaid_text`、`render_mermaid_file` 和 `generate_source_diagrams`。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "malnati-vaults-diagram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "vaults-diagram-tools"
      ]
    }
  }
}

启动命令npx -y vaults-diagram-tools

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmvaults-diagram-tools0.1.4stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
png	boolean	否
ascii	boolean	否
theme	string	否
source	string	是
fileName	string	否
asciiMode	enum	否	unicode \| ascii
outputDir	string	否
background	string	否

详细介绍

vaults-diagram-tools

将 Mermaid 转换为资源文件。将源代码转换为图表。为 Agent 提供 MCP。

vaults-diagram-tools 是一套独立工具包，适用于需要可复现的 Mermaid SVG/JPEG 资源文件、源代码图表和便于 Agent 使用的图表工作流，且无需包含 Vault 专属内容的团队。

包含内容

从 Vaults 工具链中提取的 Mermaid 渲染器。
源代码到 Mermaid 图表的生成器。
MCP stdio 服务，提供三个明确的工具，并已在 MCP Registry 发布，名称为 io.github.Malnati/vaults-diagram-tools。
支持离线使用的发布资源文件，可用于 zip 和容器分发。
专用的 GitHub Actions Marketplace 封装仓库，用于渲染、源代码和策略自动化。
Homebrew、deb/rpm、CDN、Docker 和 Podman 的打包模板，以及可发布的 VS Code 扩展包。

图表生成之外的内容管理工作流不属于此软件包。

快速开始

在项目中安装：

npm install -D vaults-diagram-tools

将一个 Mermaid 源文件渲染为持久化资源文件：

npx vaults-mermaid-render path/to/diagram.mmd --output-dir out --manifest out/manifest.json

从源代码生成 Mermaid 图表：

npx vaults-source-diagrams --source-dir src --output-dir diagrams

运行 MCP stdio 服务：

npx vaults-diagram-mcp

如果项目不应保留依赖项，可使用一次性 npx：

npx --yes --package vaults-diagram-tools vaults-mermaid-render path/to/diagram.mmd --output-dir out
npx --yes --package vaults-diagram-tools vaults-source-diagrams --source-dir src --output-dir diagrams
npx --yes --package vaults-diagram-tools vaults-diagram-mcp

核心工具

命令	用途
`vaults-mermaid-render`	将 `.mmd` 或 `.mermaid` 文件渲染为 SVG/JPEG、清单，以及可选的 PNG/文本辅助文件。
`vaults-source-diagrams`	根据源代码结构生成 Mermaid 图表，包括针对特定内容的选择和可追溯性元数据。
`vaults-diagram-mcp`	通过 MCP stdio 提供 `render_mermaid_text`、`render_mermaid_file` 和 `generate_source_diagrams`。

其他软件包二进制文件是兼容性入口，适用于较旧的 Vaults 路径、可选的文本渲染器和 Podman 工作流。

工作流

Markdown 文档： 将 Mermaid 源文件作为链接的 .mmd 文件保留，渲染为 .svg 和 .jpg，并使用围栏代码块 mermaid 内联展示源代码。
源代码图审查： 根据真实源代码路径生成图表，并检查清单中的选择数据，确认请求的文件、被省略的连接器和渲染输出。
Agent 自动化： 当客户端需要通过精简且明确的工具接口渲染图表时，使用 MCP 服务。当前注册表条目已启用，版本为 0.1.4，Smithery 服务页面也已发布。
发布打包： 发布 npm、zip、容器和离线供应商制品，同时保留许可证和声明文件。

下载与分发

npm 注册表

如需使用常规 Node.js 工具链安装，请使用已发布的 npm 包。当前 npm 最新版本为 [email protected]：

npm install -D vaults-diagram-tools
npx vaults-mermaid-render path/to/diagram.mmd --output-dir out --manifest out/manifest.json
npx vaults-source-diagrams --source-dir src --output-dir diagrams
npx vaults-diagram-mcp

使用 `npx` 一次性运行

如果项目不应保留此依赖，请使用 --package：

npx --yes --package vaults-diagram-tools vaults-mermaid-render path/to/diagram.mmd --output-dir out
npx --yes --package vaults-diagram-tools vaults-source-diagrams --source-dir src --output-dir diagrams
npx --yes --package vaults-diagram-tools vaults-diagram-mcp

GitHub Actions Marketplace

如果图表工作流需要在 GitHub Actions 中运行，且不添加项目本地脚本，请使用专用的 Marketplace 操作：

steps:
  - uses: actions/checkout@v4
  - name: Render Mermaid assets
    id: diagrams
    uses: Malnati/vaults-diagram-tools-action@v0
    with:
      mode: render
      input: docs/diagrams
      output-dir: diagram-assets
  - name: Upload diagram assets
    uses: actions/upload-artifact@v4
    with:
      name: diagram-assets
      path: ${{ steps.diagrams.outputs.output-dir }}

GitHub Actions Marketplace 列表
操作仓库
首次发布的操作版本：v0.1.4；持续更新的兼容性标签：v0。

来自 GitHub 的 npm 包

在注册表发布前测试某次提交时，请使用 GitHub 包源：

npm install github:malnati/vaults-diagram-tools
npx vaults-mermaid-render path/to/diagram.mmd --output-dir out

GitHub 发布资源

最新的 GitHub Release、GHCR 镜像、npm 包、MCP Registry 元数据和 VS Code VSIX 均已发布至 v0.1.4；Quay.io Podman 镜像仍为 v0.1.0：

vaults-diagram-tools-0.1.4.tgz
vaults-diagram-tools-0.1.4.zip
vaults-diagram-tools-vscode-0.1.4.vsix
ghcr.io/malnati/vaults-diagram-tools:v0.1.4
quay.io/ricardomalnati/vaults-diagram-tools:v0.1.0

本地检出

开发、验证或准备发布时，请使用检出版本：

git clone https://github.com/malnati/vaults-diagram-tools.git
cd vaults-diagram-tools
npm ci
npm test
node packages/renderer/render-mermaid-assets.mjs examples/simple/flowchart.mmd --output-dir tmp/rendered
node packages/source-diagrams/source-diagrams.mjs --source-dir packages/mcp --output-dir tmp/source-diagrams
node packages/mcp/server.mjs

容器、Docker 和 Podman

本地构建：

docker build -f containers/Containerfile -t vaults-diagram-tools:local .
podman build -f containers/Containerfile -t vaults-diagram-tools:local .

使用 GHCR 镜像运行渲染：

docker run --rm \
  -v "$PWD/examples/simple:/work/input:ro" \
  -v "$PWD/tmp/container-output:/work/output:rw" \
  ghcr.io/malnati/vaults-diagram-tools:v0.1.4 \
  --output-dir /work/output /work/input/flowchart.mmd

运行已在 Quay.io 发布的 Podman 镜像：

podman run --rm \
  -v "$PWD/examples/simple:/work/input:ro" \
  -v "$PWD/tmp/container-output:/work/output:rw" \
  quay.io/ricardomalnati/vaults-diagram-tools:v0.1.0 \
  --output-dir /work/output /work/input/flowchart.mmd

Quay.io 还为同一已发布的软件包系列提供 0.1.0 和 latest 标签。

Podman 辅助脚本可通过 vaults-mermaid-podman-build、vaults-mermaid-podman-render 和 vaults-mermaid-podman-test 使用。

CDN 门面

此软件包以 CLI 为主。CDN 端点仅提供可在浏览器安全使用的元数据和辅助工具；SVG/JPEG 渲染仍通过 Node.js、MCP 或容器运行时执行。

https://cdn.jsdelivr.net/npm/vaults-diagram-tools/packaging/cdn/vaults-diagram-tools.mjs
https://unpkg.com/vaults-diagram-tools/packaging/cdn/vaults-diagram-tools.mjs

VS Code 扩展

桌面版 VS Code 扩展以 malnati.vaults-diagram-tools 发布，也可以直接从 GitHub Release 获取 VSIX 并安装。它采用混合运行时：内置离线回退方案，以及可跟随 vaults-diagram-tools@latest 更新、无需重新发布扩展的托管缓存。它提供：

用于 Mermaid SVG/JPEG 渲染、源代码图表生成和 Markdown 图表策略验证的命令面板操作。
运行时命令：立即更新托管运行时、显示运行时状态，以及强制使用内置运行时。
面向已解析的 vaults-diagram-tools stdio 服务的原生 VS Code MCP 服务定义提供程序。
用于从已通过身份验证的本地 Shell 手动发布的 Marketplace/Open VSX 发布脚本。请将 npm、VS Code Marketplace 和 Open VSX 凭据保留在本地终端；GitHub Actions 不会使用这些密钥。

v0.1.4 发布后，可通过以下方式安装：

本地软件包验证：

npm run vscode:install
npm run vscode:test
npm run vscode:package
code --install-extension dist/vaults-diagram-tools-vscode-0.1.4.vsix

按顺序在本地发布：

make auth
make publish-all

make publish-all 会先进行本地终端身份验证，验证仅用于防护的发布元数据，打包制品，创建 GitHub 标签/Release，发布到 npm、VS Code Marketplace、Open VSX、GHCR、Quay.io 和 MCP Registry，随后验证公开可用性。如果当前版本/标签/npm 软件包已存在，该命令就会失败；运行前请更新并提交发布元数据。

命令行用法

从 npm 安装后，可直接通过 node_modules/.bin、npm exec 或 npx 运行公开 CLI：

vaults-mermaid-render path/to/diagram.mmd --output-dir out --png --ascii --manifest out/manifest.json
vaults-source-diagrams --source-dir src --output-dir diagrams --langs auto --diagrams dependency,class
vaults-diagram-mcp

单次运行示例：

npx --yes --package vaults-diagram-tools vaults-mermaid-render examples/simple/flowchart.mmd --output-dir tmp/vaults-diagram-tools
npx --yes --package vaults-diagram-tools vaults-source-diagrams --source-dir packages/mcp --output-dir tmp/source-diagrams --render-mode placeholder
npx --yes --package vaults-diagram-tools vaults-diagram-mcp

本地检出版本的等效用法：

node packages/renderer/render-mermaid-assets.mjs examples/simple/flowchart.mmd --output-dir tmp/vaults-diagram-tools
node packages/source-diagrams/source-diagrams.mjs --source-dir packages/mcp --output-dir tmp/source-diagrams
node packages/mcp/server.mjs

MCP 工具

vaults-diagram-mcp 正好提供三个工具：

render_mermaid_text
render_mermaid_file
generate_source_diagrams

客户端命令示例：

vaults-diagram-mcp

MCP 适配器会将主题和渲染选项传递给与 CLI 相同的渲染器，因此客户端可以请求 theme: "dracula"，并获取 .svg + .jpg 制品。

Dracula 图表示例

以下图表由此仓库通过 vaults-mermaid-render --theme dracula 生成；Markdown 链接到生成的资源，而不是嵌入 SVG/JPEG。

安装和使用流程

链接：Mermaid 源文件 / SVG / JPEG

flowchart LR
  Install["Install"] --> Npm["npm registry"]
  Install --> Npx["npx one-shot"]
  Install --> GitHub["GitHub npm"]
  Install --> Local["Local checkout"]
  Install --> Container["Docker Podman GHCR Quay.io"]

  Npm --> Cli["Public CLIs"]
  Npx --> Cli
  GitHub --> Cli
  Local --> Cli
  Container --> Cli

  Cli --> Render["vaults-mermaid-render"]
  Cli --> Source["vaults-source-diagrams"]
  Cli --> Mcp["vaults-diagram-mcp"]

  Render --> Svg["SVG Dracula"]
  Render --> Jpg["JPEG Dracula"]
  Source --> Mermaid["Mermaid source"]
  Source --> Svg
  Mcp --> Tools["3 explicit MCP tools"]

工具架构

链接：Mermaid 源文件 / SVG / JPEG

flowchart TB
  User["User or agent"] --> Markdown["Markdown docs"]
  User --> Cli["CLI workflow"]
  User --> McpClient["MCP client"]

  Cli --> Renderer["vaults-mermaid-render"]
  Cli --> SourceDiagrams["vaults-source-diagrams"]
  McpClient --> McpServer["vaults-diagram-mcp"]
  McpServer --> Renderer
  McpServer --> SourceDiagrams

  SourceDiagrams --> SourceTree["Source tree"]
  SourceDiagrams --> GeneratedMmd["Generated .mmd"]
  GeneratedMmd --> Renderer

  Renderer --> Svg[".svg"]
  Renderer --> Jpeg[".jpg"]
  Renderer --> Manifest["manifest.json"]

  Svg --> Markdown
  Jpeg --> Markdown
  GeneratedMmd --> Markdown

MCP 软件包源代码关系图

链接：生成的索引 / Mermaid 源文件 / SVG / JPEG

flowchart LR
  N1["server.mjs"]
  N2["tests/mcp-tools.test.mjs"]
  N3["tools.mjs"]
  N1 --> N3
  N2 --> N3

品牌资源

仓库、GitHub Pages 落地页、Actions 摘要、发布说明、GitHub App 徽章和社交预览均使用根据当前落地页视觉风格生成的一套确定性品牌素材。

使用以下命令重新生成并验证素材：

npm run brand:generate
npm run brand:check

合规与制品政策

Markdown 图表政策

生成的 Markdown 应链接到制品，并在 mermaid 围栏代码块中展示源代码：

#### Diagram title
- Links: [Mermaid source](docs/assets/diagrams/install-usage-flow.mmd) / [SVG](docs/assets/diagrams/install-usage-flow.svg) / [JPEG](docs/assets/diagrams/install-usage-flow.jpg)

```mermaid
flowchart TD
  A["Source"] --> B["Rendered assets"]
```

SVG 和 JPEG 文件是交付制品。默认情况下，Markdown 应链接到这些文件，而不是将它们嵌入为图片。

署名与许可证合规

项目许可证：MIT。
项目声明：NOTICE.md。
第三方署名与许可证索引：THIRD_PARTY_NOTICES.md。
许可证验证：npm run license:check；使用 npm run license:generate 刷新生成的声明。
Dracula 配色的文档图表通过 beautiful-mermaid 致谢采用 MIT 许可证的 Dracula Theme 调色板。
图标数据的来源包括 Font Awesome 4、Gil Barbara 的 SVG Logos，以及通过 Iconify JSON 软件包提供的 Lucide Icons。
发布制品必须保留 LICENSE、NOTICE.md、THIRD_PARTY_NOTICES.md，以及打包的依赖项或离线供应商运行时中包含的上游许可证文件。

离线供应商运行时

源代码树不会提交 node_modules。构建和发布作业会创建离线供应商资源：

npm run vendor:refresh
npm run test:vendor:offline

开发期间，渲染器可以通过常规 npm 依赖项运行，也可以在 MMDC_VENDOR_ONLY=1 时通过 packages/renderer/vendor/node 运行。

默认渲染器使用 Node/JS/WASM 供应商路径，无需 Chromium、Puppeteer、mmdc、ImageMagick 或 npx。只有在明确指定 MMDC_RENDER_ENGINE=mmdc 时，旧版 Shell 包装器才会使用 mmdc；自动回退到 Puppeteer 的功能已禁用。

GitHub App

公开的 vaults-diagram-tools GitHub App 是此软件包可安装的只读应用入口。

安装 URL：https://github.com/apps/vaults-diagram-tools/installations/new
用途：提供只读安装，用于验证此仓库的标签、发布制品和软件包元数据。
权限：只读访问仓库内容，以及访问 GitHub 元数据。
Webhook：已禁用；此版本不会运行 Webhook 后端。
GitHub Actions Marketplace：Vaults Diagram Tools 是专用 Malnati/vaults-diagram-tools-action 包装器仓库在 Marketplace 上的目标。
密钥：此仓库不存储私钥、客户端密钥或 Webhook 密钥。

分发状态

v1 已可用：

发布 npm 软件包并提供 GitHub 安装流程
通过 GHCR 和 Quay.io 提供 Docker/Podman 镜像
MCP 服务
MCP Registry 条目 io.github.Malnati/vaults-diagram-tools，当前版本为 0.1.4
ricardomalnati/vaults-diagram-tools 的 Smithery 服务页面
zip 发布包
GitHub Actions CI、发布、CodeQL 和 Pages 工作流
GitHub Actions Marketplace Action Vaults Diagram Tools，用于渲染、源代码和政策自动化
公开的只读 GitHub App 安装入口
支持搜索标签的 Homebrewery 软件包页面
可发布的 VS Code 扩展软件包，支持 VS Code Marketplace 和 Open VSX 工作流目标

v1 中的模板：

Homebrew formula
通过 nfpm 打包的 deb/rpm
通过 npm/jsDelivr/unpkg 提供的 CDN 门面

当前版本

vaults-diagram-tools 已作为 npm 0.1.4 和 MCP Registry 服务 io.github.Malnati/vaults-diagram-tools 版本 0.1.4 发布。最新的 GitHub Release、GHCR 镜像和 VS Code VSIX 均为 v0.1.4；Quay.io 上的 Podman 镜像系列为 v0.1.0。

渠道	状态
GitHub Release	`v0.1.4`
Release 资源	`vaults-diagram-tools-0.1.4.tgz`、`vaults-diagram-tools-0.1.4.zip` 和 `vaults-diagram-tools-vscode-0.1.4.vsix`
npm	`[email protected]`，dist-tag `latest`
GitHub Actions Marketplace	`Vaults Diagram Tools` 目标，由 `Malnati/vaults-diagram-tools-action` 标签 `v0.1.4` 和 `v0` 支持
MCP Registry	`io.github.Malnati/vaults-diagram-tools`，状态为 `active`，版本为 `0.1.4`
Smithery	`ricardomalnati/vaults-diagram-tools` 已发布
Registry PR	PR #17 统一了 MCP Registry 发布者名称，现已合并。
GHCR 容器	`ghcr.io/malnati/vaults-diagram-tools:v0.1.4`；未来的容器发布将在 GitHub Actions 之外手动进行。
Quay.io Podman 镜像	`quay.io/ricardomalnati/vaults-diagram-tools:v0.1.0`
自动化	CI、CodeQL、Pages 和 Release 工作流通过 GitHub Actions 运行；Release 仅验证并打包构件。npm、VS Code Marketplace、Open VSX、容器注册表和 MCP Registry 均通过本地终端手动发布。
GitHub App	`vaults-diagram-tools` 公开的只读应用；安装。
VS Code 扩展	VSIX 已附加到 GitHub Release。Marketplace 目标 `malnati.vaults-diagram-tools` 和 Open VSX 目标 `malnati/vaults-diagram-tools` 均在 GitHub Actions 之外手动发布。
文档	GitHub Pages 发布 `docs/` 站点。

文档

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。