MCP Server: Mermaid 验证器

一个用于验证和渲染 Mermaid 图表的 Model Context Protocol 服务器。该服务器使 LLMs 能够验证和渲染 Mermaid 图表。

使用方法

快速开始

您可以通过将 Mermaid 验证器添加到您的 mcp 服务器文件中来配置您的 MCP 客户端使用它：

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

架构

高级架构

该项目结构为一个简单的 TypeScript Node.js 应用程序，包括：

1. 主应用程序：一个 Node.js 服务，用于验证 Mermaid 图表并返回渲染后的 SVG 输出
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. 返回验证结果和渲染后的 SVG（如果有效）
5. 通过适当的错误消息处理错误情况

数据流

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

依赖项

外部库

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

开发依赖项

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

API 规范

validateMermaid 工具

目的：验证 Mermaid 图表，并在有效时返回渲染后的 SVG

参数：

• 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 // 错误消息
      },
      {
        type: "text",
        text: string // 详细的错误输出（如果有）
      }
    ]
  }
  

技术决策

1. MCP 集成: 该项目使用 Model Context Protocol (MCP) 来标准化 AI 工具的接口，允许与兼容的客户端无缝集成。

2. PNG 输出格式: 实现中使用 PNG 作为默认输出格式，以确保与大多数 MCP 客户端（特别是不支持 SVG 的 Cursor）有更好的兼容性。

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