MCP Server: Mermaid 验证器

一个模型上下文协议服务器，用于验证和渲染 Mermaid 图表。 此服务器使 LLM 能够验证和渲染 Mermaid 图表。

用法

快速开始

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

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

架构

高级架构

此项目被构建为一个简单的 TypeScript Node.js 应用程序，它：

1. 主应用程序：一个 Node.js 服务，用于验证 Mermaid 图表并返回渲染的 SVG 输出
2. MCP 集成：使用模型上下文协议 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. 注册一个 validateMermaid 工具，该工具接受 Mermaid 图表语法
3. 使用 Mermaid CLI 验证和渲染图表
4. 返回验证结果和渲染的 SVG（如果有效）
5. 使用适当的错误消息处理错误情况

数据流

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

依赖项

外部库

• @modelcontextprotocol/sdk: 用于实现模型上下文协议的 SDK
• @mermaid-js/mermaid-cli: 用于验证和渲染 Mermaid 图表的 CLI 工具
• zod: 用于 TypeScript 的模式验证库

开发依赖项

• typescript: TypeScript 编译器
• eslint: Linting 实用程序
• 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 // Error message
      },
      {
        type: "text",
        text: string // Detailed error output (if available)
      }
    ]
  }
  

技术决策

1. MCP 集成：该项目使用模型上下文协议来标准化 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

# Lint 代码
npm run lint

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

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

发布

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

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