fix: propagate mermaid-cli stderr in rendering errors (#83)

* fix: propagate mermaid-cli stderr in rendering errors

When mermaid-cli fails, execFileAsync throws with `.stderr` containing
the actual parse error details (e.g., "Parse error on line 3..."), but
only the generic `error.message` ("Command failed: npx ...") was
surfaced to the MCP response. This made it impossible for Claude to
self-correct Mermaid syntax errors.

Extract stderr from the caught error and include it in the thrown Error
message so that detailed diagnostics reach the MCP client.

* fix: improve catch handler, add tests, fix formatting

---------

Co-authored-by: Vitalii Elenhaupt <velenhaupt@gmail.com>

Author: aodecipher

src/handlers.ts

@@ -74,10 +74,13 @@ export async function renderDiagram(options: RenderOptions, liveFilePath: string
     await copyFile(outputFile, liveFilePath);
     mcpLogger.info(`Diagram rendered successfully: ${previewId}`);
   } catch (error) {
-    mcpLogger.error(`Diagram rendering failed: ${previewId}`, {
-      error: error instanceof Error ? error.message : String(error),
-    });
-    throw error;
+    const stderr =
+      error instanceof Error && "stderr" in error && (error as Error & { stderr: string }).stderr
+        ? `\n${(error as Error & { stderr: string }).stderr}`
+        : "";
+    const message = error instanceof Error ? error.message : String(error);
+    mcpLogger.error(`Diagram rendering failed: ${previewId}`, { error: message });
+    throw new Error(`${message}${stderr}`);
   }
 }
 

test/handlers.test.ts

@@ -3,6 +3,7 @@ import { handleMermaidPreview, handleMermaidSave } from "../src/handlers.js";
 import { getPreviewDir, getDiagramFilePath } from "../src/file-utils.js";
 import { mkdir, readdir, unlink, access, mkdtemp } from "fs/promises";
 import { join } from "path";
+import { execFile } from "child_process";
 import { tmpdir } from "os";
 
 // Mock execFile to avoid actually running mmdc and create fake output files
@@ -172,6 +173,52 @@ describe("handleMermaidPreview", () => {
 
     expect(result.content[0].text).toContain("Live preview is only available for SVG");
   });
+
+  it("should include stderr details in error when rendering fails", async () => {
+    const mockExecFile = vi.mocked(execFile);
+    const originalImpl = mockExecFile.getMockImplementation()!;
+
+    try {
+      mockExecFile.mockImplementation((_file: string, _args: any, callback: any) => {
+        const error: any = new Error("Command failed: npx mmdc");
+        error.stderr = "Parse error on line 3: invalid syntax near 'graph'";
+        callback(error, { stdout: "", stderr: error.stderr });
+      });
+
+      const result = await handleMermaidPreview({
+        diagram: "invalid diagram syntax",
+        preview_id: testPreviewId,
+      });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("Parse error on line 3");
+      expect(result.content[0].text).toContain("Command failed");
+    } finally {
+      mockExecFile.mockImplementation(originalImpl);
+    }
+  });
+
+  it("should show original error message when stderr is empty", async () => {
+    const mockExecFile = vi.mocked(execFile);
+    const originalImpl = mockExecFile.getMockImplementation()!;
+
+    try {
+      mockExecFile.mockImplementation((_file: string, _args: any, callback: any) => {
+        const error = new Error("Command failed: npx mmdc");
+        callback(error, { stdout: "", stderr: "" });
+      });
+
+      const result = await handleMermaidPreview({
+        diagram: "invalid diagram syntax",
+        preview_id: testPreviewId,
+      });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("Command failed");
+    } finally {
+      mockExecFile.mockImplementation(originalImpl);
+    }
+  });
 });
 
 describe("handleMermaidSave", () => {