📌Overview

Purpose: To provide a server that validates and renders Mermaid diagrams for seamless integration with LLMs and other tools.

Overview: The MCP Server: Mermaid Validator is a TypeScript Node.js application designed to validate Mermaid diagrams and generate SVG outputs. It integrates with the Model Context Protocol (MCP) to offer a standardized interface for diagram validation and rendering.

Key Features:

• MCP Integration: Seamlessly exposes functionality to MCP-compatible clients, allowing for easy integration and communication with various applications.

• Diagram Validation and Rendering: Utilizes the Mermaid CLI to validate Mermaid syntax and produce rendered SVG images, ensuring that diagrams are correctly formatted and visually accurate.

• Error Handling: Implements robust error handling to provide detailed feedback on validation failures, aiding users in troubleshooting and correcting their diagrams.

---

MCP Server: Mermaid Validator

A Model Context Protocol server that validates and renders Mermaid diagrams. This server enables LLMs to validate and render Mermaid diagrams.

Usage

Quick Start

Configure your MCP client to use the Mermaid Validator by adding it to your MCP servers file:

{
  "mcpServers": {
    "mermaid-validator": {
      "command": "npx",
      "args": [
        "-y",
        "@rtuin/mcp-mermaid-validator"
      ]
    }
  }
}

Architecture

High-Level Architecture

This project is a simple TypeScript Node.js application that:

1. Runs a Node.js service to validate Mermaid diagrams and return rendered SVG output.
2. Uses the Model Context Protocol SDK to expose functionality to MCP-compatible clients.
3. Leverages the Mermaid CLI tool to perform diagram validation and rendering.

Code Structure

mcp-mermaid-validator/
├── dist/                   # Compiled JavaScript output
│   └── main.js             # Compiled main application
├── src/                    # TypeScript source code
│   └── main.ts             # Main application entry point
├── node_modules/           # Dependencies
├── package.json            # Project dependencies and scripts
├── package-lock.json       # Dependency lock file
├── tsconfig.json           # TypeScript configuration
├── eslint.config.js        # ESLint configuration
├── .prettierrc             # Prettier configuration
└── README.md               # Project documentation

Component Functionality

MCP Server (Main Component)

Implemented in src/main.ts. This component:

1. Creates an MCP server instance.
2. Registers a validateMermaid tool accepting Mermaid diagram syntax.
3. Uses the Mermaid CLI to validate and render diagrams.
4. Returns validation results and rendered SVG (if valid).
5. Handles errors with appropriate messages.

Data Flow

1. Input: Mermaid diagram syntax as a string.
2. Processing:
   • Passes the diagram to the Mermaid CLI via stdin.
   • CLI validates the syntax and renders an SVG if valid.
   • Captures output and errors from stdout/stderr.
3. Output:
   • Success: Confirmation text + rendered SVG as base64-encoded PNG.
   • Failure: Error message with validation failure details.

Dependencies

External Libraries

• @modelcontextprotocol/sdk: SDK for implementing Model Context Protocol.
• @mermaid-js/mermaid-cli: CLI tool for validating and rendering Mermaid diagrams.
• zod: Schema validation library for TypeScript.

Development Dependencies

• typescript: TypeScript compiler.
• eslint: Linting utility.
• prettier: Code formatting.

API Specification

validateMermaid Tool

Purpose: Validates a Mermaid diagram and returns the rendered SVG if valid.

Parameters:

• diagram (string): The Mermaid diagram syntax to validate.

Return Value:

• Success:

  {
    content: [
      { 
        type: "text", 
        text: "Mermaid diagram is valid" 
      },
      {
        type: "image", 
        data: string, // Base64-encoded PNG
        mimeType: "image/png"
      }
    ]
  }
  

• Failure:

  {
    content: [
      { 
        type: "text", 
        text: "Mermaid diagram is invalid" 
      },
      {
        type: "text",
        text: string // Error message
      },
      {
        type: "text",
        text: string // Detailed error output (if available)
      }
    ]
  }
  

Technical Decisions

1. MCP Integration: Uses the Model Context Protocol to standardize AI tool interfaces for seamless client integration.
2. PNG Output Format: Uses PNG as the default output format for better compatibility with MCP clients, especially Cursor which doesn't support SVG.
3. Child Process Approach: Uses Node.js child processes to interact with the Mermaid CLI, providing isolation, detailed error capturing, and proper rendering handling.
4. Error Handling Strategy: Implements nested try-catch blocks to distinguish validation errors from system errors, provide detailed feedback, and maintain service stability.
5. Simple Project Structure: Straightforward TypeScript project structure for easy maintenance, clear dependencies, and a simplified build process.

Build and Execution

Use the following npm scripts:

# Install dependencies
npm install

# Build the application
npm run build

# Run locally (for development)
npx @modelcontextprotocol/inspector node dist/main.js

# Format code
npm run format

# Lint code
npm run lint

# Watch for changes (development)
npm run watch

The application runs as an MCP server communicating via standard input/output, suitable for MCP-compatible clients.

Release

To release a new version, run:

• npm run build
• npm run bump
• npm run changelog
• npm publish --access public