mermaid-mcp-server

Instructions

Implementation Reference

• index.ts:509-642 (handler)

  Main execution logic for the 'generate' tool. Processes arguments, renders the Mermaid diagram using renderMermaid, handles PNG/SVG output, optional file saving, and constructs the response content.

  async function processGenerateRequest(args: {
    code: string;
    theme?: "default" | "forest" | "dark" | "neutral";
    backgroundColor?: string;
    outputFormat?: "png" | "svg";
    name?: string;
    folder?: string;
  }): Promise<{
    content: Array<
      | { type: "text"; text: string }
      | { type: "image"; data: string; mimeType: string }
    >;
    isError: boolean;
  }> {
    try {
      const outputFormat = args.outputFormat || "png";
      const result = await renderMermaid(args.code, {
        theme: args.theme,
        backgroundColor: args.backgroundColor,
        outputFormat: outputFormat,
      });
  
      // Check if we need to save the file to a folder
      if (!CONTENT_IMAGE_SUPPORTED) {
        if (!args.folder) {
          throw new Error(
            "Folder parameter is required when CONTENT_IMAGE_SUPPORTED is false"
          );
        }
  
        // Save the file based on format
        let fullPath: string;
        if (outputFormat === "svg") {
          if (!result.svg) {
            throw new Error("SVG content not available");
          }
          fullPath = await saveMermaidSvgToFile(
            result.svg,
            args.name!,
            args.folder!
          );
        } else {
          fullPath = await saveMermaidImageToFile(
            result.data,
            args.name!,
            args.folder!
          );
        }
  
        return {
          content: [
            {
              type: "text",
              text: `${outputFormat.toUpperCase()} saved to: ${fullPath}`,
            },
          ],
          isError: false,
        };
      }
  
      // If folder is provided and CONTENT_IMAGE_SUPPORTED is true, save the file to the folder
      // but also return the content in the response
      let savedMessage = "";
      if (args.folder && args.name) {
        try {
          let fullPath: string;
          if (outputFormat === "svg") {
            if (!result.svg) {
              throw new Error("SVG content not available");
            }
            fullPath = await saveMermaidSvgToFile(
              result.svg,
              args.name,
              args.folder
            );
          } else {
            fullPath = await saveMermaidImageToFile(
              result.data,
              args.name,
              args.folder
            );
          }
          savedMessage = `${outputFormat.toUpperCase()} also saved to: ${fullPath}`;
          log(LogLevel.INFO, savedMessage);
        } catch (saveError) {
          log(
            LogLevel.ERROR,
            `Failed to save ${outputFormat} to folder: ${(saveError as Error).message}`
          );
          savedMessage = `Note: Failed to save ${outputFormat} to folder: ${
            (saveError as Error).message
          }`;
        }
      }
  
      // Return the appropriate content based on format
      if (outputFormat === "svg") {
        if (!result.svg) {
          throw new Error("SVG content not available");
        }
        return {
          content: [
            {
              type: "text",
              text: savedMessage
                ? `Here is the generated SVG:\n\n${result.svg}\n\n${savedMessage}`
                : `Here is the generated SVG:\n\n${result.svg}`,
            },
          ],
          isError: false,
        };
      } else {
        // Return the PNG image in the response
        return {
          content: [
            {
              type: "text",
              text: savedMessage
                ? `Here is the generated image. ${savedMessage}`
                : "Here is the generated image",
            },
            {
              type: "image",
              data: result.data,
              mimeType: "image/png",
            },
          ],
          isError: false,
        };
      }
    } catch (error) {
      return handleMermaidError(error);
    }
  }

• index.ts:193-397 (helper)

  Core rendering function that uses Puppeteer and Mermaid.js to generate PNG base64 or SVG from Mermaid markdown code.

  async function renderMermaid(
    code: string,
    config: {
      theme?: "default" | "forest" | "dark" | "neutral";
      backgroundColor?: string;
      outputFormat?: "png" | "svg";
    } = {}
  ): Promise<{ data: string; svg?: string }> {
    log(LogLevel.INFO, "Launching Puppeteer");
    log(LogLevel.DEBUG, `Rendering with config: ${JSON.stringify(config)}`);
  
    // Resolve the path to the local mermaid.js file
    const distPath = path.dirname(
      url.fileURLToPath(resolve("mermaid", import.meta.url))
    );
    const mermaidPath = path.resolve(distPath, "mermaid.min.js");
    log(LogLevel.DEBUG, `Using Mermaid from: ${mermaidPath}`);
  
    const browser = await puppeteer.launch({
      headless: true,
      // Use the bundled browser instead of looking for Chrome on the system
      executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || undefined,
      args: ["--no-sandbox", "--disable-setuid-sandbox"],
    });
  
    // Declare page outside try block so it's accessible in catch and finally
    let page: puppeteer.Page | null = null;
    // Store console messages for error reporting
    const consoleMessages: string[] = [];
  
    try {
      page = await browser.newPage();
      log(LogLevel.DEBUG, "Browser page created");
  
      // Capture browser console messages for better error reporting
      page.on("console", (msg) => {
        const text = msg.text();
        consoleMessages.push(text);
        log(LogLevel.DEBUG, text);
      });
  
      // Create a simple HTML template without the CDN reference
      const htmlContent = `
      <!DOCTYPE html>
      <html>
      <head>
        <title>Mermaid Renderer</title>
        <style>
          body { 
            background: ${config.backgroundColor || "white"};
            margin: 0;
            padding: 0;
          }
          #container {
            padding: 0;
            margin: 0;
          }
        </style>
      </head>
      <body>
        <div id="container"></div>
      </body>
      </html>
      `;
      // Note: Must be set before page.goto() to ensure the page renders with the correct dimensions from the start
      await page.setViewport({
        width: 1200, // Keep the same viewport size as before
        height: 800,
        deviceScaleFactor: 3, // 2~4 is fine, the larger the PNG, the clearer and larger it is
      });
  
      // Write the HTML to a temporary file
      const tempHtmlPath = path.join(__dirname, "temp-mermaid.html");
      fs.writeFileSync(tempHtmlPath, htmlContent);
  
      log(LogLevel.INFO, `Rendering mermaid code: ${code.substring(0, 50)}...`);
      log(LogLevel.DEBUG, `Full mermaid code: ${code}`);
  
      // Navigate to the HTML file
      await page.goto(`file://${tempHtmlPath}`);
      log(LogLevel.DEBUG, "Navigated to HTML template");
  
      // Add the mermaid script to the page
      await page.addScriptTag({ path: mermaidPath });
      log(LogLevel.DEBUG, "Added Mermaid script to page");
  
      // Render the mermaid diagram using a more robust approach similar to the CLI
      log(LogLevel.DEBUG, "Starting Mermaid rendering in browser");
      const screenshot = await page.$eval(
        "#container",
        async (container, mermaidCode, mermaidConfig) => {
          try {
            // @ts-ignore - mermaid is loaded by the script tag
            window.mermaid.initialize({
              startOnLoad: false,
              theme: mermaidConfig.theme || "default",
              securityLevel: "loose",
              logLevel: 5,
            });
  
            // This will throw an error if the mermaid syntax is invalid
            // @ts-ignore - mermaid is loaded by the script tag
            const { svg: svgText } = await window.mermaid.render(
              "mermaid-svg",
              mermaidCode,
              container
            );
            container.innerHTML = svgText;
  
            const svg = container.querySelector("svg");
            if (!svg) {
              throw new Error("SVG element not found after rendering");
            }
  
            // Apply any necessary styling to the SVG
            svg.style.backgroundColor = mermaidConfig.backgroundColor || "white";
  
            // Return the dimensions for screenshot
            const rect = svg.getBoundingClientRect();
            return {
              width: Math.ceil(rect.width),
              height: Math.ceil(rect.height),
              success: true,
            };
          } catch (error) {
            // Return the error to be handled outside
            return {
              success: false,
              error: error instanceof Error ? error.message : String(error),
            };
          }
        },
        code,
        { theme: config.theme, backgroundColor: config.backgroundColor }
      );
  
      // Check if rendering was successful
      if (!screenshot.success) {
        log(
          LogLevel.ERROR,
          `Mermaid rendering failed in browser: ${screenshot.error}`
        );
        throw new Error(`Mermaid rendering failed: ${screenshot.error}`);
      }
  
      log(LogLevel.DEBUG, "Mermaid rendered successfully in browser");
  
      // Get the SVG content if needed
      let svgContent: string | undefined;
      if (config.outputFormat === "svg") {
        svgContent = await page.$eval("#container svg", (svg) => {
          return svg.outerHTML;
        });
        log(LogLevel.DEBUG, "SVG content extracted");
      }
  
      // Take a screenshot of the SVG for PNG output
      let base64Image = "";
      if (config.outputFormat === "png" || config.outputFormat === undefined) {
        const svgElement = await page.$("#container svg");
        if (!svgElement) {
          log(LogLevel.ERROR, "SVG element not found after successful rendering");
          throw new Error("SVG element not found");
        }
  
        log(LogLevel.DEBUG, "Taking screenshot of SVG");
        // Take a screenshot with the correct dimensions
        base64Image = await svgElement.screenshot({
          omitBackground: false,
          type: "png",
          encoding: "base64",
        });
      }
  
      // Clean up the temporary file
      fs.unlinkSync(tempHtmlPath);
      log(LogLevel.DEBUG, "Temporary HTML file cleaned up");
  
      log(LogLevel.INFO, "Mermaid rendered successfully");
  
      return { data: base64Image, svg: svgContent };
    } catch (error) {
      log(
        LogLevel.ERROR,
        `Error in renderMermaid: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
      log(
        LogLevel.ERROR,
        `Error stack: ${error instanceof Error ? error.stack : "No stack trace"}`
      );
  
      // Include console messages in the error for better debugging
      if (page && page.isClosed() === false) {
        log(LogLevel.ERROR, "Browser console messages:");
        consoleMessages.forEach((msg) => log(LogLevel.ERROR, `  ${msg}`));
      }
  
      throw error;
    } finally {
      await browser.close();
      log(LogLevel.DEBUG, "Puppeteer browser closed");
    }
  }

• index.ts:113-153 (schema)

  Tool definition including name, description, and detailed input schema with parameters for code, theme, colors, format, and optional file saving.

  const GENERATE_TOOL: Tool = {
    name: "generate",
    description: "Generate PNG image or SVG from mermaid markdown",
    inputSchema: {
      type: "object",
      properties: {
        code: {
          type: "string",
          description: "The mermaid markdown to generate an image from",
        },
        theme: {
          type: "string",
          enum: ["default", "forest", "dark", "neutral"],
          description: "Theme for the diagram (optional)",
        },
        backgroundColor: {
          type: "string",
          description:
            "Background color for the diagram, e.g. 'white', 'transparent', '#F0F0F0' (optional)",
        },
        outputFormat: {
          type: "string",
          enum: ["png", "svg"],
          description: "Output format for the diagram (optional, defaults to 'png')",
        },
        name: {
          type: "string",
          description: CONTENT_IMAGE_SUPPORTED
            ? "Name of the diagram (optional)"
            : "Name for the generated file (required)",
        },
        folder: {
          type: "string",
          description: CONTENT_IMAGE_SUPPORTED
            ? "Absolute path to save the image to (optional)"
            : "Absolute path to save the image to (required)",
        },
      },
      required: CONTENT_IMAGE_SUPPORTED ? ["code"] : ["code", "name", "folder"],
    },
  };

• index.ts:645-647 (registration)

  Registers the 'generate' tool in the MCP listTools handler by returning it in the tools array.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [GENERATE_TOOL],
  }));

• index.ts:663-671 (handler)

  Dispatch logic in the MCP callTool handler that validates arguments and invokes processGenerateRequest for the 'generate' tool.

  if (name === "generate") {
    log(LogLevel.INFO, "Rendering Mermaid PNG");
    if (!isGenerateArgs(args)) {
      throw new Error("Invalid arguments for generate");
    }
  
    // Process the generate request
    return await processGenerateRequest(args);
  }