@volare-consulting/mermaid-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volare Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# mermaid-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that renders [Mermaid](https://mermaid.js.org)
+diagram markup to **PNG** images, using [`@mermaid-js/mermaid-cli`](https://github.com/mermaid-js/mermaid-cli)
+(Puppeteer/Chromium) under the hood.
+
+Give it AI-generated Mermaid — flowcharts, sequence, class, ER, gantt, state diagrams — and get
+back a rendered image, returned inline so the host can preview it and/or written to a file on disk.
+
+## Tool
+
+### `render_mermaid`
+
+| Parameter         | Type     | Required | Description |
+| ----------------- | -------- | -------- | ----------- |
+| `diagram`         | string   | yes      | Mermaid diagram source, e.g. `graph TD; A-->B;` |
+| `outputPath`      | string   | no       | Absolute path ending in `.png` to also save the image to. Omit to only return inline. |
+| `theme`           | enum     | no       | `default` \| `dark` \| `forest` \| `neutral` (default `default`) |
+| `backgroundColor` | string   | no       | e.g. `white`, `transparent`, `#ffffff` (default `white`) |
+| `width`           | number   | no       | Output width in pixels |
+| `height`          | number   | no       | Output height in pixels |
+| `scale`           | number   | no       | Device scale factor; higher = sharper/larger PNG (default `1`) |
+
+Returns a short text summary plus the PNG as inline MCP `image` content. When `outputPath` is
+supplied, the file is written there and the path is included in the summary.
+
+## Install & build
+
+```bash
+npm install
+npx puppeteer browsers install chrome   # download the headless Chromium used for rendering
+npm run build
+```
+
+Rendering runs a headless Chromium via Puppeteer. If `npm install` doesn't fetch it automatically,
+run `npx puppeteer browsers install chrome` (as above). It lands in Puppeteer's cache
+(`~/.cache/puppeteer` / `%USERPROFILE%\.cache\puppeteer`). On Windows, if extraction stalls, delete
+the partial `chrome/win64-*` folder and re-run the install.
+
+## Test
+
+```bash
+npm test
+```
+
+Integration tests using Node's built-in test runner (`node:test`). They exercise the renderer
+(input validation, inline render, render-to-file) and a full MCP stdio round-trip (spawn the server,
+list tools, call `render_mermaid`). The render tests launch headless Chromium, so they need the
+Chromium install above and take a few seconds each.
+
+## Configure in an MCP client
+
+After `npm run build`, point your MCP client at the built entry over stdio.
+
+### Claude Code
+
+```bash
+# From a local build:
+claude mcp add mermaid -- node /absolute/path/to/mermaid-mcp/dist/index.js
+
+# Or from the published package:
+claude mcp add mermaid -- npx -y @volare-consulting/mermaid-mcp
+```
+
+### Claude Desktop / generic `mcpServers` config
+
+```json
+{
+  "mcpServers": {
+    "mermaid": {
+      "command": "node",
+      "args": ["/absolute/path/to/mermaid-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+npm run dev     # run the server from TypeScript source via tsx
+```
+
+## Releasing
+
+Published to the public npm registry as
+[`@volare-consulting/mermaid-mcp`](https://www.npmjs.com/package/@volare-consulting/mermaid-mcp)
+via a tag-driven GitHub Actions release (`.github/workflows/publish.yml`), which calls the org's
+shared `publish-npm-public` reusable workflow.
+
+1. Bump `version` in `package.json` on a PR and merge to `main`.
+2. Tag the merge commit and push the tag:
+
+   ```bash
+   git tag v0.1.0 && git push origin v0.1.0
+   ```
+
+The tag **must** equal the `package.json` version or the job fails. Pushing a `v*` tag builds and
+publishes the package (tests are skipped — they need headless Chromium the publish runner doesn't
+provide). Authentication uses the org-level `NPM_TOKEN` secret.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { renderMermaidToPng } from "./render.js";
+const server = new McpServer({
+    name: "mermaid-mcp",
+    version: "0.1.0",
+});
+server.registerTool("render_mermaid", {
+    title: "Render Mermaid diagram to PNG",
+    description: "Render Mermaid diagram markup to a PNG image. Returns the image inline so it " +
+        "can be previewed. If `outputPath` (an absolute .png path) is provided, the PNG " +
+        "is also saved there and the path is returned. Useful for turning AI-generated " +
+        "Mermaid (flowcharts, sequence, class, ER, gantt, state diagrams, etc.) into images.",
+    inputSchema: {
+        diagram: z
+            .string()
+            .min(1)
+            .describe("Mermaid diagram source, e.g. `graph TD; A-->B;`"),
+        outputPath: z
+            .string()
+            .optional()
+            .describe("Absolute path ending in .png to save the image to. Omit to only return the image inline."),
+        theme: z
+            .enum(["default", "dark", "forest", "neutral"])
+            .optional()
+            .describe("Mermaid theme. Defaults to \"default\"."),
+        backgroundColor: z
+            .string()
+            .optional()
+            .describe('Background color, e.g. "white", "transparent", "#ffffff". Defaults to "white".'),
+        width: z.number().int().positive().optional().describe("Output width in pixels."),
+        height: z.number().int().positive().optional().describe("Output height in pixels."),
+        scale: z
+            .number()
+            .positive()
+            .optional()
+            .describe("Device scale factor; higher = sharper/larger PNG. Defaults to 1."),
+    },
+}, async (args) => {
+    try {
+        const result = await renderMermaidToPng(args);
+        const base64 = result.bytes.toString("base64");
+        const summary = result.isTemp
+            ? `Rendered Mermaid diagram inline (PNG, ${result.bytes.length} bytes).`
+            : `Rendered Mermaid diagram to ${result.path} (PNG, ${result.bytes.length} bytes).`;
+        return {
+            content: [
+                { type: "text", text: summary },
+                { type: "image", data: base64, mimeType: "image/png" },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to render Mermaid diagram: ${message}`,
+                },
+            ],
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("mermaid-mcp server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in mermaid-mcp:", error);
+    process.exit(1);
+});

package/dist/render.js

@@ -0,0 +1,56 @@
+import { mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, isAbsolute } from "node:path";
+import { run as mmdcRun } from "@mermaid-js/mermaid-cli";
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+/**
+ * Render a Mermaid diagram to a PNG using @mermaid-js/mermaid-cli (Puppeteer/Chromium).
+ *
+ * The mermaid-cli programmatic API works off files, so the source is written to a
+ * temporary `.mmd` file and the PNG is produced either at `outputPath` or in a temp dir.
+ */
+export async function renderMermaidToPng(opts) {
+    const diagram = opts.diagram?.trim();
+    if (!diagram) {
+        throw new Error("`diagram` is empty — provide Mermaid markup to render.");
+    }
+    if (opts.outputPath && !isAbsolute(opts.outputPath)) {
+        throw new Error(`outputPath must be an absolute path, got: ${opts.outputPath}`);
+    }
+    if (opts.outputPath && !opts.outputPath.toLowerCase().endsWith(".png")) {
+        throw new Error(`outputPath must end in .png, got: ${opts.outputPath}`);
+    }
+    const workDir = await mkdtemp(join(tmpdir(), "mermaid-mcp-"));
+    const inputPath = join(workDir, "diagram.mmd");
+    const isTemp = !opts.outputPath;
+    const outputPath = opts.outputPath ?? join(workDir, "diagram.png");
+    await writeFile(inputPath, diagram, "utf8");
+    try {
+        await mmdcRun(inputPath, outputPath, {
+            quiet: true,
+            puppeteerConfig: { args: ["--no-sandbox", "--disable-setuid-sandbox"] },
+            parseMMDOptions: {
+                backgroundColor: opts.backgroundColor ?? "white",
+                mermaidConfig: { theme: opts.theme ?? "default" },
+                viewport: opts.width || opts.height || opts.scale
+                    ? {
+                        width: opts.width ?? 800,
+                        height: opts.height ?? 600,
+                        deviceScaleFactor: opts.scale ?? 1,
+                    }
+                    : undefined,
+            },
+        });
+        const bytes = await readFile(outputPath);
+        if (!bytes.subarray(0, 4).equals(PNG_MAGIC)) {
+            throw new Error("Render produced a file that is not a valid PNG.");
+        }
+        return { path: outputPath, bytes, isTemp };
+    }
+    finally {
+        // Clean up the scratch dir (the temp .mmd input, and the temp PNG when one was
+        // used — its bytes are already in memory). A user-supplied outputPath lives
+        // outside workDir and is left untouched.
+        await rm(workDir, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@volare-consulting/mermaid-mcp",
+  "version": "0.1.0",
+  "description": "MCP server that renders Mermaid diagrams to PNG via @mermaid-js/mermaid-cli",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mermaid-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/volare-consulting-software/mermaid-mcp.git"
+  },
+  "keywords": [
+    "mermaid",
+    "diagram",
+    "png",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "mermaid-cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "node --import tsx --test test/render.test.ts test/mcp.test.ts"
+  },
+  "dependencies": {
+    "@mermaid-js/mermaid-cli": "^11.4.2",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "@types/node": "^22.9.0"
+  }
+}