# PlantUML MCP Server

A Model Context Protocol (MCP) server that wraps PlantUML functionality, allowing AI assistants to generate UML diagrams from text descriptions.

## Features

- **Generate Diagrams**: Create diagrams in multiple formats (PNG, SVG, TXT, PDF, etc.)
- **Syntax Checking**: Validate PlantUML syntax without generating images
- **Source Extraction**: Extract PlantUML source from PNG/SVG metadata
- **Dark Mode Support**: Generate diagrams with dark theme
- **Version Info**: Get PlantUML and Java version information

## Prerequisites

- Node.js 18 or higher
- Java Runtime Environment (JRE)
- PlantUML JAR file

## Installation

1. Clone this repository:
```bash
git clone <repository-url>
cd planuml
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

4. Set the PlantUML JAR path (optional):
```bash
export PLANTUML_JAR=/path/to/plantuml.jar
```

Default path: `/Users/userxxx/bin/plantuml.jar`

## Usage

### As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "plantuml": {
      "command": "node",
      "args": ["xxx/dist/index.js"],
      "env": {
        "PLANTUML_JAR": "xxx/plantuml.jar"
      }
    }
  }
}
```

### Available Tools

#### 1. generate_diagram

Generate a diagram from PlantUML source code.

**Parameters:**
- `source` (required): PlantUML source code
- `format` (optional): Output format - `png`, `svg`, `txt`, `utxt`, `eps`, `latex`, `pdf` (default: `png`)
- `darkMode` (optional): Render in dark mode (default: `false`)

**Returns:** Base64-encoded diagram data

**Example:**
```typescript
{
  "source": "@startuml\nAlice -> Bob: Hello\n@enduml",
  "format": "svg",
  "darkMode": false
}
```

#### 2. check_syntax

Check PlantUML diagram syntax without generating images.

**Parameters:**
- `source` (required): PlantUML source code to validate

**Returns:** Validation result or syntax errors

**Example:**
```typescript
{
  "source": "@startuml\nAlice -> Bob: Hello\n@enduml"
}
```

#### 3. extract_source

Extract embedded PlantUML source from PNG or SVG metadata.

**Parameters:**
- `filePath` (required): Path to the PNG or SVG file

**Returns:** Extracted PlantUML source code

**Example:**
```typescript
{
  "filePath": "/path/to/diagram.png"
}
```

#### 4. get_plantuml_version

Get PlantUML and Java version information.

**Parameters:** None

**Returns:** Version information

## PlantUML Syntax Examples

### Sequence Diagram
```plantuml
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
@enduml
```

### Class Diagram
```plantuml
@startuml
class User {
  +String name
  +String email
  +login()
  +logout()
}

class Admin {
  +manageUsers()
}

User <|-- Admin
@enduml
```

### Activity Diagram
```plantuml
@startuml
start
:Initialize;
if (Check condition?) then (yes)
  :Process A;
else (no)
  :Process B;
endif
stop
@enduml
```

### Use Case Diagram
```plantuml
@startuml
left to right direction
actor User
actor Admin

rectangle System {
  User -- (Login)
  User -- (View Profile)
  Admin -- (Manage Users)
  Admin -- (View Reports)
}
@enduml
```

## Development

### Build
```bash
npm run build
```

### Watch mode
```bash
npm run watch
```

## Environment Variables

- `PLANTUML_JAR`: Path to the PlantUML JAR file (default: `/Users/userxxx/bin/plantuml.jar`)

## Supported Output Formats

- **png**: PNG images (default)
- **svg**: SVG vector graphics
- **txt**: ASCII art diagrams
- **utxt**: ASCII art with Unicode characters
- **eps**: Encapsulated PostScript
- **latex**: LaTeX/TikZ output
- **pdf**: PDF documents

## Error Handling

The server handles various error scenarios:
- Invalid PlantUML syntax
- Missing PlantUML JAR file
- Java runtime errors
- File I/O errors

Errors are returned with descriptive messages to help diagnose issues.

## License

MIT

## Resources

- [PlantUML Official Documentation](https://plantuml.com)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [PlantUML Language Reference](https://plantuml.com/guide)