MCP Server Mermaid

Instructions

Implementation Reference

• src/server.ts:51-159 (handler)

  Handler function for CallToolRequestSchema that checks if the tool name matches 'generate_mermaid_diagram', validates arguments using the schema, renders the Mermaid diagram with custom theme and background, and returns content based on outputType (base64 image, SVG, URL, file, or raw mermaid).

  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;
        const { id, svg, screenshot } = await renderMermaid(
          mermaid as string,
          theme as string,
          backgroundColor as string,
        );
  
        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);
          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) {
        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 input parameters for the generate_mermaid_diagram tool: mermaid syntax (required), theme, backgroundColor, and outputType.

  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/server.ts:47-49 (registration)

  Registration of the tool in the MCP server's ListToolsRequest handler, exposing the tool metadata.

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

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

  Tool metadata object with name, description, and input schema (converted to JSON schema).

  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 helper function that renders Mermaid diagram to SVG and PNG screenshot using mermaid-isomorphic, applies theme and custom background CSS.

  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:19-25 (helper)

  Helper to generate public mermaid.ink URLs for SVG or PNG by deflate-compressing and base64url-encoding the mermaid syntax.

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