io.github.CloudCorpRecords/diagramport

diagramport

diagramport generates Mermaid diagrams and charts from Mermaid syntax. Give it a diagram — graph TD; A-->B; and friends — and it hands back the form you asked for: the syntax itself, a shareable mermaid.ink link, or a rendered image produced by a renderer command you configure on your own machine.

Everything except rendering is local logic that always works: the syntax is validated before anything else happens, and the share links are built from the diagram text without any network call.

Install

npx @reneturcios/diagramport generate --mermaid "graph TD; A-->B;" --output-type mermaid

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/diagramport

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

# Validate syntax only (exit 1 with the reason when invalid)
diagramport validate --mermaid "graph TD; A-->B; A-->C; B-->D; C-->D;"

# Return the validated syntax
diagramport generate --mermaid "graph TD; A-->B;" --output-type mermaid

# Build a shareable mermaid.ink link (SVG or PNG)
diagramport generate --mermaid "graph TD; A-->B;" --output-type svg_url
diagramport generate --mermaid "graph TD; A-->B;" --output-type png_url

# Render an image (needs DIAGRAMPORT_RENDERER_COMMAND, see below)
diagramport generate --mermaid "graph TD; A-->B;" --output-type base64
diagramport generate --mermaid "graph TD; A-->B;" --output-type file

diagramport --version

Exit codes: 0 on success, 1 when the syntax is invalid or rendering fails (the error names the problem), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/diagramport mcp

MCP client configuration:

{
  "mcpServers": {
    "diagramport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/diagramport", "mcp"]
    }
  }
}

Tools

Validation

Syntax is checked locally before any output is produced. The first non-empty line must start with a known diagram type (graph, flowchart, sequenceDiagram, classDiagram, stateDiagram, stateDiagram-v2, erDiagram, journey, userJourney, gantt, pie, gitGraph, mindmap, timeline, quadrantChart, requirementDiagram, C4Context), and quotes and brackets must be balanced (brackets inside a double-quoted label do not count). Invalid syntax is reported as an error naming the reason — it is never passed on to a renderer or a link builder. This is a structural sanity check, not a full Mermaid parse.

Share links

For svg_url and png_url, diagramport builds the link locally: the payload is the base64url encoding of the UTF-8 diagram text, appended to https://mermaid.ink/svg/ (SVG) or https://mermaid.ink/img/ (PNG). Anyone opening the link gets the diagram rendered by mermaid.ink; diagramport itself makes no network call to build it.

Rendering

diagramport bundles no renderer — rendering a diagram to an image needs a Mermaid engine and, typically, a headless browser, which are deliberately left to the operator. The base64, svg, and file output types render through a local command named by the DIAGRAMPORT_RENDERER_COMMAND environment variable. The command receives the diagram text on stdin and must write the rendered image bytes to stdout:

export DIAGRAMPORT_RENDERER_COMMAND="my-mermaid-renderer --format png"
diagramport generate --mermaid "graph TD; A-->B;" --output-type base64

With no renderer configured, those output types return an error naming DIAGRAMPORT_RENDERER_COMMAND. Image bytes are never invented or stubbed. file output is written under DIAGRAMPORT_OUTPUT_DIR when set, otherwise ./diagrams/, with a timestamped .png file name.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, fake renderer only
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.