vaults-diagram-tools

Portable Mermaid and source-code diagram toolkit for SVG/JPEG rendering, offline assets, and MCP workflows.

What is included

• Mermaid renderer extracted from the Vaults toolchain.

• Source-code to Mermaid diagram generator.

• MCP stdio server with three explicit tools.

• Offline-capable release assets for zip and container distribution.

• Packaging templates for Homebrew, deb/rpm, VS Code, CDN, Docker, and Podman.

Not included: OCR/document conversion, Claro vault audits, CPQ import, clippings, or Casa Conectada PDF tooling.

Install

npm package from GitHub

npm install github:malnati/vaults-diagram-tools

Local checkout

git clone https://github.com/malnati/vaults-diagram-tools.git
cd vaults-diagram-tools
npm ci
npm test

Container

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

Release images are published to GitHub Container Registry as ghcr.io/malnati/vaults-diagram-tools.

Command line usage

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

Local checkout equivalents:

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/source-diagrams/tests/fixtures/js-project --output-dir /tmp/source-diagrams
node packages/mcp/server.mjs

Supported public CLIs are the three commands above. Additional package binaries are compatibility entrypoints for older Vaults paths and may be deprecated in a future major release.

MCP tools

vaults-diagram-mcp exposes exactly three tools:

• render_mermaid_text

• render_mermaid_file

• generate_source_diagrams

Markdown diagram policy

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

#### Diagram title
- Links: [Mermaid source](assets/diagram.mmd) / [SVG](assets/diagram.svg) / [JPEG](assets/diagram.jpg)

```mermaid
flowchart TD
  A --> B
```

SVG and JPEG files are delivery artifacts. Markdown should link them instead of embedding them as images by default.

Offline vendor runtime

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

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.

Distribution status

Working in v1:

• npm package metadata and GitHub install flow

• Docker/Podman image

• MCP server

• zip release

• GitHub Actions CI, release, CodeQL, and Pages workflows

Templates in v1:

• Homebrew formula

• deb/rpm through nfpm

• VS Code extension shell

• CDN facade through npm/jsDelivr/unpkg once npm publication is enabled

Documentation

• GitHub Pages documentation

• Vaults compatibility notes

• Contributing guide

• Security policy