Mermaid Validator

MCP Server：Mermaid 验证器

一个用于验证和渲染 Mermaid 图表的 Model Context Protocol 服务。此服务可让大模型验证和渲染 Mermaid 图表。

用法

快速开始

你可以将 Mermaid Validator 添加到 mcp servers 文件中，以配置 MCP 客户端使用它：

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

架构

高层架构

此项目采用简单的 TypeScript Node.js 应用结构：

1. 主应用：一个用于验证 Mermaid 图表并返回渲染后 PNG 输出的 Node.js 服务
2. MCP 集成：使用 Model Context Protocol SDK 向兼容 MCP 的客户端公开功能
3. Mermaid CLI 集成：利用 Mermaid CLI 工具验证和渲染图表

代码结构

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

组件功能

MCP 服务（主要组件）

核心功能在 src/main.ts 中实现。此组件：

1. 创建 MCP 服务实例
2. 注册一个接受 Mermaid 图表语法的 validateMermaid 工具
3. 使用 Mermaid CLI 验证并渲染图表
4. 返回验证结果和渲染后的 PNG（如果有效）
5. 使用恰当的错误消息处理错误情况

数据流

1. 输入：作为字符串的 Mermaid 图表语法
2. 处理：
   • 通过 stdin 将图表传递给 Mermaid CLI
   • CLI 验证语法，并在语法有效时渲染 PNG
   • 从 stdout/stderr 捕获输出和错误
3. 输出：
   • 成功：文本确认信息 + 以 base64 编码的渲染后 PNG 图像
   • 失败：包含验证失败详情的错误消息

依赖项

外部库

• @modelcontextprotocol/sdk：用于实现 Model Context Protocol 的 SDK
• @mermaid-js/mermaid-cli：用于验证和渲染 Mermaid 图表的 CLI 工具
• zod：TypeScript 的模式验证库

开发依赖项

• typescript：TypeScript 编译器
• eslint：代码检查工具
• prettier：代码格式化工具

API 规范

validateMermaid 工具

用途：验证 Mermaid 图表，并在有效时返回渲染后的 PNG

参数：

• diagram（string）：要验证的 Mermaid 图表语法

返回值：

• 成功：

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

• 失败：

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

技术决策

1. MCP 集成：项目使用 Model Context Protocol 标准化 AI 工具的接口，从而与兼容的客户端无缝集成。

2. PNG 输出格式：实现默认使用 PNG 作为输出格式，以确保与大多数 MCP 客户端更好地兼容，尤其是 Cursor，因为它不支持 SVG。

3. 子进程方案：实现使用 Node.js 子进程与 Mermaid CLI 交互，具有以下优点：

   • 隔离主应用与渲染进程
   • 能够捕获详细的错误信息
   • 妥善处理渲染流程

4. 错误处理策略：实现采用嵌套的 try-catch 结构，以便：

   • 区分验证错误（图表语法无效）和系统错误
   • 提供详细的错误信息，帮助用户修复图表
   • 即使处理无效输入，也能确保服务保持稳定

5. 简单的项目结构：项目采用直观的 TypeScript 项目结构，便于：

   • 轻松维护和理解
   • 直接管理依赖项
   • 简化构建流程

构建和运行

可以使用 npm 脚本构建和运行应用：

# 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

应用作为 MCP 服务运行，并通过标准输入/输出通信，因此适合与兼容 MCP 的客户端集成。

发布

要发布新版本，请按顺序执行以下步骤：

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

故障排除

• WSL/Windows 标准输入：早期版本使用 /dev/stdin 调用 Mermaid CLI，这在 WSL 上可能因 ENXIO 而失败。此服务现在使用 - 处理标准输入/标准输出（-i - / -o -），以兼容 Linux/macOS/WSL/Windows。
• Inspector 工作目录：通过 MCP Inspector 启动时，请确保服务路径可解析（例如，npx @modelcontextprotocol/inspector npx -y @rtuin/mcp-mermaid-validator@latest，或使用 dist/main.js 的绝对路径）。