generate_mermaid_diagram

Instructions

Implementation Reference

• src/server.ts:44-170 (handler)

  The tool handler registered on the MCP server. It receives requests for 'generate_mermaid_diagram', validates with zod schema, calls renderMermaid() to generate the diagram, and handles all output types (base64, svg, mermaid, file, svg_url, png_url).

  function setupToolHandlers(server: McpServer): void {
    server.server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: [tool],
    }));
  
    server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      if (request.params.name === tool.name) {
        try {
          const args = request.params.arguments || {};
          // Use safeParse instead of parse and try-catch.
          const result = schema.safeParse(args);
          if (!result.success) {
            throw new McpError(
              ErrorCode.InvalidParams,
              `Invalid parameters: ${result.error.message}`,
            );
          }
  
          const { mermaid, theme, backgroundColor, outputType = "base64" } = args;
          Logger.info(
            `Rendering diagram (outputType=${outputType}, theme=${theme ?? "default"})`,
          );
          const { id, svg, screenshot } = await withRetry(
            () =>
              renderMermaid(
                mermaid as string,
                theme as string,
                backgroundColor as string,
              ),
            { maxAttempts: 3, delayMs: 500 },
          );
  
          if (outputType === "mermaid") {
            return {
              content: [
                {
                  type: "text",
                  text: mermaid,
                },
              ],
            };
          }
          if (outputType === "svg") {
            return {
              content: [
                {
                  type: "text",
                  text: svg,
                },
              ],
            };
          }
          if (outputType === "svg_url" || outputType === "png_url") {
            const variant = outputType === "svg_url" ? "svg" : "img";
            const url = createMermaidInkUrl(
              mermaid as string,
              variant,
              (theme as string) || "default",
            );
            return {
              content: [
                {
                  type: "text",
                  text: url,
                },
              ],
            };
          }
          if (outputType === "file") {
            if (!screenshot) {
              throw new McpError(
                ErrorCode.InternalError,
                "Failed to generate screenshot for file output.",
              );
            }
  
            // Create a unique filename with timestamp and random suffix
            const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
            const randomSuffix = Math.random().toString(36).substring(2, 8);
            const filename = `mermaid-${timestamp}-${randomSuffix}.png`;
  
            // Use current working directory to save the file
            const filePath = path.resolve(process.cwd(), filename);
  
            try {
              fs.writeFileSync(filePath, screenshot);
              return {
                content: [
                  {
                    type: "text",
                    text: `Mermaid diagram saved to file: ${filePath}`,
                  },
                ],
              };
            } catch (fileError) {
              throw new McpError(
                ErrorCode.InternalError,
                `Failed to save file: ${fileError instanceof Error ? fileError.message : "Unknown file error"}`,
              );
            }
          }
          return {
            content: [
              {
                type: "image",
                data: screenshot?.toString("base64"),
                mimeType: "image/png",
              },
            ],
          };
          // biome-ignore lint/suspicious/noExplicitAny: <explanation>
        } catch (error: any) {
          Logger.error("Tool execution failed", error);
          if (error instanceof McpError) throw error;
          throw new McpError(
            ErrorCode.InternalError,
            `Failed to generate mermaid: ${error?.message || "Unknown error."}`,
          );
        }
      } else {
        throw new McpError(
          ErrorCode.MethodNotFound,
          `Unknown tool: ${request.params.name}.`,
        );
      }
    });
  }

• src/tools/index.ts:4-32 (schema)

  Zod schema defining the tool's input: mermaid (string, required), theme (enum, optional, default 'default'), backgroundColor (string, optional, default 'white'), outputType (enum, optional, default 'base64').

  export const schema = z.object({
    mermaid: z
      .string()
      .describe(`The mermaid diagram syntax used to be generated, such as, graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;.`)
      .nonempty({ message: "The mermaid string cannot be empty." }),
    theme: z
      .enum(["default", "base", "forest", "dark", "neutral"])
      .describe("Theme for the diagram (optional). Default is 'default'.")
      .optional()
      .default("default"),
    backgroundColor: z
      .string()
      .describe(
        "Background color for the diagram (optional). Default is 'white'.",
      )
      .optional()
      .default("white"),
    outputType: z
      .enum(["base64", "svg", "mermaid", "file", "svg_url", "png_url"])
      .describe(
        "The output type of the diagram. Can be 'base64', 'svg', 'mermaid', 'file', 'svg_url', or 'png_url'. Default is 'base64'. 'base64' returns PNG image as base64 encoded string. 'file' saves the PNG image to disk. The *_url options return public mermaid.ink links for remote-friendly sharing.",
      )
      .optional()
      .default("base64"),
  });

• src/tools/index.ts:34-39 (registration)

  Tool registration object with name 'generate_mermaid_diagram', description, and inputSchema derived from the zod schema via zodToJsonSchema.

  export const tool = {
    name: "generate_mermaid_diagram",
    description:
      "Generate mermaid diagram and chart with mermaid syntax dynamically. Mermaid is a JavaScript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation catch up with development.",
    inputSchema: zodToJsonSchema(schema),
  };

• src/utils/render.ts:19-40 (helper)

  Core rendering helper function renderMermaid() which uses mermaid-isomorphic to render mermaid syntax to SVG/screenshot with configurable theme and background color.

  export async function renderMermaid(
    mermaid: string,
    theme = "default",
    backgroundColor = "white",
  ): Promise<RenderResult> {
    if (!renderer) renderer = createMermaidRenderer();
    const cssContent = `svg { background: ${backgroundColor}; }`;
    const cssTmpPath = path.join(os.tmpdir(), "mermaid-tmp-css.css");
    fs.writeFileSync(cssTmpPath, cssContent);
  
    const r = await renderer([mermaid], {
      // Image is needed.
      screenshot: true,
      css: cssTmpPath,
      mermaidConfig: {
        // biome-ignore lint/suspicious/noExplicitAny: <explanation>
        theme: theme as any,
      },
    });
    const r0 = r[0] as PromiseSettledResult<RenderResult>;
    return r0.status === "fulfilled" ? r0.value : Promise.reject(r0.reason);
  }

• src/utils/mermaidUrl.ts:20-28 (helper)

  Helper that creates public mermaid.ink URLs for svg_url and png_url output types.

  export function createMermaidInkUrl(
    mermaid: string,
    variant: "svg" | "img",
    theme = "default",
  ): string {
    const payload = JSON.stringify({ code: mermaid, mermaid: { theme } });
    const encoded = encodeMermaidToBase64Url(payload);
    return `https://mermaid.ink/${variant}/pako:${encoded}`;
  }