AI导哈

Mermaid图表验证器

MCP服务器，用于验证和渲染Mermaid图表，使LLMs能够验证和渲染Mermaid图表。

  • by rtuin
  • JavaScript
  • 本地部署
  • 57 星标
  • 更新于
在 GitHub 查看 rtuin/mcp-mermaid-validator

使用说明

MCP服务器：Mermaid验证器

验证和呈现的模型上下文协议服务器 美人鱼 图表。此服务器使LLM能够验证和渲染Mermaid图。

用法

快速开始

您可以将MCP客户端配置为使用Mermaid验证器，方法是将其添加到MCP服务器文件中：

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

建筑

高级体系结构

这个项目的结构是一个简单的TypeScript Node.js应用程序，它：

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

数据流

  1. 输入：字符串形式的美人鱼图语法
  2. 处理:
    • 该图通过stdin传递给Mermaid CLI
    • CLI验证语法，并在有效的情况下呈现PNG
    • 从stdout/stderr捕获输出和错误
  3. 输出:
    • 成功：文本确认+将PNG渲染为base64编码图像
    • 失败：包含验证失败详细信息的错误消息

依赖项

外部库

  • @模型上下文协议/sdk：用于实现模型上下文协议的SDK
  • @美人鱼js/美人鱼cli：用于验证和渲染Mermaid图的CLI工具
  • 黄道带：TypeScript的模式验证库

发展依赖性

  • TypeScript：TypeScript编译器
  • 埃斯林特：Linting实用程序
  • 更漂亮：代码格式

API规范

validateMermaid工具

目的：验证美人鱼图，如果有效，则返回渲染的PNG

参数:

  • diagram （string）：美人鱼图语法验证

返回值:

  • 成功：
    {
  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集成：该项目使用模型上下文协议来标准化人工智能工具的接口，允许与兼容客户端无缝集成。

  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

故障排除

  • WSL/Windows stdin：早期版本调用Mermaid CLI /dev/stdin，这可能会在WSL上失败 ENXIO。此服务器现在使用 - 用于标准输入/标准输出(-i - / -o -)可在Linux/MOSC/WSL/Windows上移植。
  • 检查器工作目录：通过MCP检查器启动时，确保服务器路径解析（例如。 npx @modelcontextprotocol/inspector npx -y @rtuin/mcp-mermaid-validator@latest 或使用绝对路径 dist/main.js).

相关 MCP