The

mermaider MCP 服务：快速、可靠的 Mermaid 图表语法检查器

目录

• mermaider MCP 服务：快速、可靠的 Mermaid 图表语法检查器
  • 概述
    • 为什么要使用浏览器？
  • 大模型的语法问题
  • mermaider 有何不同？
  • 安装
    • VSCode
    • Cursor/Windsuf/...
    • Bun
  • 建议
  • 使用示例
  • 参考资料
    • 其他与 Mermaid 相关的 MCP 服务
    • 许可证

概述

mermaider 是一个 MCP 服务，提供 validate_syntax 工具，用于检查所有类型的 Mermaid 图表是否存在语法错误。

为此，它直接使用 puppeteer-core package 和 mermaid-js/mermaid API，高效地调用已安装的 Chrome 内核或 Firefox 浏览器。

高效意味着：

• 只要此 MCP 服务进程处于活动状态，浏览器（打开一个新页面）就会以无头模式（默认）启动并保持运行，从而实现低延迟的工具调用。
• 每次调用 validate_syntax 工具时，都会复用浏览器和页面。

为什么要使用浏览器？

遗憾的是，mermaid-js/mermaid 的功能依赖完整的浏览器上下文（DOM），即使只是解析图表也是如此。像 happy-dom 或 jsdom 这样的 package 并不完全够用。

mermaider 使用相对轻量的 puppeteer-core package（而非完整的 puppeteer）来访问已安装的浏览器。

大模型的语法问题

现代大模型通常完全能够生成 Mermaid 图表，但往往缺乏可靠检查所生成语法的能力。这正是 mermaider MCP 发挥作用的地方。

mermaider 有何不同？

还有其他 MCP 服务 可以（在一定程度上）验证 Mermaid 语法，不过它们通常会在每次（由大模型）调用相应工具时启动 mmdc 命令行工具进程。

这会带来几个问题：

• 速度：每次调用工具都启动 mmdc 进程（随后它还会启动浏览器），既慢又耗费资源。

• 非确定性：mmdc 的真正用途是生成图像，而非验证语法。因此，对于语法错误的图表，它偶尔会以 0 代码退出并生成图像（如下图所示），而不是以非零代码退出并向 STDERR 输出错误消息。在这种情况下，使用 mmdc 的 MCP 服务无从得知发生了错误，因此你最终会得到一堆这样的图像，而不是图表。

  

• 副作用：mmdc 可能会在你不知情的情况下安装 Chrome 浏览器，因为这是 puppeteer 的默认行为，引用如下：

  安装 Puppeteer 时，它会自动下载一个较新的 Chrome for Testing 版本（macOS 约 170MB、Linux 约 282MB、Windows 约 280MB），以及一个 chrome-headless-shell 二进制文件（从 Puppeteer v21.6.0 开始），并保证其可与 Puppeteer 配合使用。默认情况下，浏览器会下载到 $HOME/.cache/puppeteer 文件夹（从 Puppeteer v19.0.0 开始）。请参阅配置，了解可用于控制下载行为的配置选项和环境变量。

安装

通常，MCP 客户端应使用以下命令：

npx -y @vtomilin/mermaider <config>

其中，<config> 可以是内联 JSON 字符串，也可以是配置文件路径，例如：

npx -y @vtomilin/mermaider '{"executablePath": "/Applications/FirefoxDeveloperEdition.app/Contents/MacOS/firefox", "browser": "firefox"}'

或者：

npx -y @vtomilin/mermaider /home/user/etc/Firefox.json

其中，/home/user/etc/Firefox.json 是一个 JSON 文件，包含配置，例如 Firefox 浏览器的配置：

{
  "executablePath": "/Applications/FirefoxDeveloperEdition.app/Contents/MacOS/firefox",
  "browser": "firefox"
}

另一个配置文件示例，使用 Brave（基于 Chrome）浏览器：

{
  "executablePath": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
}

Puppeteer 的浏览器 Launchoptions 中定义的所有可用配置选项。

VSCode

按下 Cmd-Shift-P（或 Ctrl-Shift-P），然后选择 MCP: Add Server...。选择 Command (stdio) Run a local command that implements the MCP protocol。输入 npx -y @vtomilin/mermaider /home/user/etc/Firefox.json（或其他配置方式）。输入服务名称（mermaider）。然后就可以开始使用了。

Cursor/Windsuf/...

{
  "mcpServers": {
    "mermaider": {
      "command": "npx",
      "args": ["-y", "@vtomilin/mermaider", "/home/user/etc/Firefox.json"]
    }
  }
}

Bun

尽管此项目使用 Bun 构建，但目前无法直接通过 bunx 运行 mermaider 包。你需要先使用 bun add -g @vtomilin/mermaider 全局安装该包。之后可以直接使用 mermaider-bun 可执行文件运行服务：

{
  "mcpServers": {
    "mermaider": {
      "command": "mermaider-bun",
      "args": ["/home/user/etc/Firefox.json"]
    }
  }
}

建议

• 查看 Puppeteer 支持的浏览器列表，了解支持的浏览器。
• 为 mermaider MCP 使用备用浏览器。请勿使用你的主浏览器。

使用示例

使用 VSCode 中的 Github Copilot 的示例会话：

• 生成图表并使用 mermaider 检查其语法：

• 生成有意损坏的图表并使用 mermaider 检查其语法：

参考

其他与 Mermaid 相关的 MCP 服务

• mcp-mermaid-validator：一个用于验证和渲染 Mermaid 图表的模型上下文协议服务。
• mermaid-mcp-server：一个提供工具以验证和渲染 Mermaid 图表的模型上下文协议（MCP）服务。

许可证

MIT