GitHub - rtuin/mcp-mermaid-validator: A Model Context Protocol server that validates and renders Mermaid diagrams.
Key Points
- 1This project introduces an MCP server designed to enable Large Language Models to validate and render Mermaid diagrams.
- 2It offers a `validateMermaid` tool that processes diagram syntax, leveraging the Mermaid CLI to perform validation and return valid diagrams as base64-encoded PNGs.
- 3Implemented as a TypeScript Node.js application, it integrates with the Model Context Protocol SDK and utilizes child processes for robust interaction with the Mermaid CLI, emphasizing detailed error handling and PNG output for broad client compatibility.
The mcp-mermaid-validator is a Model Context Protocol (MCP) server designed to enable Large Language Models (LLMs) and MCP-compatible clients to validate and render Mermaid diagrams. It functions as a Node.js application written in TypeScript that integrates with the @mermaid-js/mermaid-cli tool.
The core methodology of the server revolves around its interaction with the Mermaid CLI via Node.js child processes. When a Mermaid diagram is submitted for validation and rendering, the server initiates a child process that executes the mermaid-cli. The Mermaid diagram syntax is passed to the CLI via its standard input (stdin), utilizing '-' as a portable indicator for stdin across different operating systems (Linux, macOS, WSL, Windows). The CLI then processes the diagram, validating its syntax and, if valid, rendering it into a PNG image. The server captures the output from the CLI's standard output (stdout) and standard error (stderr). For successful rendering, the PNG image data received from stdout is base64-encoded. In case of validation failures or system errors, error messages and detailed outputs are captured from stderr. This child process approach ensures isolation between the main application and the rendering process, facilitates detailed error capture, and manages the rendering pipeline efficiently.
The application exposes its functionality through the MCP by registering a single tool named validateMermaid.
This tool accepts one parameter:
diagram(string): The Mermaid diagram syntax to be validated and rendered.
The validateMermaid tool returns a structured JSON object as its output, varying based on the outcome:
Success Return Value:
If the Mermaid diagram is valid and successfully rendered, the tool returns a JSON object with a content array:
{
"content": [
{
"type": "text",
"text": "Mermaid diagram is valid"
},
{
"type": "image",
"data": "[Base64-encoded PNG data]",
"mimeType": "image/png"
}
]
}Here,
data contains the base64-encoded binary data of the rendered PNG image, and mimeType specifies image/png.Failure Return Value:
If the Mermaid diagram is invalid or a system error occurs during processing, the tool returns a JSON object with a content array detailing the error:
{
"content": [
{
"type": "text",
"text": "Mermaid diagram is invalid"
},
{
"type": "text",
"text": "[Descriptive error message]"
},
{
"type": "text",
"text": "[Detailed error output from CLI (if available)]"
}
]
}This structure provides a high-level error message, a more specific error description, and optionally, the raw output from the Mermaid CLI's
stderr for comprehensive debugging. Error handling includes a nested try-catch structure to differentiate between diagram syntax errors and internal system issues, ensuring robust service stability.Key technical decisions include adopting the MCP for standardized AI tool integration, utilizing PNG as the output format for broad client compatibility (especially with clients like Cursor which do not support SVG), and employing Node.js child processes for interacting with the Mermaid CLI. The project uses external libraries such as @modelcontextprotocol/sdk for MCP integration, @mermaid-js/mermaid-cli for core validation/rendering, and zod for schema validation, with typescript, eslint, and prettier as development dependencies. The server communicates via standard input/output, making it suitable for integration with MCP clients, and can be built and run using standard npm scripts.