MCP Server: Mermaid Validator

这是一个使用Model Context Protocol（MCP）的服务器，用于验证并渲染Mermaid图表。此服务器使LLMs能够验证并渲染Mermaid图表。

使用方法

快速开始

你可以通过在mcp服务器文件中添加以下内容来配置你的MCP客户端以使用Mermaid Validator：

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

架构

高级架构

该项目被设计为一个简单的TypeScript Node.js应用程序，其结构如下：

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

代码结构

mcp-mermaid-validator/
├── dist/                   # 编译后的JavaScript输出
│   └── main.js             # 编译后的主应用
├── src/                    # TypeScript源代码
│   └── main.ts             # 主应用入口点
├── node_modules/           # 依赖项
├── package.json            # 项目依赖项和脚本
├── package-lock.json       # 依赖项锁定文件
├── tsconfig.json           # TypeScript配置
├── eslint.config.js        # ESLint配置
├── .prettierrc             # Prettier配置
└── README.md               # 项目文档

组件功能

MCP服务器（主要组件）

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

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

数据流

1. 输入：作为字符串的Mermaid图表语法。
2. 处理：
   • 将图表通过标准输入传递给Mermaid CLI。
   • CLI验证语法并在有效时渲染PNG。
   • 捕获来自标准输出和标准错误的输出和错误。
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图表有效" 
      },
      {
        type: "image", 
        data: string, // base64编码的PNG
        mimeType: "image/png"
      }
    ]
  }
  

• 失败：

  {
    content: [
      { 
        type: "text", 
        text: "Mermaid图表无效" 
      },
      {
        type: "text",
        text: string // 错误消息
      },
      {
        type: "text",
        text: string // 详细的错误输出（如果有）
      }
    ]
  }
  

技术决策

1. MCP集成：项目使用Model Context Protocol标准化AI工具接口，允许与兼容客户端无缝集成。
2. PNG输出格式：实现使用PNG作为默认输出格式，确保与大多数MCP客户端更好的兼容性，特别是Cursor，它不支持SVG。
3. 子进程方法：实现使用Node.js子进程与Mermaid CLI交互，这提供了：
   • 主应用与渲染过程之间的隔离。
   • 能够捕获详细的错误信息。
   • 正确处理渲染流水线。
4. 错误处理策略：实现使用嵌套的try-catch结构来：
   • 区分验证错误（无效的图表语法）和系统错误。
   • 提供详细的错误信息帮助用户修复他们的图表。
   • 即使在处理无效输入时也能确保服务稳定运行。
5. 简单的项目结构：项目使用简单的TypeScript项目结构，便于维护和理解，直接管理依赖项，简化构建过程。

构建和执行

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

# 安装依赖项
npm install

# 构建应用程序
npm run build

# 本地运行（开发）
npx @modelcontextprotocol/inspector node dist/main.js

# 格式化代码
npm run format

# 检查代码
npm run lint

# 监视更改（开发）
npm run watch

应用程序作为一个MCP服务器运行，通过标准输入/输出通信，使其适合与兼容MCP的客户端集成。

发布

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

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