使用说明

MCP图表服务器

一个完全符合MCP的图表渲染服务器，它提供了通过模型上下文协议将PlantUML、Graphviz（DOT）和Mermaid图表渲染为SVG/PNG格式的工具。

特性

🎨 PlantUML -将PlantUML脚本渲染为SVG或PNG
📊 Graphviz（DOT） -将DOT源渲染为SVG或PNG
🌊 美人鱼 -将美人鱼图渲染为SVG或PNG
🔌 符合MCP标准 -通过stdio和SSE完全支持MCP协议
🌐 多种模式 -HTTP REST API、MCP stdio和MCP SSE
🚀 快速API -使用FastAPI构建，提供现代异步支持

项目结构

mcp_diagram_server/
├── mcp_diagram_server.py   # Main server (all modes: HTTP, MCP stdio, SSE)
├── mcp_stdio_wrapper.py    # Legacy wrapper (deprecated)
├── diagram_ui.html         # Web UI for interactive rendering
├── README.md                # This file
├── doc/                     # Documentation
│   ├── index.md            # Documentation index
│   ├── usage.md            # Complete usage guide
│   ├── cursor_direct_usage.md  # Cursor integration
│   ├── sse_usage.md        # SSE mode guide
│   ├── web_ui_usage.md     # Web UI guide
│   └── mcp_compliance.md   # MCP protocol details
├── test/                    # Test scripts
│   ├── test_mcp_direct.py  # Test stdio mode
│   ├── test_sse_mode.py    # Test SSE mode
│   └── ...
└── pyproject.toml           # Dependencies

需求

系统相关性

Graphviz

# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt-get install graphviz

# Windows
# Download and install from https://graphviz.org/download/

Mermaid CLI（可选，仅用于渲染Mermaid）

# Install globally
npm install -g @mermaid-js/mermaid-cli

# Or use npx (no install needed)
# The server will automatically use npx if available

Python依赖关系

此项目使用Poetry进行依赖关系管理。

# Install Poetry if you haven't already
curl -sSL https://install.python-poetry.org | python3 -

# Install Python dependencies
poetry install

或者，如果你更喜欢pip：

pip install fastapi uvicorn graphviz requests python-dotenv

注意：您仍然需要单独安装Graphviz系统二进制文件。

安装

克隆或下载此存储库
```
cd mcp_diagram_server
```
安装Graphviz （见上文系统依赖关系）
安装Python依赖项
```
poetry install
```
（可选）安装Mermaid CLI 用于Mermaid图支持
```
npm install -g @mermaid-js/mermaid-cli
```

运行服务器

# Using Make (recommended)
make run

# Using Poetry
poetry run uvicorn mcp_diagram_server:app --host 0.0.0.0 --port 8050 --reload

# Or using uvicorn directly (if dependencies installed via pip)
uvicorn mcp_diagram_server:app --host 0.0.0.0 --port 8050 --reload

服务器将于启动 http://localhost:8050.

使用Make

为方便起见，a Makefile 包含在常用命令中：

make help       # Show all available commands
make install    # Install dependencies
make run        # Run the server
make test       # Run tests
make test-cov   # Run tests with coverage
make lint       # Lint code
make format     # Format code
make clean      # Clean temporary files

API终点

发布 `/list_tools`

返回可用的图表渲染工具。

答复：

{
  "ok": true,
  "tools": [
    {
      "name": "plantuml.render",
      "description": "Render PlantUML diagram text to image",
      "arguments": {
        "text": "string (PlantUML script)",
        "format": "string, 'svg' or 'png' (optional, default 'svg')"
      }
    },
    ...
  ]
}

发布 `/call_tool`

使用可用工具之一渲染图表。

请求：

{
  "name": "plantuml.render",
  "arguments": {
    "text": "@startuml\nAlice -> Bob: Hello\n@enduml",
    "format": "svg"
  }
}

成功响应：

{
  "ok": true,
  "result": {
    "content_type": "image/svg+xml",
    "data_base64": "PHN2Zz4..."
  }
}

错误响应：

{
  "ok": false,
  "error": "error message"
}

测试服务器

使用curl

列出可用工具：

curl -X POST http://localhost:8050/list_tools

渲染PlantUML图：

curl -X POST http://localhost:8050/call_tool \
  -H "Content-Type: application/json" \
  -d '{
    "name": "plantuml.render",
    "arguments": {
      "text": "@startuml\nAlice -> Bob: Hello\n@enduml",
      "format": "svg"
    }
  }'

渲染Graphviz（DOT）图：

curl -X POST http://localhost:8050/call_tool \
  -H "Content-Type: application/json" \
  -d '{
    "name": "graphviz.render",
    "arguments": {
      "dot": "digraph { A -> B }",
      "format": "svg"
    }
  }'

渲染美人鱼图：

curl -X POST http://localhost:8050/call_tool \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mermaid.render",
    "arguments": {
      "text": "graph TD\nA-->B",
      "format": "svg"
    }
  }'

使用pytest（推荐）

运行综合测试套件：

# Using Make (recommended)
make test           # Run all tests
make test-cov       # Run tests with coverage
make test-verbose   # Run tests with verbose output

# Or using pytest directly
poetry run pytest                    # Run all tests
poetry run pytest -v                 # Run with verbose output
poetry run pytest test_mcp_diagram_server.py::test_plantuml_render_svg -v  # Run specific test
poetry run pytest --cov=mcp_diagram_server --cov-report=html  # Run with coverage report

测试套件包括：

✅ 列出工具端点
✅ PlantUML渲染（SVG和PNG）
✅ Graphviz渲染（SVG和PNG）
✅ 美人鱼渲染（需要Mermaid cli）
✅ 错误处理（缺少参数、语法无效）
✅ 边缘案例（复杂图表，默认格式）
✅ Base64编码有效性

与Cursor集成

MCP模式（推荐）

这是将服务器与Cursor一起使用的最简单、最直接的方法。

在中配置 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-diagram-server": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_diagram_server.py", "--mcp"],
      "env": {}
    }
  }
}

替换 /absolute/path/to/ 使用服务器文件的实际路径。

重新启动Cursor，您将能够要求AI直接生成图表！

有关详细说明，请参阅 cursor_direct_usage.md.

HTTP模式（可选）

如果您更喜欢将服务器用作HTTP API：

启动服务器：
```
make run
```
访问web UI：
```
http://localhost:8050
```
或者使用REST API 从您的代码中编程。

文档

有关更多详细信息，请参阅文档目录和那个索引:

usage.md -所有模式的完整使用指南
cursor_direct_usage.md -游标IDE集成
web_ui_usage.md -交互式web UI指南
sse_usage.md -服务器发送事件模式
mcp合规.md -MCP协议详细信息

故障排除

“graphviz不可用”

确保Graphviz已安装且可访问：

which dot  # Should return the path to dot binary

在macOS上使用Homebrew：

brew install graphviz

“未找到mermaid cli（mmdc）”

安装Mermaid命令行界面：

npm install -g @mermaid-js/mermaid-cli

或者服务器将尝试使用 npx 如果可用（速度较慢，但无需安装）。

服务器未启动

检查端口8050是否已在使用中：

lsof -i :8050

使用其他端口：

uvicorn mcp_diagram_server:app --port 8081

示例图表

PlantUML示例

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

Graphviz示例

digraph G {
    rankdir=LR
    A[label="Start"]
    B[label="Process"]
    C[label="End"]
    A -> B -> C
}

美人鱼示例

graph TD
    A[Christmas] -->|Get money| B[Buy presents]
    B --> C{Is it Jan 1?}
    C -->|Yes| D[Return]
    C -->|No| E[Keep presents]

许可证

麻省理工学院

贡献

欢迎投稿！这是一个专注于开发工作流程的实用图表渲染的最小实现。