Mermaid Chart MCP Server

一个专注于Mermaid图表渲染的MCP服务器，支持将Mermaid代码渲染为SVG图表。

✨ 特性

🎨 高质量渲染: 基于官方Mermaid库的SVG渲染
🔄 双模式支持: stdio（MCP标准）和SSE（Web测试）
🛡️ 安全性: 输入校验、沙箱环境、CORS配置
📊 多图表类型: 支持流程图、序列图、类图、甘特图等
🚀 高性能: 隔离渲染环境，避免全局污染
💚 健康监控: 内置健康检查和连接管理

🏗️ 项目结构

src/
├── server/
│   ├── index.ts              # 主入口文件
│   ├── simple-mcp-server.ts  # MCP服务器核心逻辑
│   ├── sse-transport.ts      # SSE传输和Web服务器
│   └── utils.ts              # 工具函数（校验、清理等）
├── package.json
├── tsconfig.json
├── tsup.config.ts            # 构建配置
└── README.md

🚀 快速开始

安装依赖

pnpm install

开发模式

# stdio模式（用于MCP客户端）
pnpm run start:dev

# SSE模式（用于Web测试）
pnpm run start:dev:sse

# 指定端口的SSE模式
pnpm run start:dev:sse -- --port=3001

构建和运行

# 构建项目
pnpm run build

# 运行构建后的项目
pnpm start                  # stdio模式
pnpm run start:sse          # SSE模式
pnpm run start:sse:port     # SSE模式（端口3001）

🔍 调试和测试

推荐使用官方的 MCP Inspector 进行调试和测试：

# 使用 MCP Inspector 调试服务器
npx @modelcontextprotocol/inspector node dist/server/index.js

# 或者在开发模式下
npx @modelcontextprotocol/inspector node --loader ts-node/esm src/server/index.ts

MCP Inspector 提供了强大的可视化界面，支持：

🎨 交互式工具测试
📊 实时请求/响应监控
🔧 参数配置和验证
📋 完整的API探索

🛠️ 可用工具

1. render_mermaid_to_svg

将Mermaid代码渲染为SVG图表。

参数:

mermaidCode (string, 必需): Mermaid图表代码
title (string, 可选): 图表标题，默认"Mermaid图表"
theme (string, 可选): 主题，可选值: default, dark, forest, neutral
createTempFile (boolean, 可选): 是否创建临时SVG文件，默认true

示例:

{
  "mermaidCode": "graph TD\n    A[开始] --> B[结束]",
  "title": "简单流程图",
  "theme": "dark",
  "createTempFile": true
}

2. validate_mermaid_syntax

验证Mermaid代码语法。

参数:

mermaidCode (string, 必需): 要验证的Mermaid图表代码

示例:

{
  "mermaidCode": "sequenceDiagram\n    Alice->>Bob: Hello"
}

🔧 技术特性

全局污染解决方案

使用独立的JSDOM实例和临时全局变量设置，避免在多用户并发环境中的竞态问题：

// 创建隔离的渲染环境
const dom = new JSDOM('<!DOCTYPE html>...');
const originalWindow = global.window;
const originalDocument = global.document;

try {
  global.window = dom.window;
  global.document = dom.window.document;
  // 渲染逻辑
} finally {
  // 恢复原始全局变量
  if (originalWindow !== undefined) {
    global.window = originalWindow;
  } else {
    delete (global as any).window;
  }
  dom.window.close();
}

稳健的SVG标题添加

使用DOM解析器插入title元素，比字符串替换更可靠：

private addTitleToSVG(svg: string, title: string): string {
  try {
    const dom = new JSDOM(`<!DOCTYPE html><html><body>${svg}</body></html>`);
    const svgElement = dom.window.document.querySelector('svg');
    
    if (svgElement) {
      const titleElement = dom.window.document.createElement('title');
      titleElement.textContent = title;
      svgElement.insertBefore(titleElement, svgElement.firstChild);
      return svgElement.outerHTML;
    }
    // 回退方案...
  } catch (error) {
    // 回退到字符串替换
  }
}

精细的图表类型检测

使用正则表达式精确匹配各种Mermaid图表类型：

const patterns = [
  { pattern: /^(graph|flowchart)\s+(TD|TB|BT|RL|LR)/, type: '流程图' },
  { pattern: /^sequencediagram/m, type: '序列图' },
  { pattern: /^classDiagram/m, type: '类图' },
  // ... 更多模式
];

输入校验和安全性

字符串长度限制（50000字符）
恶意内容检测（script标签、JavaScript URL等）
文件名清理和安全化
CORS配置和域名白名单

SSE连接管理

自动连接清理和资源释放
优雅关闭处理
活动连接数量监控
错误处理和重连机制

🌐 Web测试界面

SSE模式提供了一个现代化的测试界面，包含：

🎨 美观的Material Design风格UI
📱 响应式设计，支持移动设备
🧪 实时代码测试和验证
📊 服务器状态监控
🔗 API端点信息

访问 http://localhost:3000 查看测试界面。

📡 API端点

SSE模式端点

GET / - 测试页面
GET /sse - Server-Sent Events连接端点
GET /health - 健康检查
GET /api/info - API信息

健康检查响应

{
  "status": "healthy",
  "mode": "sse",
  "port": 3000,
  "activeConnections": 2,
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0.0"
}

🔧 配置

环境变量

ALLOWED_ORIGINS: CORS允许的域名列表（逗号分隔），默认为*
NODE_ENV: 环境模式（development/production）

TypeScript配置

项目使用严格的TypeScript配置：

启用所有严格检查
ESM模块系统
Node.js 18+ 目标
完整的类型声明

🚢 部署建议

1. 构建优化

# 生产构建
pnpm run build

# 验证构建产物
ls -la dist/

2. 进程管理

推荐使用PM2等进程管理器：

# 安装PM2
npm install -g pm2

# 启动服务
pm2 start dist/server/index.js --name mermaid-mcp

# SSE模式
pm2 start dist/server/index.js --name mermaid-mcp-sse -- --sse --port=3000

3. 反向代理

Nginx配置示例：

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目！

📄 许可证

MIT License

Made with ❤️ for the MCP community

Mermaid Chart MCP Server

一个专注于Mermaid图表渲染的MCP服务器，支持将Mermaid代码渲染为SVG图表。

✨ 特性

🎨 高质量渲染: 基于官方Mermaid库的SVG渲染
🔄 双模式支持: stdio（MCP标准）和SSE（Web测试）
🛡️ 安全性: 输入校验、沙箱环境、CORS配置
📊 多图表类型: 支持流程图、序列图、类图、甘特图等
🚀 高性能: 隔离渲染环境，避免全局污染
💚 健康监控: 内置健康检查和连接管理

🏗️ 项目结构

src/
├── server/
│   ├── index.ts              # 主入口文件
│   ├── simple-mcp-server.ts  # MCP服务器核心逻辑
│   ├── sse-transport.ts      # SSE传输和Web服务器
│   └── utils.ts              # 工具函数（校验、清理等）
├── package.json
├── tsconfig.json
├── tsup.config.ts            # 构建配置
└── README.md

🚀 快速开始

安装依赖

pnpm install

开发模式

# stdio模式（用于MCP客户端）
pnpm run start:dev

# SSE模式（用于Web测试）
pnpm run start:dev:sse

# 指定端口的SSE模式
pnpm run start:dev:sse -- --port=3001

构建和运行

# 构建项目
pnpm run build

# 运行构建后的项目
pnpm start                  # stdio模式
pnpm run start:sse          # SSE模式
pnpm run start:sse:port     # SSE模式（端口3001）

🔍 调试和测试

推荐使用官方的 MCP Inspector 进行调试和测试：

# 使用 MCP Inspector 调试服务器
npx @modelcontextprotocol/inspector node dist/server/index.js

# 或者在开发模式下
npx @modelcontextprotocol/inspector node --loader ts-node/esm src/server/index.ts

MCP Inspector 提供了强大的可视化界面，支持：

🎨 交互式工具测试
📊 实时请求/响应监控
🔧 参数配置和验证
📋 完整的API探索

🛠️ 可用工具

1. render_mermaid_to_svg

将Mermaid代码渲染为SVG图表。

参数:

mermaidCode (string, 必需): Mermaid图表代码
title (string, 可选): 图表标题，默认"Mermaid图表"
theme (string, 可选): 主题，可选值: default, dark, forest, neutral
createTempFile (boolean, 可选): 是否创建临时SVG文件，默认true

示例:

{
  "mermaidCode": "graph TD\n    A[开始] --> B[结束]",
  "title": "简单流程图",
  "theme": "dark",
  "createTempFile": true
}

2. validate_mermaid_syntax

验证Mermaid代码语法。

参数:

mermaidCode (string, 必需): 要验证的Mermaid图表代码

示例:

{
  "mermaidCode": "sequenceDiagram\n    Alice->>Bob: Hello"
}

🔧 技术特性

全局污染解决方案

使用独立的JSDOM实例和临时全局变量设置，避免在多用户并发环境中的竞态问题：

// 创建隔离的渲染环境
const dom = new JSDOM('<!DOCTYPE html>...');
const originalWindow = global.window;
const originalDocument = global.document;

try {
  global.window = dom.window;
  global.document = dom.window.document;
  // 渲染逻辑
} finally {
  // 恢复原始全局变量
  if (originalWindow !== undefined) {
    global.window = originalWindow;
  } else {
    delete (global as any).window;
  }
  dom.window.close();
}

稳健的SVG标题添加

使用DOM解析器插入title元素，比字符串替换更可靠：

private addTitleToSVG(svg: string, title: string): string {
  try {
    const dom = new JSDOM(`<!DOCTYPE html><html><body>${svg}</body></html>`);
    const svgElement = dom.window.document.querySelector('svg');
    
    if (svgElement) {
      const titleElement = dom.window.document.createElement('title');
      titleElement.textContent = title;
      svgElement.insertBefore(titleElement, svgElement.firstChild);
      return svgElement.outerHTML;
    }
    // 回退方案...
  } catch (error) {
    // 回退到字符串替换
  }
}

精细的图表类型检测

使用正则表达式精确匹配各种Mermaid图表类型：

const patterns = [
  { pattern: /^(graph|flowchart)\s+(TD|TB|BT|RL|LR)/, type: '流程图' },
  { pattern: /^sequencediagram/m, type: '序列图' },
  { pattern: /^classDiagram/m, type: '类图' },
  // ... 更多模式
];

输入校验和安全性

字符串长度限制（50000字符）
恶意内容检测（script标签、JavaScript URL等）
文件名清理和安全化
CORS配置和域名白名单

SSE连接管理

自动连接清理和资源释放
优雅关闭处理
活动连接数量监控
错误处理和重连机制

🌐 Web测试界面

SSE模式提供了一个现代化的测试界面，包含：

🎨 美观的Material Design风格UI
📱 响应式设计，支持移动设备
🧪 实时代码测试和验证
📊 服务器状态监控
🔗 API端点信息

访问 http://localhost:3000 查看测试界面。

📡 API端点

SSE模式端点

GET / - 测试页面
GET /sse - Server-Sent Events连接端点
GET /health - 健康检查
GET /api/info - API信息

健康检查响应

{
  "status": "healthy",
  "mode": "sse",
  "port": 3000,
  "activeConnections": 2,
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0.0"
}

🔧 配置

环境变量

ALLOWED_ORIGINS: CORS允许的域名列表（逗号分隔），默认为*
NODE_ENV: 环境模式（development/production）

TypeScript配置

项目使用严格的TypeScript配置：

启用所有严格检查
ESM模块系统
Node.js 18+ 目标
完整的类型声明

🚢 部署建议

1. 构建优化

# 生产构建
pnpm run build

# 验证构建产物
ls -la dist/

2. 进程管理

推荐使用PM2等进程管理器：

# 安装PM2
npm install -g pm2

# 启动服务
pm2 start dist/server/index.js --name mermaid-mcp

# SSE模式
pm2 start dist/server/index.js --name mermaid-mcp-sse -- --sse --port=3000

3. 反向代理

Nginx配置示例：

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目！

📄 许可证

MIT License

Made with ❤️ for the MCP community