Repository: peng-shawn/mermaid-mcp-server Branch: main Commit: 81dc507991c6 Files: 10 Total size: 38.6 KB Directory structure: gitextract_pz7yyjpu/ ├── .github/ │ └── workflows/ │ └── npm-publish.yml ├── .gitignore ├── Dockerfile ├── LICENSE ├── README.md ├── index.ts ├── package.json ├── scripts/ │ └── release.sh ├── smithery.yaml └── tsconfig.json ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/workflows/npm-publish.yml ================================================ name: Publish to npm on: push: tags: - 'v*' # Run workflow on version tags, e.g. v1.0.0 jobs: build-and-publish: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' registry-url: 'https://registry.npmjs.org' - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Publish to npm run: npm publish --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} ================================================ FILE: .gitignore ================================================ node_modules dist .cursor/* ================================================ FILE: Dockerfile ================================================ # Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile # Use node:lts-slim (Debian-based) instead of Alpine for better Chrome compatibility FROM node:lts-slim # Set working directory WORKDIR /app # Install Chromium with its dependencies RUN apt-get update && apt-get install -y \ chromium \ --no-install-recommends \ && rm -rf /var/lib/apt/lists/* # Copy package files and install dependencies # Use PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true to avoid downloading Chromium again ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true COPY package.json package-lock.json ./ RUN npm install # Copy the rest of the application files COPY . . # Build the TypeScript code RUN npm run build # Command to run the MCP server CMD [ "node", "dist/index.js" ] ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2025 Shawn Peng Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # Mermaid MCP Server A Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images or SVG files. This server allows AI assistants and other applications to generate visual diagrams from textual descriptions using the Mermaid markdown syntax. ## Features - Converts Mermaid diagram code to PNG images or SVG files - Supports multiple diagram themes (default, forest, dark, neutral) - Customizable background colors - Uses Puppeteer for high-quality headless browser rendering - Implements the MCP protocol for seamless integration with AI assistants - Flexible output options: return images/SVG directly or save to disk - Error handling with detailed error messages ## How It Works The server uses Puppeteer to launch a headless browser, render the Mermaid diagram to SVG, and optionally capture a screenshot of the rendered diagram. The process involves: 1. Launching a headless browser instance 2. Creating an HTML template with the Mermaid code 3. Loading the Mermaid.js library 4. Rendering the diagram to SVG 5. Either saving the SVG directly or taking a screenshot as PNG 6. Either returning the image/SVG directly or saving it to disk ## Build ```bash npx tsc ``` ## Usage ### Use with Claude desktop ```json { "mcpServers": { "mermaid": { "command": "npx", "args": ["-y", "@peng-shawn/mermaid-mcp-server"] } } } ``` ### Use with Cursor and Cline ```bash env CONTENT_IMAGE_SUPPORTED=false npx -y @peng-shawn/mermaid-mcp-server ``` You can find a list of mermaid diagrams under `./diagrams`, they are created using Cursor agent with prompt: "generate mermaid diagrams and save them in a separate diagrams folder explaining how renderMermaidPng work" ### Run with inspector Run the server with inspector for testing and debugging: ```bash npx @modelcontextprotocol/inspector node dist/index.js ``` The server will start and listen on stdio for MCP protocol messages. Learn more about inspector [here](https://modelcontextprotocol.io/docs/tools/inspector). ### Installing via Smithery To install Mermaid Diagram Generator for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@peng-shawn/mermaid-mcp-server): ```bash npx -y @smithery/cli install @peng-shawn/mermaid-mcp-server --client claude ``` ### Docker and Smithery Environments When running in Docker containers (including via Smithery), you may need to handle Chrome dependencies: 1. The server now attempts to use Puppeteer's bundled browser by default 2. If you encounter browser-related errors, you have two options: **Option 1: During Docker image build:** - Set `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true` when installing Puppeteer - Install Chrome/Chromium in your Docker container - Set `PUPPETEER_EXECUTABLE_PATH` at runtime to point to the Chrome installation **Option 2: Use Puppeteer's bundled Chrome:** - Ensure your Docker container has the necessary dependencies for Chrome - No need to set `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` - The code will use the bundled browser automatically For Smithery users, the latest version should work without additional configuration. ## API The server exposes a single tool: - `generate`: Converts Mermaid diagram code to a PNG image or SVG file - Parameters: - `code`: The Mermaid diagram code to render - `theme`: (optional) Theme for the diagram. Options: "default", "forest", "dark", "neutral" - `backgroundColor`: (optional) Background color for the diagram, e.g. 'white', 'transparent', '#F0F0F0' - `outputFormat`: (optional) Output format for the diagram. Options: "png", "svg" (defaults to "png") - `name`: Name for the generated file (required when CONTENT_IMAGE_SUPPORTED=false) - `folder`: Absolute path to save the image/SVG to (required when CONTENT_IMAGE_SUPPORTED=false) The behavior of the `generate` tool depends on the `CONTENT_IMAGE_SUPPORTED` environment variable: - When `CONTENT_IMAGE_SUPPORTED=true` (default): The tool returns the image/SVG directly in the response - When `CONTENT_IMAGE_SUPPORTED=false`: The tool saves the image/SVG to the specified folder and returns the file path ## Environment Variables - `CONTENT_IMAGE_SUPPORTED`: Controls whether images are returned directly in the response or saved to disk - `true` (default): Images are returned directly in the response - `false`: Images are saved to disk, requiring `name` and `folder` parameters ## Examples ### Basic Usage ```javascript // Generate a flowchart with default settings { "code": "flowchart TD\n A[Start] --> B{Is it?}\n B -->|Yes| C[OK]\n B -->|No| D[End]" } ``` ### With Theme and Background Color ```javascript // Generate a sequence diagram with forest theme and light gray background { "code": "sequenceDiagram\n Alice->>John: Hello John, how are you?\n John-->>Alice: Great!", "theme": "forest", "backgroundColor": "#F0F0F0" } ``` ### Saving to Disk (when CONTENT_IMAGE_SUPPORTED=false) ```javascript // Generate a class diagram and save it to disk as PNG { "code": "classDiagram\n Class01 <|-- AveryLongClass\n Class03 *-- Class04\n Class05 o-- Class06", "theme": "dark", "name": "class_diagram", "folder": "/path/to/diagrams" } ``` ### Generating SVG Output ```javascript // Generate a state diagram as SVG { "code": "stateDiagram-v2\n [*] --> Still\n Still --> [*]\n Still --> Moving\n Moving --> Still\n Moving --> Crash\n Crash --> [*]", "outputFormat": "svg", "name": "state_diagram", "folder": "/path/to/diagrams" } ``` ## FAQ ### Doesn't Claude desktop already support mermaid via canvas? Yes, but it doesn't support the `theme` and `backgroundColor` options. Plus, having a dedicated server makes it easier to create mermaid diagrams with different MCP clients. ### Why do I need to specify CONTENT_IMAGE_SUPPORTED=false when using with Cursor? Cursor doesn't support inline images in responses yet. ## Publishing This project uses GitHub Actions to automate the publishing process to npm. ### Method 1: Using the Release Script (Recommended) 1. Make sure all your changes are committed and pushed 2. Run the release script with either a specific version number or a semantic version increment: ```bash # Using a specific version number npm run release 0.1.4 # Using semantic version increments npm run release patch # Increments the patch version (e.g., 0.1.3 → 0.1.4) npm run release minor # Increments the minor version (e.g., 0.1.3 → 0.2.0) npm run release major # Increments the major version (e.g., 0.1.3 → 1.0.0) ``` 3. The script will: - Validate the version format or semantic increment - Check if you're on the main branch - Detect and warn about version mismatches between files - Update all version references consistently (package.json, package-lock.json, and index.ts) - Create a single commit with all version changes - Create and push a git tag - The GitHub workflow will then automatically build and publish to npm ### Method 2: Manual Process 1. Update your code and commit the changes 2. Create and push a new tag with the version number: ```bash git tag v0.1.4 # Use the appropriate version number git push origin v0.1.4 ``` 3. The GitHub workflow will automatically: - Build the project - Publish to npm with the version from the tag Note: You need to set up the `NPM_TOKEN` secret in your GitHub repository settings. To do this: 1. Generate an npm access token with publish permissions 2. Go to your GitHub repository → Settings → Secrets and variables → Actions 3. Create a new repository secret named `NPM_TOKEN` with your npm token as the value ## Badges [![smithery badge](https://smithery.ai/badge/@peng-shawn/mermaid-mcp-server)](https://smithery.ai/server/@peng-shawn/mermaid-mcp-server) mermaid-mcp-server MCP server ## License MIT ================================================ FILE: index.ts ================================================ #!/usr/bin/env node import puppeteer from "puppeteer"; import path from "path"; import url from "url"; import fs from "fs"; import { resolve } from "import-meta-resolve"; import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { CallToolRequestSchema, ListToolsRequestSchema, Tool, } from "@modelcontextprotocol/sdk/types.js"; /** * Mermaid MCP Server * * This server provides a tool to render Mermaid diagrams as PNG images or SVG files. * * Environment Variables: * - MERMAID_LOG_VERBOSITY: Controls the verbosity of logging (default: 2) * 0 = EMERGENCY - Only the most critical errors * 1 = CRITICAL - Critical errors that require immediate attention * 2 = ERROR - Error conditions (default) * 3 = WARNING - Warning conditions * 4 = INFO - Informational messages * 5 = DEBUG - Debug-level messages * - CONTENT_IMAGE_SUPPORTED: Controls whether images can be returned directly in the response (default: true) * When set to 'false', the 'name' and 'folder' parameters become mandatory, and all images must be saved to disk. * * Example: * MERMAID_LOG_VERBOSITY=2 node index.js # Only show ERROR and more severe logs (default) * MERMAID_LOG_VERBOSITY=4 node index.js # Show INFO and more severe logs * MERMAID_LOG_VERBOSITY=5 node index.js # Show DEBUG and more severe logs * CONTENT_IMAGE_SUPPORTED=false node index.js # Require all images to be saved to disk * * Tool Parameters: * - code: The mermaid markdown to generate an image from (required) * - theme: Theme for the diagram (optional, one of: "default", "forest", "dark", "neutral") * - backgroundColor: Background color for the diagram (optional, e.g., "white", "transparent", "#F0F0F0") * - outputFormat: Output format for the diagram (optional, "png" or "svg", defaults to "png") * - name: Name for the generated file (required when saving to folder or when CONTENT_IMAGE_SUPPORTED=false) * - folder: Folder path to save the image to (optional, but required when CONTENT_IMAGE_SUPPORTED=false) * * File Saving Behavior: * - When 'folder' is specified, the image will be saved to disk instead of returned in the response * - The 'name' parameter is required when 'folder' is specified * - If a file with the same name already exists, a timestamp will be appended to the filename * - When CONTENT_IMAGE_SUPPORTED=false, all images must be saved to disk, and 'name' and 'folder' are required * - SVG files are saved as .svg text files, PNG files are saved as .png binary files */ // __dirname is not available in ESM modules by default const __dirname = url.fileURLToPath(new URL(".", import.meta.url)); // Define log levels with numeric values for comparison enum LogLevel { EMERGENCY = 0, CRITICAL = 1, ERROR = 2, WARNING = 3, INFO = 4, DEBUG = 5, } // Get verbosity level from environment variable, default to INFO (4) const LOG_VERBOSITY = process.env.MERMAID_LOG_VERBOSITY ? parseInt(process.env.MERMAID_LOG_VERBOSITY, 10) : LogLevel.ERROR; // Check if content images are supported (default: true) const CONTENT_IMAGE_SUPPORTED = process.env.CONTENT_IMAGE_SUPPORTED !== "false"; // Convert LogLevel to MCP log level string function getMcpLogLevel( level: LogLevel ): "error" | "info" | "debug" | "warning" | "critical" | "emergency" { switch (level) { case LogLevel.EMERGENCY: return "emergency"; case LogLevel.CRITICAL: return "critical"; case LogLevel.ERROR: return "error"; case LogLevel.WARNING: return "warning"; case LogLevel.DEBUG: return "debug"; case LogLevel.INFO: default: return "info"; } } function log(level: LogLevel, message: string) { // Only log if the current level is less than or equal to the verbosity setting if (level <= LOG_VERBOSITY) { // Get the appropriate MCP log level const mcpLevel = getMcpLogLevel(level); server.sendLoggingMessage({ level: mcpLevel, data: message, }); // Only console.error is consumed by MCP inspector console.error(`${LogLevel[level]} - ${message}`); } } // Define tools const GENERATE_TOOL: Tool = { name: "generate", description: "Generate PNG image or SVG from mermaid markdown", inputSchema: { type: "object", properties: { code: { type: "string", description: "The mermaid markdown to generate an image from", }, theme: { type: "string", enum: ["default", "forest", "dark", "neutral"], description: "Theme for the diagram (optional)", }, backgroundColor: { type: "string", description: "Background color for the diagram, e.g. 'white', 'transparent', '#F0F0F0' (optional)", }, outputFormat: { type: "string", enum: ["png", "svg"], description: "Output format for the diagram (optional, defaults to 'png')", }, name: { type: "string", description: CONTENT_IMAGE_SUPPORTED ? "Name of the diagram (optional)" : "Name for the generated file (required)", }, folder: { type: "string", description: CONTENT_IMAGE_SUPPORTED ? "Absolute path to save the image to (optional)" : "Absolute path to save the image to (required)", }, }, required: CONTENT_IMAGE_SUPPORTED ? ["code"] : ["code", "name", "folder"], }, }; // Server implementation const server = new Server( { name: "mermaid-mcp-server", version: "0.2.0", }, { capabilities: { tools: {}, logging: {}, }, } ); function isGenerateArgs(args: unknown): args is { code: string; theme?: "default" | "forest" | "dark" | "neutral"; backgroundColor?: string; outputFormat?: "png" | "svg"; name?: string; folder?: string; } { return ( typeof args === "object" && args !== null && "code" in args && typeof (args as any).code === "string" && (!(args as any).theme || ["default", "forest", "dark", "neutral"].includes((args as any).theme)) && (!(args as any).backgroundColor || typeof (args as any).backgroundColor === "string") && (!(args as any).outputFormat || ["png", "svg"].includes((args as any).outputFormat)) && (!(args as any).name || typeof (args as any).name === "string") && (!(args as any).folder || typeof (args as any).folder === "string") ); } async function renderMermaid( code: string, config: { theme?: "default" | "forest" | "dark" | "neutral"; backgroundColor?: string; outputFormat?: "png" | "svg"; } = {} ): Promise<{ data: string; svg?: string }> { log(LogLevel.INFO, "Launching Puppeteer"); log(LogLevel.DEBUG, `Rendering with config: ${JSON.stringify(config)}`); // Resolve the path to the local mermaid.js file const distPath = path.dirname( url.fileURLToPath(resolve("mermaid", import.meta.url)) ); const mermaidPath = path.resolve(distPath, "mermaid.min.js"); log(LogLevel.DEBUG, `Using Mermaid from: ${mermaidPath}`); const browser = await puppeteer.launch({ headless: true, // Use the bundled browser instead of looking for Chrome on the system executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || undefined, args: ["--no-sandbox", "--disable-setuid-sandbox"], }); // Declare page outside try block so it's accessible in catch and finally let page: puppeteer.Page | null = null; // Store console messages for error reporting const consoleMessages: string[] = []; try { page = await browser.newPage(); log(LogLevel.DEBUG, "Browser page created"); // Capture browser console messages for better error reporting page.on("console", (msg) => { const text = msg.text(); consoleMessages.push(text); log(LogLevel.DEBUG, text); }); // Create a simple HTML template without the CDN reference const htmlContent = ` Mermaid Renderer
`; // Note: Must be set before page.goto() to ensure the page renders with the correct dimensions from the start await page.setViewport({ width: 1200, // Keep the same viewport size as before height: 800, deviceScaleFactor: 3, // 2~4 is fine, the larger the PNG, the clearer and larger it is }); // Write the HTML to a temporary file const tempHtmlPath = path.join(__dirname, "temp-mermaid.html"); fs.writeFileSync(tempHtmlPath, htmlContent); log(LogLevel.INFO, `Rendering mermaid code: ${code.substring(0, 50)}...`); log(LogLevel.DEBUG, `Full mermaid code: ${code}`); // Navigate to the HTML file await page.goto(`file://${tempHtmlPath}`); log(LogLevel.DEBUG, "Navigated to HTML template"); // Add the mermaid script to the page await page.addScriptTag({ path: mermaidPath }); log(LogLevel.DEBUG, "Added Mermaid script to page"); // Render the mermaid diagram using a more robust approach similar to the CLI log(LogLevel.DEBUG, "Starting Mermaid rendering in browser"); const screenshot = await page.$eval( "#container", async (container, mermaidCode, mermaidConfig) => { try { // @ts-ignore - mermaid is loaded by the script tag window.mermaid.initialize({ startOnLoad: false, theme: mermaidConfig.theme || "default", securityLevel: "loose", logLevel: 5, }); // This will throw an error if the mermaid syntax is invalid // @ts-ignore - mermaid is loaded by the script tag const { svg: svgText } = await window.mermaid.render( "mermaid-svg", mermaidCode, container ); container.innerHTML = svgText; const svg = container.querySelector("svg"); if (!svg) { throw new Error("SVG element not found after rendering"); } // Apply any necessary styling to the SVG svg.style.backgroundColor = mermaidConfig.backgroundColor || "white"; // Return the dimensions for screenshot const rect = svg.getBoundingClientRect(); return { width: Math.ceil(rect.width), height: Math.ceil(rect.height), success: true, }; } catch (error) { // Return the error to be handled outside return { success: false, error: error instanceof Error ? error.message : String(error), }; } }, code, { theme: config.theme, backgroundColor: config.backgroundColor } ); // Check if rendering was successful if (!screenshot.success) { log( LogLevel.ERROR, `Mermaid rendering failed in browser: ${screenshot.error}` ); throw new Error(`Mermaid rendering failed: ${screenshot.error}`); } log(LogLevel.DEBUG, "Mermaid rendered successfully in browser"); // Get the SVG content if needed let svgContent: string | undefined; if (config.outputFormat === "svg") { svgContent = await page.$eval("#container svg", (svg) => { return svg.outerHTML; }); log(LogLevel.DEBUG, "SVG content extracted"); } // Take a screenshot of the SVG for PNG output let base64Image = ""; if (config.outputFormat === "png" || config.outputFormat === undefined) { const svgElement = await page.$("#container svg"); if (!svgElement) { log(LogLevel.ERROR, "SVG element not found after successful rendering"); throw new Error("SVG element not found"); } log(LogLevel.DEBUG, "Taking screenshot of SVG"); // Take a screenshot with the correct dimensions base64Image = await svgElement.screenshot({ omitBackground: false, type: "png", encoding: "base64", }); } // Clean up the temporary file fs.unlinkSync(tempHtmlPath); log(LogLevel.DEBUG, "Temporary HTML file cleaned up"); log(LogLevel.INFO, "Mermaid rendered successfully"); return { data: base64Image, svg: svgContent }; } catch (error) { log( LogLevel.ERROR, `Error in renderMermaid: ${ error instanceof Error ? error.message : String(error) }` ); log( LogLevel.ERROR, `Error stack: ${error instanceof Error ? error.stack : "No stack trace"}` ); // Include console messages in the error for better debugging if (page && page.isClosed() === false) { log(LogLevel.ERROR, "Browser console messages:"); consoleMessages.forEach((msg) => log(LogLevel.ERROR, ` ${msg}`)); } throw error; } finally { await browser.close(); log(LogLevel.DEBUG, "Puppeteer browser closed"); } } /** * Saves a generated Mermaid diagram to a file * * @param base64Image - The base64-encoded PNG image * @param name - The name to use for the file (without extension) * @param folder - The folder to save the file in * @returns The full path to the saved file */ async function saveMermaidImageToFile( base64Image: string, name: string, folder: string ): Promise { // Create the folder if it doesn't exist if (!fs.existsSync(folder)) { log(LogLevel.INFO, `Creating folder: ${folder}`); fs.mkdirSync(folder, { recursive: true }); } // Generate a filename, adding timestamp if file already exists let filename = `${name}.png`; const filePath = path.join(folder, filename); if (fs.existsSync(filePath)) { const timestamp = new Date().toISOString().replace(/[:.]/g, "-"); filename = `${name}-${timestamp}.png`; log(LogLevel.INFO, `File already exists, using filename: ${filename}`); } // Save the image to the file const imageBuffer = Buffer.from(base64Image, "base64"); const fullPath = path.join(folder, filename); fs.writeFileSync(fullPath, imageBuffer); log(LogLevel.INFO, `Image saved to: ${fullPath}`); return fullPath; } /** * Saves a generated Mermaid SVG to a file * * @param svgContent - The SVG content as a string * @param name - The name to use for the file (without extension) * @param folder - The folder to save the file in * @returns The full path to the saved file */ async function saveMermaidSvgToFile( svgContent: string, name: string, folder: string ): Promise { // Create the folder if it doesn't exist if (!fs.existsSync(folder)) { log(LogLevel.INFO, `Creating folder: ${folder}`); fs.mkdirSync(folder, { recursive: true }); } // Generate a filename, adding timestamp if file already exists let filename = `${name}.svg`; const filePath = path.join(folder, filename); if (fs.existsSync(filePath)) { const timestamp = new Date().toISOString().replace(/[:.]/g, "-"); filename = `${name}-${timestamp}.svg`; log(LogLevel.INFO, `File already exists, using filename: ${filename}`); } // Save the SVG to the file const fullPath = path.join(folder, filename); fs.writeFileSync(fullPath, svgContent, "utf-8"); log(LogLevel.INFO, `SVG saved to: ${fullPath}`); return fullPath; } /** * Handles Mermaid syntax errors and other errors * * @param error - The error that occurred * @returns A response object with the error message */ function handleMermaidError(error: unknown): { content: Array<{ type: "text"; text: string }>; isError: boolean; } { const errorMessage = error instanceof Error ? error.message : String(error); const isSyntaxError = errorMessage.includes("Syntax error") || errorMessage.includes("Parse error") || errorMessage.includes("Mermaid rendering failed"); return { content: [ { type: "text", text: isSyntaxError ? `Mermaid syntax error: ${errorMessage}\n\nPlease check your diagram syntax.` : `Error generating diagram: ${errorMessage}`, }, ], isError: true, }; } /** * Processes a generate request to create a Mermaid diagram * * @param args - The arguments for the generate request * @returns A response object with the generated image or file path */ async function processGenerateRequest(args: { code: string; theme?: "default" | "forest" | "dark" | "neutral"; backgroundColor?: string; outputFormat?: "png" | "svg"; name?: string; folder?: string; }): Promise<{ content: Array< | { type: "text"; text: string } | { type: "image"; data: string; mimeType: string } >; isError: boolean; }> { try { const outputFormat = args.outputFormat || "png"; const result = await renderMermaid(args.code, { theme: args.theme, backgroundColor: args.backgroundColor, outputFormat: outputFormat, }); // Check if we need to save the file to a folder if (!CONTENT_IMAGE_SUPPORTED) { if (!args.folder) { throw new Error( "Folder parameter is required when CONTENT_IMAGE_SUPPORTED is false" ); } // Save the file based on format let fullPath: string; if (outputFormat === "svg") { if (!result.svg) { throw new Error("SVG content not available"); } fullPath = await saveMermaidSvgToFile( result.svg, args.name!, args.folder! ); } else { fullPath = await saveMermaidImageToFile( result.data, args.name!, args.folder! ); } return { content: [ { type: "text", text: `${outputFormat.toUpperCase()} saved to: ${fullPath}`, }, ], isError: false, }; } // If folder is provided and CONTENT_IMAGE_SUPPORTED is true, save the file to the folder // but also return the content in the response let savedMessage = ""; if (args.folder && args.name) { try { let fullPath: string; if (outputFormat === "svg") { if (!result.svg) { throw new Error("SVG content not available"); } fullPath = await saveMermaidSvgToFile( result.svg, args.name, args.folder ); } else { fullPath = await saveMermaidImageToFile( result.data, args.name, args.folder ); } savedMessage = `${outputFormat.toUpperCase()} also saved to: ${fullPath}`; log(LogLevel.INFO, savedMessage); } catch (saveError) { log( LogLevel.ERROR, `Failed to save ${outputFormat} to folder: ${(saveError as Error).message}` ); savedMessage = `Note: Failed to save ${outputFormat} to folder: ${ (saveError as Error).message }`; } } // Return the appropriate content based on format if (outputFormat === "svg") { if (!result.svg) { throw new Error("SVG content not available"); } return { content: [ { type: "text", text: savedMessage ? `Here is the generated SVG:\n\n${result.svg}\n\n${savedMessage}` : `Here is the generated SVG:\n\n${result.svg}`, }, ], isError: false, }; } else { // Return the PNG image in the response return { content: [ { type: "text", text: savedMessage ? `Here is the generated image. ${savedMessage}` : "Here is the generated image", }, { type: "image", data: result.data, mimeType: "image/png", }, ], isError: false, }; } } catch (error) { return handleMermaidError(error); } } // Tool handlers server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [GENERATE_TOOL], })); // Set up the request handler for tool calls server.setRequestHandler(CallToolRequestSchema, async (request) => { try { const { name, arguments: args } = request.params; if (!args) { throw new Error("No arguments provided"); } log( LogLevel.INFO, `Received request: ${name} with args: ${JSON.stringify(args)}` ); if (name === "generate") { log(LogLevel.INFO, "Rendering Mermaid PNG"); if (!isGenerateArgs(args)) { throw new Error("Invalid arguments for generate"); } // Process the generate request return await processGenerateRequest(args); } return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true, }; } catch (error) { return { content: [ { type: "text", text: `Error: ${ error instanceof Error ? error.message : String(error) }`, }, ], isError: true, }; } }); async function runServer() { const transport = new StdioServerTransport(); await server.connect(transport); log(LogLevel.INFO, "Mermaid MCP Server running on stdio"); } runServer().catch((error) => { log( LogLevel.CRITICAL, `Fatal error running server: ${ error instanceof Error ? error.message : String(error) }` ); process.exit(1); }); ================================================ FILE: package.json ================================================ { "name": "@peng-shawn/mermaid-mcp-server", "version": "0.2.0", "description": "A Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images", "main": "dist/index.js", "type": "module", "scripts": { "build": "tsc", "start": "node dist/index.js", "release": "scripts/release.sh" }, "bin": { "mermaid-mcp-server": "dist/index.js" }, "files": [ "dist", "README.md", "LICENSE" ], "keywords": [ "mermaid", "diagram", "mcp", "model-context-protocol", "ai", "visualization" ], "author": "Shawn Peng", "license": "MIT", "dependencies": { "@modelcontextprotocol/sdk": "^1.6.1", "import-meta-resolve": "^4.1.0", "mermaid": "^11.4.1", "puppeteer": "^24.3.1" }, "devDependencies": { "@types/node": "^22.13.9", "typescript": "^5.8.2" }, "engines": { "node": ">=18.0.0" }, "repository": { "type": "git", "url": "git+https://github.com/peng-shawn/mermaid-mcp-server.git" }, "bugs": { "url": "https://github.com/peng-shawn/mermaid-mcp-server/issues" }, "homepage": "https://github.com/peng-shawn/mermaid-mcp-server#readme" } ================================================ FILE: scripts/release.sh ================================================ #!/bin/bash # Script to help with the release process # Check if a version argument was provided if [ -z "$1" ]; then echo "Error: No version specified" echo "Usage: ./scripts/release.sh " echo "Examples:" echo " ./scripts/release.sh 0.1.4 # Set specific version" echo " ./scripts/release.sh patch # Increment patch version (0.1.3 -> 0.1.4)" echo " ./scripts/release.sh minor # Increment minor version (0.1.3 -> 0.2.0)" echo " ./scripts/release.sh major # Increment major version (0.1.3 -> 1.0.0)" exit 1 fi VERSION_ARG=$1 # Check if the version is a semantic increment or specific version if [[ "$VERSION_ARG" =~ ^(patch|minor|major)$ ]]; then # It's a semantic increment INCREMENT_TYPE=$VERSION_ARG # Get the current version to display in logs CURRENT_VERSION=$(grep -o '"version": "[^"]*"' package.json | cut -d'"' -f4) echo "Using semantic increment: $INCREMENT_TYPE (current version: $CURRENT_VERSION)" else # It's a specific version - validate semver format if ! [[ $VERSION_ARG =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+)?(\+[0-9A-Za-z-]+)?$ ]]; then echo "Error: Version must follow semantic versioning (e.g., 1.2.3, 1.2.3-beta, etc.)" echo "Or use one of: patch, minor, major" exit 1 fi # Store the specific version SPECIFIC_VERSION=$VERSION_ARG echo "Using specific version: $SPECIFIC_VERSION" fi # Check if we're on the main branch CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD) if [ "$CURRENT_BRANCH" != "main" ]; then echo "Warning: You are not on the main branch. Current branch: $CURRENT_BRANCH" read -p "Do you want to continue? (y/n) " -n 1 -r echo if [[ ! $REPLY =~ ^[Yy]$ ]]; then exit 1 fi fi # Check if working directory is clean if [ -n "$(git status --porcelain)" ]; then echo "Error: Working directory is not clean. Please commit or stash your changes." exit 1 fi # Pull latest changes echo "Pulling latest changes from origin..." git pull origin main # Check current versions in files PACKAGE_VERSION=$(grep -o '"version": "[^"]*"' package.json | cut -d'"' -f4) PACKAGE_LOCK_VERSION=$(grep -o '"version": "[^"]*"' package-lock.json | head -1 | cut -d'"' -f4) INDEX_VERSION=$(grep -o 'version: "[^"]*"' index.ts | cut -d'"' -f2) echo "Current versions:" echo "- package.json: $PACKAGE_VERSION" echo "- package-lock.json: $PACKAGE_LOCK_VERSION" echo "- index.ts: $INDEX_VERSION" # Function to update index.ts version update_index_version() { local old_version=$1 local new_version=$2 local commit_msg=$3 echo "Updating version in index.ts from $old_version to $new_version..." sed -i '' "s/version: \"$old_version\"/version: \"$new_version\"/" index.ts git add index.ts if [ -n "$commit_msg" ]; then git commit -m "$commit_msg" fi } if [ "$PACKAGE_VERSION" != "$PACKAGE_LOCK_VERSION" ] || [ "$PACKAGE_VERSION" != "$INDEX_VERSION" ]; then echo "Warning: Version mismatch detected between files." if [ -n "$SPECIFIC_VERSION" ]; then echo "Will update all files to version: $SPECIFIC_VERSION" else echo "Will update all files using increment: $INCREMENT_TYPE" fi read -p "Do you want to continue? (y/n) " -n 1 -r echo if [[ ! $REPLY =~ ^[Yy]$ ]]; then exit 1 fi fi # Handle version updates based on increment type or specific version if [ -n "$INCREMENT_TYPE" ]; then # For semantic increments echo "Incrementing version ($INCREMENT_TYPE)..." # Use npm version to increment the version npm version $INCREMENT_TYPE --no-git-tag-version # Get the new version NEW_VERSION=$(grep -o '"version": "[^"]*"' package.json | cut -d'"' -f4) # Update index.ts with the new version update_index_version "$INDEX_VERSION" "$NEW_VERSION" # Commit all changes and create tag git add package.json package-lock.json git commit -m "chore: release version $NEW_VERSION" git tag -a "v$NEW_VERSION" -m "Version $NEW_VERSION" else # For specific version # Use npm version to update package.json and package-lock.json without git operations echo "Updating version in package.json and package-lock.json..." npm version $SPECIFIC_VERSION --no-git-tag-version # Update index.ts update_index_version "$INDEX_VERSION" "$SPECIFIC_VERSION" # Commit all changes and create tag git add package.json package-lock.json git commit -m "chore: release version $SPECIFIC_VERSION" git tag -a "v$SPECIFIC_VERSION" -m "Version $SPECIFIC_VERSION" fi # Get the final version for pushing the tag FINAL_VERSION=$(grep -o '"version": "[^"]*"' package.json | cut -d'"' -f4) # Push changes and tag to remote echo "Pushing changes and tag to remote..." git push origin main git push origin v$FINAL_VERSION echo "Release process completed for version $FINAL_VERSION" echo "The GitHub workflow will now build and publish the package to npm" echo "Check the Actions tab in your GitHub repository for progress" ================================================ FILE: smithery.yaml ================================================ # Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml startCommand: type: stdio configSchema: # JSON Schema defining the configuration options for the MCP. type: object required: [] properties: contentImageSupported: type: boolean default: true description: Set to true if images should be returned directly in the response. Set to false if images should be saved to disk, requiring 'name' and 'folder' parameters. commandFunction: # A JS function that produces the CLI command based on the given config to start the MCP on stdio. |- (config) => ({ command: 'node', args: ['dist/index.js'], env: { CONTENT_IMAGE_SUPPORTED: config.contentImageSupported ? 'true' : 'false', PUPPETEER_EXECUTABLE_PATH: '/usr/bin/chromium' } }) exampleConfig: contentImageSupported: true ================================================ FILE: tsconfig.json ================================================ { "compilerOptions": { "target": "ES2022", "module": "Node16", "moduleResolution": "Node16", "outDir": "./dist", "rootDir": ".", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["index.ts"] }