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.

• GitHub Pages documentation
• npm package vaults-diagram-tools@0.1.4
• GitHub Actions Marketplace Action Vaults Diagram Tools (repo)
• MCP Registry io.github.Malnati/vaults-diagram-tools
• Smithery server
• GitHub release v0.1.4
• Quay.io Podman image quay.io/ricardomalnati/vaults-diagram-tools:v0.1.0
• GitHub App
• Brand assets
• Homebrewery package page

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:

npm install -D vaults-diagram-tools

Render one Mermaid source to durable assets:

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

Generate Mermaid diagrams from source code:

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

Run the MCP stdio server:

npx vaults-diagram-mcp

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

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

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:

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:

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:

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:

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:

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:

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:

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:

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.

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: