MERMAID-MCP-APP

Mermaid MCP 应用

一个可流式处理的 MCP 应用服务，可渲染交互式 Mermaid 图表，支持实时预览、主题切换和全屏编辑。

演示

交互式图表编辑，支持实时预览、平移/缩放控制和全屏模式

功能特性

• 完整渲染 - 等待图表完全生成后再显示（无部分/流式输出）
• SVGO 优化 - 自动 SVG 优化可减少文件大小约 85%
• 深色模式 - 自动检测系统主题并使用中性灰色调色板
• 交互式平移/缩放 - 使用滚轮缩放和拖动控制来浏览大型图表
• 全屏编辑器 - 使用实时预览和缩放控制（+/−/1:1）编辑 Mermaid 语法
• 主题切换 - 浅色、深色或自定义（Agent 提供）主题
• 所有图表类型 - 流程图、序列图、类图、状态图、ER 图、甘特图、饼图、Git 图等
• 导出加载指示器 - 将 SVGO 优化的 SVG 复制到剪贴板（加载指示器显示进度）
• 客户端渲染 - 无服务器依赖，完全在浏览器中运行

快速开始

远程（Vercel）

使用托管端点：https://mermaid-mcp-app.vercel.app/mcp

在客户端中添加为远程 MCP 服务。例如，在 claude.ai 中：Settings（设置）→ Connectors（连接器）→ Add custom connector（添加自定义连接器）→ 粘贴上述 URL。

安装

npm install

开发

使用热重载启动开发服务器：

npm run dev

服务器将在 http://localhost:3001/mcp 启动

构建

为生产环境构建：

npm run build

这会创建：

• dist/mcp-app.html - 单文件捆绑 UI
• dist/server.js - MCP 服务
• dist/index.js - CLI 入口点

使用方法

本地（HTTP）

npm run serve
# or
node dist/index.js

本地（stdio）

node dist/index.js --stdio

Vercel 部署

部署到 Vercel 以实现远程访问：

npx vercel

MCP 端点将在 https://mermaid-mcp-app.vercel.app/mcp 可用

MCP 工具

read_me

返回包含所有图表类型示例的综合 Mermaid 语法参考。

使用方法：在调用 create_view 之前调用此工具来了解 Mermaid 语法。

create_view

渲染 Mermaid 图表。图表完全渲染后才会显示（无渐进式/流式渲染）。

参数：

• mermaid（字符串，必需）- Mermaid 图表语法
• theme（字符串，可选）- 以下之一：default（自动检测）、forest、dark、neutral、base
• title（字符串，可选）- 在图表上方显示的标题

注意：

• 默认主题自动检测系统深色模式并应用中性灰色调色板
• Agent 可指定内置 Mermaid 主题（forest、dark、neutral、base），这些在 UI 中显示为"Custom"（自定义）
• 全屏模式包括缩放控制（+、−、1:1、滚轮缩放）和平移/拖动

示例：

{
  "mermaid": "flowchart TD\n  A[Start] --> B[End]",
  "theme": "forest",
  "title": "Simple Flow"
}

export_svg（仅应用）

使用 SVGO 导出渲染的图表为优化的 SVG。由 UI 导出按钮（处理时显示加载指示器）调用。

优化：

• SVGO 可减少 SVG 大小约 85%（例如，334KB → 51KB）
• 将坐标四舍五入到 2 位小数
• 保留 viewBox 和 mermaid ID 以确保正确渲染

架构

• 服务：带有 Express + MCP SDK 的 Node.js
  • 支持 Streamable HTTP 和 stdio 传输
  • 无状态的按请求设计（无会话）
• UI：React 19 与 Mermaid.js
  • 通过 importmap 从 CDN 加载（Mermaid 使用 jsdelivr，React 使用 esm.sh）
  • 客户端渲染以实现零服务器依赖
  • 通过 Vite + vite-plugin-singlefile 的单文件 HTML 捆绑（~402KB）
  • 导出的 SVGO 服务器端优化
• 构建：TypeScript + Vite + Bun
  • 类型安全的服务器和客户端代码
  • 优化的生产捆绑

文件结构

mermaid-mcp-app/
├── src/
│   ├── server.ts          # MCP server with tool registration + SVGO
│   ├── main.ts            # Transport layer (HTTP + stdio)
│   ├── mcp-app.html       # HTML shell with importmap
│   ├── mcp-app.tsx        # React UI component
│   ├── theme-vars.ts      # Mermaid theme color palettes
│   └── global.css         # Styles (dark mode, animations)
├── api/
│   └── mcp.ts            # Vercel serverless handler
├── dist/                  # Build output
├── scripts/
│   └── setup-bun.mjs     # Auto-install bun
├── package.json
├── tsconfig.json          # Client TS config
├── tsconfig.server.json   # Server TS config
├── vite.config.ts         # Vite bundler config
├── vercel.json           # Vercel deployment config
└── manifest.json         # MCP app manifest

技术栈

• MCP SDK - Model Context Protocol
• ext-apps - MCP Apps 扩展
• Mermaid.js - 图表生成
• SVGO - SVG 优化（服务器端）
• React 19 - UI 框架
• Vite - 构建工具
• TypeScript - 类型安全
• Bun - 构建打包工具

许可证

MIT