AI导哈

Mermaid图表验证服务器

用于验证Mermaid图表语法的Python服务器，提供结构化验证结果和可选渲染功能。

  • by andrewginns
  • Python
  • 本地部署
  • 11 星标
  • 更新于
在 GitHub 查看 andrewginns/mermaid-mcp-server

使用说明

Mermaid MCP服务器

用于验证Mermaid图的模型上下文协议（MCP）服务器。

在上面实现一个最小的Python包装器https://github.com/mermaid-js/mermaid-cli更简单的开箱即用。

概述

Python MCP服务器，用于验证Mermaid图并（可选）将其渲染为PNG图像。它使用Mermaid CLI工具执行验证和渲染。

服务器为LLM提供结构化验证结果，包括：

  • 布尔验证状态 (is_valid: true/false)指示Mermaid图语法是否正确
  • 详细的错误消息 解释验证失败时到底出了什么问题（例如，语法错误、不支持的图表类型、格式错误的节点）
  • 可选的base64编码PNG图像 用于视觉验证的成功渲染图表

这使LLM能够以编程方式验证Mermaid图语法，了解特定错误以提供有用的更正，并可选择接收渲染输出的视觉确认。

还提供了一个简单的Pydantic AI MCP客户端，用于使用Gemini模型调用MCP服务器进行测试。

先决条件

重要：此MCP服务器要求在您的系统上安装Node.js，即使您只使用服务器组件（而不是客户端）。服务器内部调用 npx @mermaid-js/mermaid-cli 作为执行图表验证和渲染的子流程。

所需依赖关系

  • Node.js 使用npm（所有使用都需要）
  • Mermaid CLI：安装 npm install -g @mermaid-js/mermaid-cli
  • python 带uv（用于运行MCP服务器）

快速依赖设置

# Install Mermaid CLI globally
npm install -g @mermaid-js/mermaid-cli

# Verify installation
npx @mermaid-js/mermaid-cli --version

快速启动

要将此服务器与MCP客户端（如Claude Desktop）一起使用，请将以下配置添加到MCP设置中：

备注：在配置MCP服务器之前，请确保安装了Node.js和Mermaid CLI（请参阅上面的先决条件）。

配置格式

  1. 克隆此存储库

  2. 将其添加到您的MCP客户端配置文件中（例如。， claude_desktop_config.json):

{
  "mcpServers": {
    "mermaid-validator": {
      "command": "uv",
      "args": ["run", "/path/to/mermaid_mcp_server.py"],
    }
  }
}

配置选项

  • 命令：使用 uv 运行服务器
  • 参数：使用以下命令运行服务器脚本 uv run
  • 当前工作目录：设置为克隆存储库的绝对路径
  • 环境：服务器的环境变量
    • MCP_TRANSPORT：设置为 "stdio" 用于标准输入/输出通信

扩展配置示例

{
  "mcpServers": {
    "mermaid-validator": {
      "command": "uv", 
      "args": ["run", "/path/to/mermaid_mcp_server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
      }
    }
  }
}

Mermaid CLI上的摘要

Python包装器通过抽象掉复杂的文件处理和命令行参数，大大简化了Mermaid CLI的使用：

没有包装（原始美人鱼cli）：

# Create input file
echo "graph TD; A-->B" > diagram.mmd

# Create puppeteer config file
echo '{"args": ["--no-sandbox", "--disable-setuid-sandbox"]}' > puppeteer-config.json

# Run mermaid-cli with multiple arguments
npx @mermaid-js/mermaid-cli -i diagram.mmd -o output.png --puppeteerConfigFile puppeteer-config.json

# Handle output file and cleanup

使用Python包装器：

# Simple function call with diagram text
result = await validate_mermaid_diagram("graph TD; A-->B")

# All file handling, configuration, and cleanup is automatic
# Returns structured result with validation status and base64-encoded image

关键摘要：

  1. 临时文件管理：自动创建和清理临时 .mmd 输入文件
  2. 输出文件处理：管理临时 .png 输出文件并将其转换为base64字符串
  3. 木偶配置：自动生成无头浏览器渲染所需的沙盒配置
  4. 错误处理：捕获并返回结构化错误消息，而不是原始stderr输出
  5. 指挥建设：构建完整 npx @mermaid-js/mermaid-cli 带有所有必要标志的命令
  6. 资源清理：确保处理后正确删除所有临时文件

这种抽象允许用户专注于图表验证和呈现，而无需处理底层文件系统操作和命令行复杂性。

地方发展

该存储库可以独立使用，以编程方式测试Mermaid MCP验证器的功能。

需求

请参阅 先决条件 以上部分介绍了所需的依赖关系（Node.js、Mermaid CLI和带uv的Python）。

快速设置（推荐）

使用提供的Makefile简化设置：

# Install all dependencies (Python + Node.js + Mermaid CLI)
make install

# Run validation tests
make test

手动设置

如果您更喜欢手动设置：

  1. 克隆此存储库
  2. 安装依赖项： uv sync
  3. 安装Mermaid命令行界面： npm install -g @mermaid-js/mermaid-cli
  4. 复制 .env.example 向 .env 并填写您的API密钥
  5. 运行服务器： uv run mermaid_mcp_server.py

用法

服务器公开了一个用于验证Mermaid图的工具：

  • validate_mermaid_diagram：验证Mermaid图并返回验证结果

刀具参数

  • diagram_text （必填）：美人鱼图文本验证
  • return_image （可选，默认值： false)：是否返回base64编码的PNG图像

上下文长度优化

重要：默认情况下，该工具不返回base64编码的图像(return_image=false)以保持LLM对话中的上下文长度。Base64编码的图像可能是非常长的字符串（通常为10KB-100KB+），这会显著影响对话的可用上下文。

何时使用每个设置:

  • return_image=false （默认）：仅用于图表验证。快速且上下文高效。
  • return_image=true：仅当您特别需要渲染图像数据时使用。警告：这将消耗大量上下文长度。

示例用法

# Validation only (recommended for most cases)
result = await validate_mermaid_diagram("graph TD; A-->B")
# Returns: MermaidValidationResult(is_valid=True, error_message=None, diagram_image=None)

# Validation with image (use sparingly)
result = await validate_mermaid_diagram("graph TD; A-->B", return_image=True)
# Returns: MermaidValidationResult(is_valid=True, error_message=None, diagram_image="iVBORw0KGgoAAAANSUhEUg...")

测试

该项目包括方便的测试命令：

# Run all tests
make test

# Or run the test script directly
uv run test_pydantic.py

测试脚本使用Pydantic AI和Gemini模型来验证MCP服务器功能。

相关 MCP