mcp-mermaid-validator

MCP 服务器：美人鱼验证器

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

用法

快速入门

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

建筑学

高级架构

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

1. 主要应用：一个 Node.js 服务，用于验证美人鱼图表并返回渲染的 PNG 输出
2. MCP 集成：使用模型上下文协议 SDK 向 MCP 兼容客户端公开功能
3. Mermaid CLI 集成：利用 Mermaid CLI 工具执行图表验证和渲染

代码结构

组件功能

MCP 服务器（主要组件）

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

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

数据流

1. 输入：美人鱼图语法作为字符串
2. 加工：
   • 该图通过 stdin 传递给 Mermaid CLI
   • CLI 验证语法，如果有效则渲染 PNG
   • 从 stdout/stderr 捕获输出和错误
3. 输出：
   • 成功：文本确认+渲染 PNG 作为 base64 编码图像
   • 失败：包含验证失败详细信息的错误消息

依赖项

外部库

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

开发依赖项

• typescript ：TypeScript 编译器
• eslint ：Lint 实用程序
• Prettier ：代码格式化

API 规范

验证美人鱼工具

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

参数：

• diagram （字符串）：要验证的美人鱼图语法

返回值：

• 成功：
  { 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 客户端（尤其是不支持 SVG 的 Cursor）更好地兼容。
3. 子进程方法：该实现使用 Node.js 子进程与 Mermaid CLI 交互，它提供：
   • 主应用程序与渲染进程之间的隔离
   • 能够捕获详细的错误信息
   • 正确处理渲染管道
4. 错误处理策略：实现使用嵌套的try-catch结构来：
   • 区分验证错误（无效图表语法）和系统错误
   • 提供详细的错误信息以帮助用户修复他们的图表
   • 确保即使在处理无效输入时服务仍然保持稳定
5. 简单的项目结构：该项目使用简单的 TypeScript 项目结构来：
   • 易于维护和理解
   • 直接依赖管理
   • 简化的构建过程

构建和执行

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

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

发布

要发布新版本，请按以下步骤操作：

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