Mermaid MCP Server

用于验证Mermaid图表的Model Context Protocol (MCP)服务器。

实现了一个最小的Python封装，基于https://github.com/mermaid-js/mermaid-cli，以便更简单地开箱即用。

概述

这是一个用于验证Mermaid图表并可选地将其渲染为PNG图像的Python MCP服务器。它使用Mermaid CLI工具进行验证和渲染。

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

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

这使得LLMs能够程序化地验证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服务器）

快速依赖设置

# 全局安装Mermaid CLI
npm install -g @mermaid-js/mermaid-cli

# 验证安装
npx @mermaid-js/mermaid-cli --version

快速入门

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

注意：确保已安装Node.js和Mermaid CLI（参见预备条件）后再配置MCP服务器。

配置格式

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_m_服务器.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
      }
    }
  }
}

对Mermaid-CLI的抽象

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

不使用封装（原始mermaid-cli）：

# 创建输入文件
echo "graph TD; A-->B" > diagram.mmd

# 创建puppeteer配置文件
echo '{"args": ["--no-sandbox", "--disable-setuid-sandbox"]}' > puppeteer-config.json

# 使用多个参数运行mermaid-cli
npx @mermaid-js/mermaid-cli -i diagram.mmd -o output.png --puppeteerConfigFile puppeteer-config.json

# 处理输出文件并清理

使用Python封装：

# 带有图表文本的简单函数调用
result = await validate_mermaid_diagram("graph TD; A-->B")

# 所有文件处理、配置和清理都是自动的
# 返回带有验证状态和base64编码图像的结构化结果

关键抽象：

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

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

本地开发

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

要求

参见上面的预备条件部分，了解所需依赖项（Node.js、Mermaid CLI和带有uv的Python）。

快速设置（推荐）

使用提供的Makefile进行流线型设置：

# 安装所有依赖项（Python + Node.js + Mermaid CLI）
make install

# 运行验证测试
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：仅当您特别需要渲染图像数据时使用。警告：这将消耗大量上下文长度。

示例用法

# 仅验证（大多数情况下的推荐做法）
result = await validate_mermaid_diagram("graph TD; A-->B")
# 返回：MermaidValidationResult(is_valid=True, error_message=None, diagram_image=None)

# 验证并带图像（谨慎使用）
result = await validate_mermaid_diagram("graph TD; A-->B", return_image=True)
# 返回：MermaidValidationResult(is_valid=True, error_message=None, diagram_image="iVBORw0KGgoAAAANSUhEUg...")

测试

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

# 运行所有测试
make test

# 或直接运行测试脚本
uv run test_pydantic.py

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