claude-mermaid

Instructions

Implementation Reference

• src/handlers.ts:194-267 (handler)

  The handler function that executes the mermaid_save tool: validates inputs, ensures the diagram is rendered, copies the file to the target path, and returns success/error messages.

  export async function handleMermaidSave(args: any) {
    const savePath = args.save_path as string;
    const previewId = args.preview_id as string;
    const format = (args.format as string) || "svg";
  
    if (!savePath) {
      throw new Error("save_path parameter is required");
    }
    if (!previewId) {
      throw new Error("preview_id parameter is required");
    }
  
    // Validate save path to prevent path traversal attacks
    try {
      validateSavePath(savePath);
    } catch (error) {
      mcpLogger.error("Save path validation failed", {
        savePath,
        error: error instanceof Error ? error.message : String(error),
      });
      return {
        content: [
          {
            type: "text",
            text: `Invalid save path: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  
    try {
      const liveFilePath = getDiagramFilePath(previewId, format);
  
      try {
        await access(liveFilePath);
      } catch {
        const diagram = await loadDiagramSource(previewId);
        const options = await loadDiagramOptions(previewId);
        await renderDiagram(
          {
            diagram,
            previewId,
            format,
            ...options,
          },
          liveFilePath
        );
      }
  
      const saveDir = dirname(savePath);
      await mkdir(saveDir, { recursive: true });
      await copyFile(liveFilePath, savePath);
  
      return {
        content: [
          {
            type: "text",
            text: `Diagram saved to: ${savePath} (${format.toUpperCase()})`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error saving diagram: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:92-113 (schema)

  Input schema defining parameters for the mermaid_save tool: save_path (required), preview_id (required), format (optional, defaults to svg).

  inputSchema: {
    type: "object",
    properties: {
      save_path: {
        type: "string",
        description: "Path to save the diagram file (e.g., './docs/diagram.svg')",
      },
      preview_id: {
        type: "string",
        description:
          "ID of the preview to save. Must match the preview_id used in mermaid_preview.",
      },
      format: {
        type: "string",
        enum: ["png", "svg", "pdf"],
        description:
          "Output format (default: svg). Must match the format used in mermaid_preview.",
        default: "svg",
      },
    },
    required: ["save_path", "preview_id"],
  },

• src/index.ts:86-114 (registration)

  Tool definition in TOOL_DEFINITIONS array used for ListTools, including name, description, and schema.

  {
    name: "mermaid_save",
    description:
      "Save the current live Mermaid diagram to a file path. " +
      "This copies the already-rendered diagram from the live preview to the specified location. " +
      "Use this after tuning your diagram with mermaid_preview.",
    inputSchema: {
      type: "object",
      properties: {
        save_path: {
          type: "string",
          description: "Path to save the diagram file (e.g., './docs/diagram.svg')",
        },
        preview_id: {
          type: "string",
          description:
            "ID of the preview to save. Must match the preview_id used in mermaid_preview.",
        },
        format: {
          type: "string",
          enum: ["png", "svg", "pdf"],
          description:
            "Output format (default: svg). Must match the format used in mermaid_preview.",
          default: "svg",
        },
      },
      required: ["save_path", "preview_id"],
    },
  },

• src/index.ts:147-150 (registration)

  Dispatches to the handleMermaidSave handler in the CallTool request handler switch statement.

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