io.github.Malnati/vaults-diagram-tools

Official

by Malnati · JavaScript

Vaults Diagram Tools

Mermaid to assets. Source code to maps. MCP for agents.

Convert source code and diagrams to visual assets using Mermaid.

Topics

diagramsdockergithub-actionsjpegmcpmermaidnodejspodmansource-code-analysissvgmcp-serveroffline-assetsbrand-assetsdiagram-tools

README.md23 KBView on GitHub

vaults-diagram-tools

Mermaid to assets. Source code to maps. MCP for agents.

vaults-diagram-tools is a standalone toolkit for teams that need reproducible Mermaid SVG/JPEG assets, source-code diagrams, and agent-friendly diagram workflows without carrying Vault-specific content.

What is included

Mermaid renderer extracted from the Vaults toolchain.
Source-code to Mermaid diagram generator.
MCP stdio server with three explicit tools, published in MCP Registry as io.github.Malnati/vaults-diagram-tools.
Offline-capable release assets for zip and container distribution.
Dedicated GitHub Actions Marketplace wrapper repository for render/source/policy automation.
Packaging templates for Homebrew, deb/rpm, CDN, Docker, and Podman, plus a publishable VS Code extension package.

Content-management workflows outside diagram generation are not part of this package.

Quick start

Install in a project:

bash

npm install -D vaults-diagram-tools

Render one Mermaid source to durable assets:

bash

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

Generate Mermaid diagrams from source code:

bash

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

Run the MCP stdio server:

bash

npx vaults-diagram-mcp

Use one-shot npx when the project should not keep a dependency:

bash

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

Core tools

Command	Purpose
`vaults-mermaid-render`	Render `.mmd` or `.mermaid` files to SVG/JPEG, manifests, and optional PNG/text sidecars.
`vaults-source-diagrams`	Generate Mermaid diagrams from source-code structure, including focused selections and traceability metadata.
`vaults-diagram-mcp`	Expose `render_mermaid_text`, `render_mermaid_file`, and `generate_source_diagrams` through MCP stdio.

Additional package binaries are compatibility entrypoints for older Vaults paths, optional text renderers, and Podman workflows.

Workflows

Markdown docs: keep the Mermaid source as a linked .mmd, render .svg and .jpg, and show source inline with a fenced mermaid block.
Source graph reviews: generate diagrams from real source paths and inspect manifest selection data for requested files, omitted connectors, and rendered outputs.
Agent automation: use the MCP server when clients need diagram rendering through a narrow, explicit tool surface. Current registry entry is active at version 0.1.4, and the Smithery server page is already published.
Release packaging: ship npm, zip, container, and offline vendor artifacts while preserving license and notice files.

Download and distribution

npm registry

Use the published npm package when you want the normal Node.js toolchain installation. Current npm latest is vaults-diagram-tools@0.1.4:

bash

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

One-shot with `npx`

Use --package when the project should not keep the dependency:

bash

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

Use the dedicated Marketplace action when the diagram workflow should run inside GitHub Actions without adding project-local scripts:

yaml

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 listing
Action repository
Initial action release: v0.1.4; moving compatibility tag: v0.

npm package from GitHub

Use the GitHub package source when testing a commit before a registry release:

bash

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

GitHub release assets

The latest GitHub Release, GHCR image, npm package, MCP Registry metadata, and VS Code VSIX are published at v0.1.4; the Quay.io Podman image remains at 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

Local checkout

Use the checkout for development, validation, or release preparation:

bash

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

Container, Docker, and Podman

Build locally:

bash

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

Run a render from the GHCR image:

bash

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

Run the published Podman image from Quay.io:

bash

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 also exposes 0.1.0 and latest tags for the same published package line.

Podman helper scripts are available through vaults-mermaid-podman-build, vaults-mermaid-podman-render, and vaults-mermaid-podman-test.

CDN facade

The package is CLI-first. CDN endpoints expose browser-safe metadata/helpers only; SVG/JPEG rendering still runs through Node.js, MCP, or the container runtime.

text

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 extension

The desktop VS Code extension is published as malnati.vaults-diagram-tools and can also be installed directly from the GitHub Release VSIX. It uses a hybrid runtime: a bundled offline fallback plus a managed cache that can follow vaults-diagram-tools@latest without republishing the extension. It contributes:

Command Palette actions for Mermaid SVG/JPEG rendering, source-diagram generation, and Markdown diagram-policy validation.
Runtime commands: update managed runtime now, show runtime status, and force the bundled runtime.
A native VS Code MCP server definition provider for the resolved vaults-diagram-tools stdio server.
Marketplace/Open VSX publish scripts for manual publication from an authenticated local shell. Keep npm, VS Code Marketplace, and Open VSX credentials in the local terminal; GitHub Actions does not use those secrets.

Install options after v0.1.4 is released:

Local package validation:

bash

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

Sequential local publication:

bash

make auth
make publish-all

make publish-all runs local-terminal authentication first, validates guard-only release metadata, packages artifacts, creates the GitHub tag/release, publishes npm, VS Code Marketplace, Open VSX, GHCR, Quay.io, and MCP Registry, then verifies public availability. It fails when the current version/tag/npm package already exists; bump and commit release metadata before running.

Command line usage

After installing from npm, run public CLIs directly from node_modules/.bin, npm exec, or npx:

bash

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

One-shot examples:

bash

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

Local checkout equivalents:

bash

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 tools

vaults-diagram-mcp exposes exactly three tools:

render_mermaid_text
render_mermaid_file
generate_source_diagrams

Example client command:

bash

vaults-diagram-mcp

The MCP adapter passes theme and rendering options through to the same renderer used by the CLI, so a client can request theme: "dracula" and receive .svg + .jpg artifacts.

Dracula diagram examples

The diagrams below were generated by this repository with vaults-mermaid-render --theme dracula; Markdown links the generated assets instead of embedding SVG/JPEG.

Install and usage flow

Links: Mermaid source / SVG / JPEG

mermaid

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"]

Tooling architecture

Links: Mermaid source / SVG / JPEG

mermaid

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 package source graph

Links: Generated index / Mermaid source / SVG / JPEG

mermaid

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

Brand assets

The repository, GitHub Pages landing, Actions summaries, release notes, GitHub App badge, and social preview use one deterministic brand kit generated from the current landing visual language.

Regenerate and verify the kit with:

bash

npm run brand:generate
npm run brand:check

Compliance and artifact policy

Markdown diagram policy

Generated Markdown should link artifacts and show source in a mermaid fenced block:

markdown

#### 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 and JPEG files are delivery artifacts. Markdown should link them instead of embedding them as images by default.

Credits and license compliance

Project license: MIT.
Project notices: NOTICE.md.
Third-party credits and license index: THIRD_PARTY_NOTICES.md.
License verification: npm run license:check; refresh generated notices with npm run license:generate.
Dracula-colored documentation diagrams credit the MIT-licensed Dracula Theme palette through beautiful-mermaid.
Icon data credits include Font Awesome 4, SVG Logos by Gil Barbara, and Lucide Icons via Iconify JSON packages.
Release artifacts must preserve LICENSE, NOTICE.md, THIRD_PARTY_NOTICES.md, and upstream license files bundled by packaged dependencies or the offline vendor runtime.

Offline vendor runtime

The source tree does not commit node_modules. Build and release jobs create offline vendor assets with:

bash

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

The renderer can run from normal npm dependencies during development, or from packages/renderer/vendor/node when MMDC_VENDOR_ONLY=1.

The default renderer is the Node/JS/WASM vendor path and does not require Chromium, Puppeteer, mmdc, ImageMagick, or npx. The legacy shell wrapper only uses mmdc when explicitly requested with MMDC_RENDER_ENGINE=mmdc; automatic fallback to Puppeteer is disabled.

GitHub App

The public vaults-diagram-tools GitHub App is the installable read-only app surface for this package.

Install URL: https://github.com/apps/vaults-diagram-tools/installations/new
Purpose: read-only installs for validating tags, release assets, and package metadata around this repository.
Permissions: repository contents read-only, plus GitHub metadata access.
Webhooks: disabled; this release does not run a webhook backend.
GitHub Actions Marketplace: Vaults Diagram Tools is the Marketplace target for the dedicated Malnati/vaults-diagram-tools-action wrapper repository.
Secrets: no private key, client secret, or webhook secret is stored in this repository.

Distribution status

Working in v1:

npm package publication and GitHub install flow
Docker/Podman images through GHCR and Quay.io
MCP server
MCP Registry entry io.github.Malnati/vaults-diagram-tools active at version 0.1.4
Smithery server page for ricardomalnati/vaults-diagram-tools
zip release
GitHub Actions CI, release, CodeQL, and Pages workflows
GitHub Actions Marketplace Action Vaults Diagram Tools for render/source/policy automation
Public read-only GitHub App install surface
Homebrewery package page with searchable tags
Publishable VS Code extension package with VS Code Marketplace and Open VSX workflow targets

Templates in v1:

Homebrew formula
deb/rpm through nfpm
CDN facade through npm/jsDelivr/unpkg

Current release

vaults-diagram-tools is published as npm 0.1.4 and MCP Registry server io.github.Malnati/vaults-diagram-tools version 0.1.4. The latest GitHub Release, GHCR image, and VS Code VSIX are v0.1.4; Quay.io carries the Podman image line at v0.1.0.

Channel	Status
GitHub Release	`v0.1.4`
Release assets	`vaults-diagram-tools-0.1.4.tgz`, `vaults-diagram-tools-0.1.4.zip`, and `vaults-diagram-tools-vscode-0.1.4.vsix`
npm	`vaults-diagram-tools@0.1.4`, dist-tag `latest`
GitHub Actions Marketplace	`Vaults Diagram Tools` target, backed by `Malnati/vaults-diagram-tools-action` tags `v0.1.4` and `v0`
MCP Registry	`io.github.Malnati/vaults-diagram-tools`, status `active`, version `0.1.4`
Smithery	`ricardomalnati/vaults-diagram-tools` is published
Registry PR	PR #17 aligned the MCP Registry publisher name and was merged.
GHCR container	`ghcr.io/malnati/vaults-diagram-tools:v0.1.4`; future container publication is manual outside GitHub Actions.
Quay.io Podman image	`quay.io/ricardomalnati/vaults-diagram-tools:v0.1.0`
Automation	CI, CodeQL, Pages, and Release workflows run through GitHub Actions; release validates and packages artifacts only. npm, VS Code Marketplace, Open VSX, container registries, and MCP Registry are published manually from a local terminal.
GitHub App	`vaults-diagram-tools` public read-only app; install.
VS Code extension	VSIX is attached to the GitHub Release. Marketplace target `malnati.vaults-diagram-tools` and Open VSX target `malnati/vaults-diagram-tools` are published manually outside GitHub Actions.
Documentation	GitHub Pages publishes the `docs/` site.

Documentation

Install

claude_desktop_config.json

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

Topics

vaults-diagram-tools

What is included

Quick start

Core tools

Workflows

Download and distribution

npm registry

One-shot with npx

GitHub Actions Marketplace

npm package from GitHub

GitHub release assets

Local checkout

Container, Docker, and Podman

CDN facade

VS Code extension

Command line usage

MCP tools

Dracula diagram examples

Install and usage flow

Tooling architecture

MCP package source graph

Brand assets

Compliance and artifact policy

Markdown diagram policy

Credits and license compliance

Offline vendor runtime

GitHub App

Distribution status

Current release

Documentation

Install

One-shot with `npx`