使用说明

UML MCP服务

使用PlantUML生成UML图的模型上下文协议（MCP）服务实现。此服务提供了一个远程服务器，该服务器接受来自MCP客户端的UML命令，并返回各种格式（PNG、SVG、TXT）的生成图。

特性

MCP协议支持：基于JSON-RPC 2.0的MCP协议实现
PlantUML集成：对所有图表类型的完整PlantUML支持
多种输出格式：生成PNG、SVG或ASCII文本格式的图表
远程部署：在任何主机上作为独立服务器运行
RESTful API：MCP和REST风格的端点都可用
Docker支持：使用Docker/Docker Compose轻松部署
跨平台客户端：包括Java和Python客户端实现

支持的图表类型

顺序图
类图
用例图
活动图
构件图
状态图
对象图
部署图
定时图
网络图
线框图
拱形图
甘特图
思维导图
工作分解结构（WBS）

建筑

┌─────────────────┐
│  MCP Clients    │
│  (Java/Python)  │
└────────┬────────┘
         │ HTTP/JSON-RPC
         │
┌────────▼────────┐
│   MCP Server    │
│   (Javalin)     │
├─────────────────┤
│  PlantUML       │
│  Service        │
└─────────────────┘

快速开始

使用Docker Compose（推荐）

# Clone the repository
git clone <repository-url>
cd uml-mcp

# Build and start the server
cd server
docker-compose up -d

# Check server status
curl http://localhost:8080/health

手动构建和运行

# Build the server
cd server
mvn clean package

# Run the server
java -jar target/uml-mcp-server-1.0.0.jar

# Or with custom host/port
java -jar target/uml-mcp-server-1.0.0.jar --host 0.0.0.0 --port 9000

服务器使用情况

启动服务器

# Default configuration (0.0.0.0:8080)
java -jar uml-mcp-server-1.0.0.jar

# Custom host and port
java -jar uml-mcp-server-1.0.0.jar --host localhost --port 9000

# Using Docker
docker run -p 8080:8080 uml-mcp-server

可用端点

MCP端点

POST /mcp/generate -生成UML图
POST /mcp/validate -验证UML源代码
POST /mcp/capabilities -获取服务器功能

REST端点

POST /api/v1/diagrams/generate -生成UML图
POST /api/v1/diagrams/validate -验证UML源代码
GET /api/v1/capabilities -获取服务器功能
GET /health -健康检查

客户端使用情况

JAVA客户端

构建

cd clients/java
mvn clean package

用法

# Generate diagram with default example
java -jar target/uml-mcp-java-client-1.0.0.jar generate http://localhost:8080

# Generate from custom UML source
java -jar target/uml-mcp-java-client-1.0.0.jar generate \
  http://localhost:8080 \
  "@startuml\nAlice -> Bob: Hello\n@enduml" \
  png \
  output.png

# Validate UML
java -jar target/uml-mcp-java-client-1.0.0.jar validate \
  http://localhost:8080 \
  "@startuml\nAlice -> Bob\n@enduml"

# Get capabilities
java -jar target/uml-mcp-java-client-1.0.0.jar capabilities http://localhost:8080

作为图书馆

import com.mcp.client.UMLMCPClient;

UMLMCPClient client = new UMLMCPClient("http://localhost:8080");

String uml = "@startuml\nAlice -> Bob: Hello\n@enduml";
MCPResponse response = client.generateDiagram(uml, "png", "sequence");

if (response.getError() == null) {
    client.saveDiagram(response, "output.png");
}

Python客户端

安装

cd clients/python
pip install -r requirements.txt

用法

# Generate diagram with default example
python uml_mcp_client.py generate --server http://localhost:8080

# Generate from file
python uml_mcp_client.py generate \
  --server http://localhost:8080 \
  --uml diagram.puml \
  --format png \
  --output result.png

# Generate from inline UML
python uml_mcp_client.py generate \
  --uml "@startuml\nAlice -> Bob\n@enduml" \
  --format svg

# Use built-in examples
python uml_mcp_client.py generate --example sequence --format png
python uml_mcp_client.py generate --example class --format svg

# Validate UML
python uml_mcp_client.py validate --uml diagram.puml

# Get capabilities
python uml_mcp_client.py capabilities

作为图书馆

from uml_mcp_client import UMLMCPClient

client = UMLMCPClient("http://localhost:8080")

uml_source = """
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi!
@enduml
"""

response = client.generate_diagram(uml_source, "png", "sequence")

if not response.has_error():
    client.save_diagram(response, "output.png")

示例请求

生成序列图

请求：

curl -X POST http://localhost:8080/mcp/generate \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "generate",
    "params": {
      "uml": "@startuml\nAlice -> Bob: Authentication Request\nBob --> Alice: Authentication Response\n@enduml",
      "format": "png",
      "diagramType": "sequence"
    }
  }'

答复：

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "diagram": "iVBORw0KGgoAAAANSUhEUgAA...(base64 encoded PNG)",
    "format": "png",
    "diagramType": "sequence",
    "timestamp": 1698765432000
  }
}

生成类图（SVG）

请求：

curl -X POST http://localhost:8080/mcp/generate \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "generate",
    "params": {
      "uml": "@startuml\nclass User {\n  -username: String\n  +login()\n}\n@enduml",
      "format": "svg",
      "diagramType": "class"
    }
  }'

生成活动图（ASCII文本）

请求：

curl -X POST http://localhost:8080/mcp/generate \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "generate",
    "params": {
      "uml": "@startuml\n:Start;\n:Process Data;\n:End;\n@enduml",
      "format": "txt",
      "diagramType": "activity"
    }
  }'

答复：

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "diagramText": "     ┌─────┐\n     │Start│\n     └──┬──┘\n...",
    "format": "txt",
    "diagramType": "activity",
    "timestamp": 1698765432100
  }
}

验证UML

请求：

curl -X POST http://localhost:8080/mcp/validate \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "validate",
    "params": {
      "uml": "@startuml\nAlice -> Bob\n@enduml"
    }
  }'

答复：

{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "diagramText": "Valid UML",
    "timestamp": 1698765432200
  }
}

获取能力

请求：

curl -X POST http://localhost:8080/mcp/capabilities \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "5",
    "method": "capabilities"
  }'

答复：

{
  "jsonrpc": "2.0",
  "id": "5",
  "result": {
    "diagramText": "Supported Diagram Types: sequence, usecase, class, activity, component, state, object, deployment, timing, network, wireframe, archimate, gantt, mindmap, wbs\nSupported Formats: png, svg, txt",
    "timestamp": 1698765432300
  }
}

UML示例

顺序图

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

User -> Web: Login Request
Web -> API: POST /auth/login
API -> DB: Validate Credentials
DB --> API: User Data
API --> Web: Auth Token
Web --> User: Login Success
@enduml

类图

@startuml
class User {
  -String username
  -String email
  -String password
  +login()
  +logout()
  +updateProfile()
}

class Admin {
  -List<Permission> permissions
  +manageUsers()
  +assignRoles()
}

class Customer {
  -String address
  -String phone
  +placeOrder()
}

User <|-- Admin
User <|-- Customer
@enduml

用例图

@startuml
left to right direction
actor User
actor Admin

rectangle System {
  User -- (Login)
  User -- (View Products)
  User -- (Place Order)
  Admin -- (Manage Users)
  Admin -- (View Reports)
  (Manage Users) .> (Login) : includes
}
@enduml

活动图

@startuml
start
:Receive Order;
if (In Stock?) then (yes)
  :Process Payment;
  :Ship Order;
else (no)
  :Notify Customer;
  :Order from Supplier;
endif
:Update Inventory;
stop
@enduml

错误处理

服务器返回标准JSON-RPC 2.0错误响应：

错误响应：

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32602,
    "message": "Invalid params: 'uml' parameter is required",
    "data": "Additional error details"
  }
}

错误代码：

-32700：分析错误
-32600：无效请求
-32602：无效参数
-32000：服务器错误

性能注意事项

图表生成时间因复杂性而异（通常为100-500ms）
服务器可以处理并发请求
对于高流量场景，请考虑：
- 为频繁生成的图表实施缓存
- 负载平衡多个服务器实例
- 添加请求速率限制

部署

Docker部署

# Build the image
cd server
docker build -t uml-mcp-server .

# Run the container
docker run -d -p 8080:8080 --name uml-mcp uml-mcp-server

# Check logs
docker logs -f uml-mcp

生产部署检查表

[]配置适当的主机和端口
[]为HTTPS设置反向代理（nginx/Apache）
[]实施请求速率限制
[]配置日志记录和监控
[]设置健康检查和警报
[]考虑实施身份验证/授权
[]仅对受信任的域启用CORS

发展

从源头构建

# Server
cd server
mvn clean install

# Java Client
cd clients/java
mvn clean install

# Python Client (development mode)
cd clients/python
pip install -e .

运行测试

# Server tests
cd server
mvn test

# Manual testing
./test-server.sh

故障排除

服务器无法启动

检查端口8080是否已在使用中： netstat -an | grep 8080
尝试其他端口： java -jar server.jar --port 9000

图表生成失败

确保PlantUML依赖项已正确安装
检查服务器日志以获取详细的错误消息
使用验证端点验证UML语法

客户端连接问题

验证服务器是否正在运行： curl http://localhost:8080/health
检查防火墙设置
确保客户端配置中的服务器URL正确

API文档

看 docs/API.md文件 API的详细文档。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请随时提交拉取请求。

支持

对于问题和疑问：

在GitHub上打开一个问题
检查中的现有文档 docs/ 目录

致谢

PlantUML -UML图生成引擎
Javalin -Java轻量级web框架

使用说明

UML MCP服务

特性

支持的图表类型

建筑

快速开始

使用Docker Compose（推荐）

手动构建和运行

服务器使用情况

启动服务器

可用端点

MCP端点

REST端点

客户端使用情况

JAVA客户端

构建

用法

作为图书馆

Python客户端

安装

用法

作为图书馆

示例请求

生成序列图

生成类图（SVG）

生成活动图（ASCII文本）

验证UML

获取能力

UML示例

顺序图

类图

用例图

活动图

错误处理

性能注意事项

部署

Docker部署

生产部署检查表

发展

从源头构建

运行测试

故障排除

服务器无法启动

图表生成失败

客户端连接问题

API文档

许可证

贡献

支持

致谢

相关 MCP

Excel表格处理MCP服务

图表生成MCP服务器

AI开发助手

ECharts 图表生成 MCP 服务

漏洞扫描服务

图表生成服务