UML MCP 渲染服务

基于 FastMCP 的 UML 图表渲染服务，支持通过自然语言对话生成 UML 图表。

🚀 功能特性

• MCP 协议支持：符合 Model Context Protocol 标准，可作为 AI 工具调用
• PlantUML 渲染：支持完整的 PlantUML DSL 语法
• 多格式输出：支持 PNG、SVG 格式输出
• Base64 编码：直接返回 Base64 编码的图像数据
• 异步处理：高性能异步架构，支持并发请求
• 安全限制：输入大小限制，防止 DoS 攻击
• 错误处理：完善的错误处理和用户友好的错误信息

📋 系统要求

• Python 3.9+
• Java 8+ (用于运行 PlantUML)
• uv 包管理器 (推荐) 或 pip
• 4GB+ 内存推荐

🛠️ 安装部署

1. 克隆项目

git clone <repository-url>
cd uml-mcp

2. 安装依赖

使用 uv (推荐)

# 安装 uv 包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装项目依赖
uv sync

使用 pip (传统方式)

pip install -r requirements.txt

3. 下载 PlantUML

# 下载最新版本的 PlantUML JAR 文件
wget https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar
# 或者使用 curl
curl -L -o plantuml.jar https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar

4. 配置环境变量

创建 .env 文件：

# PlantUML JAR 文件路径
PLANTUML_JAR_PATH=./plantuml.jar

# 服务配置
SERVER_HOST=localhost
SERVER_PORT=8000

# 安全配置
MAX_UML_SIZE=10240  # 最大 UML 代码大小 (字节)
RENDER_TIMEOUT=30   # 渲染超时时间 (秒)

# 日志配置
LOG_LEVEL=INFO

5. 启动服务

使用 uv (推荐)

# 直接运行
uv run python server.py

# 或使用启动脚本
./start.sh

使用 python (传统方式)

# 直接运行
python server.py

# 或使用 FastMCP CLI
fastmcp run server.py:mcp

# HTTP 模式
fastmcp run server.py:mcp --transport http --port 8000

🔧 使用方法

MCP 工具调用

服务提供一个名为 render_uml 的 MCP 工具：

{
  "tool": "render_uml",
  "arguments": {
    "uml_code": "@startuml\nAlice -> Bob: Hello\nBob -> Alice: Hi\n@enduml",
    "format": "png"
  }
}

参数说明

• uml_code (必需): PlantUML DSL 代码，必须以 @startuml 开始，@enduml 结束
• format (可选): 输出格式，支持 png (默认) 或 svg

返回格式

{
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "format": "png",
  "success": true
}

📊 支持的 UML 图表类型

• 序列图 (Sequence Diagram)
• 类图 (Class Diagram)
• 用例图 (Use Case Diagram)
• 活动图 (Activity Diagram)
• 组件图 (Component Diagram)
• 部署图 (Deployment Diagram)
• 状态图 (State Diagram)
• 时序图 (Timing Diagram)

🔍 示例

类图示例

@startuml
class User {
  +username: String
  +email: String
  +login()
  +logout()
}

class Order {
  +id: Long
  +date: Date
  +total: BigDecimal
  +addItem()
}

class Product {
  +name: String
  +price: BigDecimal
  +description: String
}

User "1" -- "*" Order
Order "*" -- "*" Product
@enduml

序列图示例

@startuml
actor User
participant "Web App" as WA
participant "API Server" as API
database "Database" as DB

User -> WA: 登录请求
WA -> API: 验证用户
API -> DB: 查询用户信息
DB --> API: 返回用户数据
API --> WA: 验证成功
WA --> User: 显示主页
@enduml

🐳 Docker 部署

# 构建镜像
docker build -t uml-mcp .

# 运行容器
docker run -p 8000:8000 uml-mcp

🧪 测试

使用 uv

# 运行测试
uv run pytest

# 运行测试并生成覆盖率报告
uv run pytest --cov=src

使用 python

# 运行测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=src

📈 性能指标

• 渲染速度: 常规图表 < 3 秒
• 并发支持: 50+ 并发请求
• 内存使用: 基础 < 100MB，峰值 < 500MB
• 输入限制: UML 代码 ≤ 10KB

🔒 安全考虑

• 输入大小限制防止 DoS 攻击
• 渲染超时机制防止资源耗尽
• 临时文件自动清理
• 进程隔离和资源限制

🛣️ 发展路线图

V1.0 (当前)

• ✅ 基础 PlantUML 渲染
• ✅ PNG/SVG 格式支持
• ✅ MCP 协议集成
• ✅ 错误处理和安全限制

V2.0 (计划中)

• 🔄 渲染结果缓存
• 🔄 性能优化
• 🔄 更多输出格式 (PDF, EPS)

V3.0 (未来)

• 📋 Mermaid.js 支持
• 📋 Graphviz 支持
• 📋 多渲染引擎切换

V4.0 (远期)

• 📋 Web 编辑器界面
• 📋 实时预览功能
• 📋 协作编辑支持

🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 支持

如有问题或建议，请：

• 提交 Issue
• 发送邮件至 [your-email@example.com]
• 查看 Wiki 获取更多文档

🙏 致谢

• FastMCP - 优秀的 MCP 框架
• PlantUML - 强大的 UML 渲染引擎
• Model Context Protocol - 标准化的 AI 工具协议