@volare-consulting/mermaid-mcp 0.1.0 → 0.2.0

package/README.md

@@ -28,14 +28,24 @@ supplied, the file is written there and the path is included in the summary.
 
 ```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.
+## Browser requirement
+
+Mermaid renders inside a real browser (it needs a DOM for layout), so **Google Chrome / Chromium is
+required**. Puppeteer resolves it, in this order:
+
+1. **`PUPPETEER_EXECUTABLE_PATH`** — an explicit Chrome/Chromium binary you point it at.
+2. **Puppeteer's bundled Chromium** — downloaded by `@mermaid-js/mermaid-cli` during `npm install`.
+3. **A system-installed Google Chrome** — used as a fallback (`channel: "chrome"`) if the bundled
+   browser can't be launched.
+
+If none can be launched, the tool returns an actionable error: install Chrome, run
+`npx puppeteer browsers install chrome`, or set `PUPPETEER_EXECUTABLE_PATH`.
+
+> If Puppeteer's automatic Chromium download is blocked (a locked-down network, or — on some Windows
+> machines — a stalled extraction), just install Google Chrome and the renderer falls back to it.
 
 ## Test
 

package/dist/render.js

@@ -3,11 +3,37 @@ 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]);
+// Substrings that mean "Puppeteer couldn't find or launch a browser" (as opposed
+// to a genuine diagram/syntax error, which we must not silently retry).
+const BROWSER_LAUNCH_HINTS = [
+    "could not find",
+    "failed to launch",
+    "browser was not found",
+    "executable doesn't exist",
+    "no usable sandbox",
+    "spawn",
+    "enoent",
+];
+function isBrowserLaunchError(err) {
+    const message = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return BROWSER_LAUNCH_HINTS.some((hint) => message.includes(hint));
+}
+function browserSetupError(original) {
+    const detail = original instanceof Error ? original.message : String(original);
+    return new Error("Could not launch Chrome to render the diagram. Fix any one of:\n" +
+        "  - Install Google Chrome, or run: npx puppeteer browsers install chrome\n" +
+        "  - Or set PUPPETEER_EXECUTABLE_PATH to a Chrome/Chromium binary.\n" +
+        `Original error: ${detail}`);
+}
 /**
  * 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.
+ *
+ * Puppeteer resolves the browser: the first attempt uses `PUPPETEER_EXECUTABLE_PATH`
+ * (if set) or Puppeteer's bundled Chromium; if that can't launch, it falls back to a
+ * system-installed Google Chrome (`channel: "chrome"`). No hardcoded paths.
  */
 export async function renderMermaidToPng(opts) {
     const diagram = opts.diagram?.trim();
@@ -25,22 +51,45 @@ export async function renderMermaidToPng(opts) {
     const isTemp = !opts.outputPath;
     const outputPath = opts.outputPath ?? join(workDir, "diagram.png");
     await writeFile(inputPath, diagram, "utf8");
+    const 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 baseArgs = ["--no-sandbox", "--disable-setuid-sandbox"];
+    // Browser sources tried in order, all resolved by Puppeteer itself.
+    const puppeteerConfigs = [
+        { args: baseArgs }, // PUPPETEER_EXECUTABLE_PATH or Puppeteer's bundled Chromium
+        { args: baseArgs, channel: "chrome" }, // system-installed Google Chrome
+    ];
     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,
-            },
-        });
+        let launchError;
+        let rendered = false;
+        for (const puppeteerConfig of puppeteerConfigs) {
+            try {
+                await mmdcRun(inputPath, outputPath, {
+                    quiet: true,
+                    puppeteerConfig,
+                    parseMMDOptions,
+                });
+                rendered = true;
+                break;
+            }
+            catch (err) {
+                if (!isBrowserLaunchError(err))
+                    throw err; // genuine render/syntax error
+                launchError = err; // browser source unavailable — try the next one
+            }
+        }
+        if (!rendered) {
+            throw browserSetupError(launchError);
+        }
         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.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volare-consulting/mermaid-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server that renders Mermaid diagrams to PNG via @mermaid-js/mermaid-cli",
   "license": "MIT",
   "type": "module",