Mermaid MCP Server

Mermaid MCP 服务

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

这是一个精简的 Python 封装，基于 https://github.com/mermaid-js/mermaid-cli，让你开箱即用地使用该工具。

概览

用于验证 Mermaid 图表，并可选择将其渲染为 PNG 图片的 Python MCP 服务。它使用 Mermaid CLI 工具执行验证和渲染。

该服务向大模型提供结构化的验证结果，包括：

• 布尔验证状态（is_valid: true/false），用于指示 Mermaid 图表语法是否正确
• 详细的错误消息，在验证失败时准确说明出错原因（例如语法错误、不支持的图表类型或格式错误的节点）
• 可选的 base64 编码 PNG 图片，用于直观验证成功渲染的图表

这样，大模型便可通过编程方式验证 Mermaid 图表语法，了解具体错误以提供有用的修正，并可选择接收渲染结果的视觉确认。

此外，还提供一个简单的 Pydantic-AI MCP 客户端，可使用 Gemini 模型调用 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"],
    }
  }
}

配置选项

• command：使用 uv 运行服务
• args：使用 uv run 运行服务脚本
• cwd：设置为已克隆仓库的绝对路径
• env：服务的环境变量
  • 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 的使用，隐藏了复杂的文件处理和命令行参数：

不使用封装（直接使用 mermaid-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. Puppeteer 配置：自动生成无头浏览器渲染所需的沙箱配置
4. 错误处理：捕获并返回结构化的错误消息，而不是原始 stderr 输出
5. 命令构建：构建包含所有必要标志的完整 npx @mermaid-js/mermaid-cli 命令
6. 资源清理：确保处理后妥善删除所有临时文件

该封装让用户可以专注于图表验证和渲染，而不必处理底层文件系统操作和命令行的复杂性。

本地开发

此仓库可独立使用，以通过编程方式测试 Mermaid MCP 验证器的功能。

要求

所需依赖项（Node.js、Mermaid CLI 和 Python 与 uv）请参见上文的先决条件部分。

快速设置（推荐）

使用提供的 Makefile 简化设置：

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

# Run validation tests
make test

手动设置

如果你更倾向于手动设置：

1. 克隆此仓库
2. 安装依赖项：uv sync
3. 安装 Mermaid CLI：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（必需）：要验证的 Mermaid 图表文本
• 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 服务的功能。