Sargoth Mermaid Renderer - MCP Server

---

🚀 用 AI 将想法转化为图表

使用 AI 轻松将想法转化为精美图表。只需用通俗英语向大模型助手描述工作流、流程或系统，即可通过我们的高性能 Mermaid 引擎即时生成专业的 SVG/PNG 图表。

理想的 AI 工作流：

• 💬 用自然语言向 Claude/ChatGPT 描述图表需求
• 🤖 大模型自动生成经过优化的 Mermaid 代码
• ⚡ 我们的 MCP 服务即时渲染精美、可用于生产环境的视觉效果
• 📥 使用自定义主题和缩放比例导出为 SVG 或 PNG

什么是 MCP？

Model Context Protocol（MCP） 是一项开放标准，可让 AI 助手安全地连接到外部数据源和工具。通过为我们的 Mermaid 渲染器创建 MCP 服务，我们让 AI 助手能够：

• 🎨 在对话过程中实时生成图表
• ✅ 验证 Mermaid 语法并提出改进建议
• 📚 创建可视化文档和说明
• 🔄 帮助用户逐步构建复杂图表

✨ 功能

MCP 服务提供 4 个强大的工具：

🎨 render_mermaid_svg

使用 Mermaid 代码生成 SVG 图表，并支持主题。

参数：

• code（必填）：Mermaid 图表代码
• theme（可选）：主题（modern、classic、dark、minimal）

🖼️ render_mermaid_png

使用 Mermaid 代码生成 PNG 图像，并支持缩放。

参数：

• code（必填）：Mermaid 图表代码
• theme（可选）：主题（modern、classic、dark、minimal）
• scale（可选）：PNG 缩放系数（1-4，默认值：2）

✅ validate_mermaid

验证 Mermaid 语法并分析图表复杂度。

参数：

• code（必填）：要验证的 Mermaid 图表代码

💡 suggest_mermaid_improvements

分析 Mermaid 代码并提出改进建议或修复方案。

参数：

• code（必填）：要分析的 Mermaid 代码
• diagram_type（可选）：预期的图表类型，用于提供有针对性的建议

📦 安装

前置条件

1. 已安装 Python 3.8+
2. 兼容 MCP 的 AI 助手（Claude Desktop 等）
3. 可选：用于开发的本地 Sargoth Mermaid Renderer API（参见主项目）

步骤 1：安装 MCP 依赖项

# Install MCP server dependencies
pip install -r requirements.txt

步骤 2：使服务可执行

chmod +x mcp_server.py

步骤 3：测试服务

使用生产环境 API（推荐）：

# Test with the live production API
python mcp_server.py

使用本地开发 API：

# Start your local Mermaid API first
python ../app.py

# In another terminal, test the MCP server with local API
python mcp_server.py --api-url http://localhost:5000

🔌 与 AI 助手集成

Claude Desktop

1. 找到 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加 MCP 服务配置：

用于生产环境（推荐）：

{
  "mcpServers": {
    "mermaid-renderer": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server.py"]
    }
  }
}

用于本地开发：

{
  "mcpServers": {
    "mermaid-renderer": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server.py", "--api-url", "http://localhost:5000"]
    }
  }
}

3. 重启 Claude Desktop

4. 测试集成：

   • 开启新对话
   • 提问：“你能创建一个展示简单用户登录流程的流程图吗？”
   • Claude 应会使用 Mermaid 工具生成图表！

其他 MCP 客户端

生产环境配置：

{
  "command": "python",
  "args": ["mcp_server.py"]
}

本地开发配置：

{
  "command": "python",
  "args": ["mcp_server.py", "--api-url", "http://localhost:5000"]
}

💬 使用示例

集成后，你可以向 AI 助手提出类似以下请求：

基本图表生成

“创建一个时序图，展示用户如何登录 Web 应用程序”

验证与改进

“检查这段 Mermaid 代码是否有错误：```graph TD A -> B```”

复杂工作流

“为 CI/CD 流水线生成一个流程图，然后将其转换为 PNG 格式”

教育内容

“为一个简单的电子商务系统创建类图，并解释每个组件”

🎯 对话示例

你：“能否为一个简单的交通信号灯系统创建状态图？”

AI 助手： 使用 render_mermaid_svg 工具

stateDiagram-v2
    [*] --> Red
    Red --> Green : Timer
    Green --> Yellow : Timer
    Yellow --> Red : Timer
    Red --> [*]

AI：“我已创建一个交通信号灯状态机的 SVG 图表！该图表展示了三个状态（红、绿、黄）以及由计时器触发的状态转换。你想将其转换为 PNG 格式，还是修改设计？”

⚙️ API 配置

默认行为

MCP 服务默认使用**生产环境 API：https://sargoth.xyz**。大多数用户无需进行其他配置。

环境变量

• MERMAID_API_URL：覆盖 API 基础 URL（可选）

命令行选项

python mcp_server.py --help

# Use production API (default)
python mcp_server.py

# Use local development API
python mcp_server.py --api-url http://localhost:5000

# Use custom API endpoint
python mcp_server.py --api-url https://sargoth.xyz

配置示例

生产环境（默认）：

• 无需配置
• 自动使用 https://sargoth.xyz
• 推荐大多数用户使用

本地开发：

• 运行本地 API：python ../app.py
• 使用标志：--api-url http://localhost:5000
• 适用于测试更改

自定义部署：

• 使用你自行托管的实例
• 指定为：--api-url https://sargoth.xyz

🔧 故障排除

服务无法启动

1. 检查互联网连接（生产环境 API 需要联网）
2. 确保已安装所有依赖项：pip install -r requirements.txt
3. 验证 Python 版本：python --version（需要 3.8+）
4. 对于本地开发，确保本地 Mermaid API 正在运行

AI 助手找不到工具

1. 检查 MCP 配置文件路径
2. 确保配置中的服务路径是绝对路径
3. 更改配置后，重启 AI 助手
4. 检查日志中是否有连接错误

渲染失败

1. 生产环境 API：检查互联网连接并重试
2. 本地 API：验证 API 是否可访问：curl http://localhost:5000/health
3. 先使用简单的 Mermaid 代码进行测试
4. 检查 API 日志以获取详细错误信息

连接问题

1. 防火墙：确保允许出站 HTTPS 连接
2. 代理：如果处于企业防火墙之后，请配置代理设置
3. 本地开发：验证本地 API 是否运行在正确端口上

🔒 安全注意事项

• 生产环境 API：通过安全的 HTTPS 连接到 https://sargoth.xyz
• 网络：生产环境使用需要能够通过 HTTPS 访问 sargoth.xyz

🎨 高级用法

自定义主题

该服务支持 Mermaid 渲染器提供的所有主题：

• modern（默认）
• classic
• dark
• minimal

批量处理

虽然 MCP 协议会逐个处理工具，但你可以让 AI 按顺序生成多个图表。

与文档集成

使用 MCP 服务自动为以下内容生成图表：

• 技术文档
• 架构图
• 流程图
• 教育材料

🤝 贡献

此 MCP 服务是 Sargoth Mermaid Renderer 项目的一部分。贡献方式如下：

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交拉取请求

📄 许可证

与 Sargoth Mermaid Renderer 主项目相同。

---