MCP Mermaid Validator Extended

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捕获输出和错误

1. 输出:

- 成功：文本确认+将PNG渲染为base64编码图像 - 失败：包含验证失败详细信息的错误消息

依赖项

外部库

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

发展依赖性

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

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

1. 儿童过程方法：该实现使用Node.js子进程与Mermaid CLI交互，后者提供：

- 主应用程序和渲染过程之间的隔离 - 能够捕获详细的错误信息 - 正确处理渲染管道

1. 错误处理策略：该实现使用嵌套的try-catch结构来：

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

1. 项目结构简单：该项目使用简单的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).