claude-mermaid

Instructions

Implementation Reference

• src/handlers.ts:147-192 (handler)

  Core handler function that validates inputs, renders the Mermaid diagram using mermaid-cli, sets up live preview for SVG format, and returns success or error response.

  export async function handleMermaidPreview(args: any) {
    const diagram = args.diagram as string;
    const previewId = args.preview_id as string;
    const format = (args.format as string) || "svg";
    const theme = (args.theme as string) || "default";
    const background = (args.background as string) || "white";
    const width = (args.width as number) || 800;
    const height = (args.height as number) || 600;
    const scale = (args.scale as number) || 2;
  
    if (!diagram) {
      throw new Error("diagram parameter is required");
    }
    if (!previewId) {
      throw new Error("preview_id parameter is required");
    }
  
    const previewDir = getPreviewDir(previewId);
    await mkdir(previewDir, { recursive: true });
    const liveFilePath = getDiagramFilePath(previewId, format);
  
    try {
      await saveDiagramSource(previewId, diagram, { theme, background, width, height, scale });
      await renderDiagram(
        { diagram, previewId, format, theme, background, width, height, scale },
        liveFilePath
      );
  
      if (format === "svg") {
        const { serverUrl, hasConnections } = await setupLivePreview(previewId, liveFilePath);
        return createLivePreviewResponse(liveFilePath, format, serverUrl, hasConnections);
      } else {
        return createStaticRenderResponse(liveFilePath, format);
      }
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error rendering Mermaid diagram: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:37-84 (schema)

  Input schema defining the parameters for the mermaid_preview tool, including required fields and defaults.

  inputSchema: {
    type: "object",
    properties: {
      diagram: {
        type: "string",
        description: "The Mermaid diagram code to render",
      },
      preview_id: {
        type: "string",
        description:
          "ID for this preview session. Use different IDs for multiple diagrams (e.g., 'architecture', 'flow', 'sequence').",
      },
      format: {
        type: "string",
        enum: ["png", "svg", "pdf"],
        description: "Output format (default: svg)",
        default: "svg",
      },
      theme: {
        type: "string",
        enum: ["default", "forest", "dark", "neutral"],
        description: "Theme of the chart (default: default)",
        default: "default",
      },
      background: {
        type: "string",
        description:
          "Background color for pngs/svgs. Example: transparent, red, '#F0F0F0' (default: white)",
        default: "white",
      },
      width: {
        type: "number",
        description: "Diagram width in pixels (default: 800)",
        default: 800,
      },
      height: {
        type: "number",
        description: "Diagram height in pixels (default: 600)",
        default: 600,
      },
      scale: {
        type: "number",
        description: "Scale factor for higher quality output (default: 2)",
        default: 2,
      },
    },
    required: ["diagram", "preview_id"],
  },

• src/index.ts:28-85 (registration)

  Registration of the 'mermaid_preview' tool in the TOOL_DEFINITIONS array, including name, description, and reference to inputSchema.

  {
    name: "mermaid_preview",
    description:
      "Render a Mermaid diagram and open it in browser with live reload. " +
      "Takes Mermaid diagram code as input and generates a live preview. " +
      "Supports themes (default, forest, dark, neutral), custom backgrounds, dimensions, and quality scaling. " +
      "The diagram will auto-refresh when updated. Use mermaid_save to save to disk. " +
      "IMPORTANT: Automatically use this tool whenever you create a Mermaid diagram for the user. " +
      "NOTE: Sequence diagrams do not support style directives - avoid using 'style' statements in sequenceDiagram.",
    inputSchema: {
      type: "object",
      properties: {
        diagram: {
          type: "string",
          description: "The Mermaid diagram code to render",
        },
        preview_id: {
          type: "string",
          description:
            "ID for this preview session. Use different IDs for multiple diagrams (e.g., 'architecture', 'flow', 'sequence').",
        },
        format: {
          type: "string",
          enum: ["png", "svg", "pdf"],
          description: "Output format (default: svg)",
          default: "svg",
        },
        theme: {
          type: "string",
          enum: ["default", "forest", "dark", "neutral"],
          description: "Theme of the chart (default: default)",
          default: "default",
        },
        background: {
          type: "string",
          description:
            "Background color for pngs/svgs. Example: transparent, red, '#F0F0F0' (default: white)",
          default: "white",
        },
        width: {
          type: "number",
          description: "Diagram width in pixels (default: 800)",
          default: 800,
        },
        height: {
          type: "number",
          description: "Diagram height in pixels (default: 600)",
          default: 600,
        },
        scale: {
          type: "number",
          description: "Scale factor for higher quality output (default: 2)",
          default: 2,
        },
      },
      required: ["diagram", "preview_id"],
    },
  },

• src/index.ts:143-146 (registration)

  Dispatch logic in the CallToolRequest handler that routes 'mermaid_preview' calls to the handleMermaidPreview function.

  case "mermaid_preview":
    result = await handleMermaidPreview(args);
    mcpLogger.info(`CallTool completed: ${toolName}`);
    return result;

• src/handlers.ts:38-89 (helper)

  Key helper function that executes the mermaid-cli to render the diagram to the specified format and copies to live file path.

  async function renderDiagram(options: RenderOptions, liveFilePath: string): Promise<void> {
    const { diagram, previewId, format, theme, background, width, height, scale } = options;
  
    mcpLogger.info(`Rendering diagram: ${previewId}`, { format, theme, width, height });
  
    const tempDir = join(tmpdir(), "claude-mermaid");
    await mkdir(tempDir, { recursive: true });
  
    const inputFile = join(tempDir, `diagram-${previewId}.mmd`);
    const outputFile = join(tempDir, `diagram-${previewId}.${format}`);
  
    await writeFile(inputFile, diagram, "utf-8");
  
    const args = [
      "-y",
      "@mermaid-js/mermaid-cli",
      "-i",
      inputFile,
      "-o",
      outputFile,
      "-t",
      theme,
      "-b",
      background,
      "-w",
      width.toString(),
      "-H",
      height.toString(),
      "-s",
      scale.toString(),
    ];
  
    if (format === "pdf") {
      args.push("--pdfFit");
    }
  
    mcpLogger.debug(`Executing mermaid-cli`, { args });
  
    try {
      const { stdout, stderr } = await execFileAsync("npx", args);
      if (stderr) {
        mcpLogger.debug(`mermaid-cli stderr`, { stderr });
      }
      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;
    }
  }