render_mermaid

Instructions

Implementation Reference

• src/mcp/server.ts:120-144 (registration)

  Registration of the 'render_mermaid' tool including name, description, and input schema definition.

  {
    name: "render_mermaid",
    description:
      'Render a Mermaid diagram to SVG format. CRITICAL RULES: 1) Node IDs must be alphanumeric without spaces (use A1, nodeA, start_node). 2) For node labels with special characters, wrap in quotes: A["Label with spaces"] or A["Process (step 1)"]. 3) For quotes in labels use ", for < use <, for > use >. 4) For square brackets in labels use A["Array[0]"]. 5) Always close all brackets and quotes. 6) Use consistent arrow styles (either --> or ->). Example: graph TD\\n  A["Complex Label"] --> B{Decision?}\\n  B -->|Yes| C["Result "OK""]\\n\\nIMPORTANT: If the diagram fails validation, the error message will explain what needs to be fixed. Please read the error carefully and retry with a corrected diagram.',
    inputSchema: {
      type: "object",
      properties: {
        diagram: {
          type: "string",
          description: `Mermaid diagram syntax. MUST start with diagram type (graph TD, flowchart LR, sequenceDiagram, etc). Node IDs cannot have spaces. Use quotes for labels with spaces/special chars. Avoid forward slashes. Use this colors which work well for both light and dark mode: ${colorPrompt}`,
        },
        background: {
          type: "string",
          description: "Background color",
          default: "white",
        },
        title: {
          type: "string",
          description: "Title for the diagram (max 50 characters)",
          maxLength: 50,
        },
      },
      required: ["diagram", "title"],
    },
  },

• src/mcp/server.ts:280-321 (handler)

  The primary handler method for executing the render_mermaid tool, proxying the request to the HTTP server's /api/render endpoint and handling the RenderResult.

  private async renderMermaid(
    diagram: string,
    background?: string,
    title?: string,
  ): Promise<RenderResult> {
    // Use HTTP API endpoint
    try {
      const response = await fetch(
        `http://localhost:${this.httpPort}/api/render`,
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            diagram,
            background,
            title,
            clientId: this.clientId,
            clientName: this.clientName,
            workingDir: process.cwd(),
          }),
          signal: this.getAbortSignal(),
        },
      );
  
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
  
      const result = (await response.json()) as RenderResult;
  
      return result;
    } catch (error) {
      return {
        type: "error",
        diagram,
        error:
          error instanceof Error ? error.message : "Failed to render diagram",
      };
    }
  }

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

  The switch case in the CallToolRequestHandler that invokes the renderMermaid method for the 'render_mermaid' tool.

  case "render_mermaid":
    const renderResult = await this.renderMermaid(
      args?.diagram as string,
      args?.background as string,
      args?.title as string,
    );
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(renderResult, null, 2),
        },
      ],
    };

• src/shared/renderer.ts:4-36 (helper)

  Core rendering helper function that validates Mermaid syntax and prepares the RenderResult for client-side SVG rendering. Used by the HTTP server.

  export async function renderMermaid(
    diagram: string,
    background?: string,
  ): Promise<RenderResult> {
    try {
      // Validate the diagram first
      const validation = await validateMermaidSyntax(diagram);
  
      if (!validation.valid) {
        return {
          type: "error",
          diagram,
          error: validation.errors?.[0] || "Invalid diagram syntax",
          details: validation.errors?.join("\n"),
        };
      }
  
      // Return the validated diagram for client-side rendering
      // The actual SVG rendering happens in the browser
      return {
        type: "success",
        diagram,
        background,
        // Note: svg field is populated by the client after rendering
      };
    } catch (error) {
      return {
        type: "error",
        diagram,
        error: error instanceof Error ? error.message : "Failed to process diagram",
      };
    }
  }

• src/mcp/server.ts:124-142 (schema)

  Input schema definition for the render_mermaid tool, specifying properties and requirements.

  inputSchema: {
    type: "object",
    properties: {
      diagram: {
        type: "string",
        description: `Mermaid diagram syntax. MUST start with diagram type (graph TD, flowchart LR, sequenceDiagram, etc). Node IDs cannot have spaces. Use quotes for labels with spaces/special chars. Avoid forward slashes. Use this colors which work well for both light and dark mode: ${colorPrompt}`,
      },
      background: {
        type: "string",
        description: "Background color",
        default: "white",
      },
      title: {
        type: "string",
        description: "Title for the diagram (max 50 characters)",
        maxLength: 50,
      },
    },
    required: ["diagram", "title"],