# StarUML MCP Server

通过 MCP 协议或 REST API 远程控制 StarUML，让 AI 自动生成各种 UML 图表（用例图、类图、时序图、ER 图等）。

## Architecture

```
AI Client (Claude/Hermes/Cursor)
    │  MCP Protocol (stdio)
    ▼
Python MCP Server (server.py)
    │  HTTP REST API
    ▼
staruml-controller Extension (runs inside StarUML)
    │
    ▼
StarUML — renders diagrams
```

## Prerequisites

| Requirement | Version | Note |
|------------|---------|------|
| StarUML | v6.0.0+ | https://staruml.io/ |
| Python | 3.10+ | https://www.python.org/downloads/ |
| staruml-controller | latest | StarUML 扩展，提供 REST API |

## Quick Start

### 1. Install staruml-controller extension

Clone into StarUML's extensions directory:

```bash
# Windows (%APPDATA% = C:\Users\<用户名>\AppData\Roaming)
cd %APPDATA%\StarUML\extensions\user
git clone https://github.com/pontasan/staruml-controller.git

# macOS
cd ~/Library/Application\ Support/StarUML/extensions/user
git clone https://github.com/pontasan/staruml-controller.git

# Linux
cd ~/.config/StarUML/extensions/user
git clone https://github.com/pontasan/staruml-controller.git
```

### 2. Install Python dependencies

```bash
cd staruml-mcp
pip install -r requirements.txt
```

Or run the setup script:

```bash
scripts\setup.bat
```

### 3. Start StarUML

Launch StarUML — the extension auto-starts and listens on **port 12345**.

### 4. Start MCP Server

```bash
python server.py
```

---

## Configure AI Clients

### Proma / Claude Desktop

Edit `claude_desktop_config.json` (or Proma's `mcp.json`):

```json
{
  "mcpServers": {
    "staruml": {
      "command": "python",
      "args": ["D:/path/to/staruml-mcp/server.py"],
      "timeout": 60
    }
  }
}
```

### Hermes Agent

Edit `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  staruml:
    command: "python"
    args: ["D:/path/to/staruml-mcp/server.py"]
    timeout: 60
```

### Cursor

Edit `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "staruml": {
      "command": "python",
      "args": ["D:/path/to/staruml-mcp/server.py"]
    }
  }
}
```

### Custom Port

If the staruml-controller uses a different port:

```bash
python server.py --api-port 56789
```

---

## MCP Tools Reference

### Diagram Generation (via Mermaid)

| Tool | Description | Supported Types |
|------|-------------|----------------|
| `generate_diagram` | Import any Mermaid code | classDiagram, sequenceDiagram, flowchart, erDiagram, mindmap, requirementDiagram, stateDiagram |

### Structured Diagram Builders

| Tool | Description |
|------|-------------|
| `create_class_diagram` | 类图 — classes, attributes, methods, relationships |
| `create_sequence_diagram` | 时序图 — participants, messages |
| `create_use_case_diagram` | 用例图 — actors, use cases, relationships |
| `create_activity_diagram` | 活动图 — nodes, flows |
| `create_state_diagram` | 状态图 — states, transitions |
| `create_er_diagram` | ER 图 — entities, attributes, relationships |
| `create_flowchart` | 流程图 — nodes, connections |
| `create_mindmap` | 思维导图 — root, branches |

### Utility Tools

| Tool | Description |
|------|-------------|
| `check_staruml_connection` | 检查与 StarUML 的连接状态 |
| `get_all_diagrams` | 获取当前项目所有图表信息 |
| `get_current_diagram` | 获取当前图表详情 |
| `export_diagram_as_image` | 导出图表为 PNG 图片（base64） |

---

## AI Prompt Examples

In your AI chat, just say:

> "用 staruml 画一个电商系统的**用例图**，有顾客、商家和管理员三个角色"

> "画一个图书管理系统的**类图**，包含 Book、User、BorrowRecord"

> "画一个用户登录的**时序图**"

> "画一个订单处理的**状态图**"

> "画一个数据库设计的 **ER 图**"

---

## Direct REST API Usage

The `scripts/` directory contains standalone Python scripts that call the REST API directly (no MCP client needed).

### Create Use Case Diagram

```bash
python create_usecase.py
```

### Layout / Reposition Elements

If diagram elements overlap, run the layout script:

```bash
python layout_usecase.py
```

> **Note:** staruml-controller's auto-layout skips use case diagrams, so layout is done by manually positioning views via `PUT /api/views/:id`.

### API Endpoints

staruml-controller provides full CRUD REST API for all diagram families:

| Family | Prefix | Examples |
|--------|--------|---------|
| Use Case | `/api/usecase/` | actors, use-cases, subjects, associations, includes, extends |
| Class | `/api/class/` | classes, interfaces, attributes, methods, associations |
| Sequence | `/api/sequence/` | lifelines, messages, combined-fragments |
| Activity | `/api/activity/` | actions, decisions, forks |
| State Machine | `/api/statemachine/` | states, transitions |
| ERD | `/api/erd/` | entities, columns, relationships |
| Flowchart | `/api/flowchart/` | nodes, connections |
| MindMap | `/api/mindmap/` | nodes |
| BPMN | `/api/bpmn/` | pools, lanes, tasks, gateways |
| C4 | `/api/c4/` | containers, components, relationships |
| AWS / Azure / GCP | `/api/aws/`, `/api/azure/`, `/api/gcp/` | architecture diagrams |

Each family supports: `GET/POST /api/{family}/{resource}`, `GET/PUT/DELETE /api/{family}/{resource}/:id`

---

## Project Structure

```
staruml-mcp/
├── server.py                    # MCP Server (Python / FastMCP)
├── requirements.txt             # Python dependencies
├── README.md                    # This file
├── .gitignore
│
├── create_usecase.py            # Standalone: create a use case diagram via REST API
├── layout_usecase.py            # Standalone: reposition diagram elements
│
├── scripts/
│   ├── setup.bat                # Windows setup script
│   └── test_connection.bat      # Connection test script
│
└── examples/
    ├── class_library.json        # Class diagram example data
    ├── sequence_login.json       # Sequence diagram example data
    └── use_case_ecommerce.json   # Use case diagram example data
```

## Troubleshooting

### "Cannot connect to StarUML Controller"

1. Ensure StarUML is running
2. Check staruml-controller is installed at `%APPDATA%\StarUML\extensions\user\staruml-controller`
3. Restart StarUML (extension auto-starts on port 12345)
4. Run `scripts\test_connection.bat` to verify

### Mermaid Import Fails

Only these Mermaid types are supported: classDiagram, sequenceDiagram, flowchart, erDiagram, mindmap, requirementDiagram, stateDiagram. Use case diagrams use the REST API directly instead.

### Port Conflict

If port 12345 is in use, modify `server.py`'s `DEFAULT_API_PORT` or pass `--api-port` flag.

### Diagram Elements Overlap

Run `python layout_usecase.py` to reposition use case diagram elements. For other diagram types, use `POST /api/diagrams/{id}/layout` with direction (TB/BT/LR/RL).

## License

MIT