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.