drawio-mcp-server/README.md

# Draw.io MCP Server

An MCP (Model Context Protocol) server that enables creating and managing draw.io diagrams from Cline in VSCode using a functional programming approach.

## Features

- ✅ **Diagram Creation**: Support for multiple diagram types (BPMN, UML, ER, Network, Architecture, Flowchart, etc.)
- ✅ **VSCode Integration**: Automatic opening of diagrams in VSCode with draw.io extension
- ✅ **Functional Programming**: Architecture based on pure functions without classes
- ✅ **Automatic Generation**: Predefined templates for different diagram types
- ✅ **File Management**: Search and listing of existing diagrams
- ✅ **Automatic Configuration**: Automatic VSCode environment setup

## Supported Diagram Types

### BPMN (Business Process Model and Notation)
- `bpmn-process`: Business processes
- `bpmn-collaboration`: Collaboration between participants
- `bpmn-choreography`: Message exchanges

### UML (Unified Modeling Language)
- `uml-class`: Class diagrams
- `uml-sequence`: Sequence diagrams
- `uml-use-case`: Use case diagrams
- `uml-activity`: Activity diagrams
- `uml-state`: State diagrams
- `uml-component`: Component diagrams
- `uml-deployment`: Deployment diagrams

### Database
- `er-diagram`: Entity-Relationship diagrams
- `database-schema`: Database schemas
- `conceptual-model`: Conceptual models

### Network & Infrastructure
- `network-topology`: Network topology
- `infrastructure`: System infrastructure
- `cloud-architecture`: Cloud architecture

### Software Architecture
- `system-architecture`: System architecture
- `microservices`: Microservices architecture
- `layered-architecture`: Layered architecture
- `c4-context`: C4 context diagrams
- `c4-container`: C4 container diagrams
- `c4-component`: C4 component diagrams

### General
- `flowchart`: Flowcharts
- `orgchart`: Organizational charts
- `mindmap`: Mind maps
- `wireframe`: Wireframes
- `gantt`: Gantt charts

## Installation

1. **Clone the repository**:
```bash
git clone <repository-url>
cd drawio-mcp-server
```

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

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

4. **Configure in Cline**:
Add to your Cline MCP configuration file:

```json
{
  "mcpServers": {
    "drawio-mcp-server": {
      "command": "node",
      "args": ["/full/path/to/project/build/index.js"],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/workspace"
      }
    }
  }
}
```

## Available Tools

### `create_diagram`
Creates a new diagram of the specified type.

**Parameters**:
- `name` (required): Diagram file name
- `type` (required): Type of diagram to create
- `format` (optional): File format (drawio, drawio.svg, drawio.png, dio, xml)
- `description` (optional): Diagram description
- `outputPath` (optional): Output directory
- `workspaceRoot` (optional): Workspace root directory

**Type-specific parameters**:

**BPMN**:
- `processName`: Process name
- `tasks`: List of tasks
- `gatewayType`: Gateway type (exclusive, parallel)
- `branches`: Gateway branches
- `beforeGateway`: Tasks before gateway
- `afterGateway`: Tasks after gateway

**UML**:
- `classes`: List of classes for class diagrams

**ER**:
- `entities`: List of entities

**Network/Architecture**:
- `components`: List of components

**Flowchart**:
- `processes`: List of processes

**Example**:
```json
{
  "name": "my-bpmn-process",
  "type": "bpmn-process",
  "processName": "Approval Process",
  "tasks": ["Request", "Review", "Approve"],
  "format": "drawio"
}
```

### `list_diagrams`
Lists all diagram files in the workspace.

**Parameters**:
- `workspaceRoot` (optional): Workspace root directory

### `open_diagram_in_vscode`
Opens a diagram in VSCode with the draw.io extension.

**Parameters**:
- `filePath` (required): Path to the diagram file
- `workspaceRoot` (optional): Workspace root directory

### `setup_vscode_environment`
Sets up VSCode environment for draw.io (installs extension if needed).

**Parameters**:
- `workspaceRoot` (optional): Workspace root directory

### `get_diagram_types`
Gets the list of supported diagram types with descriptions.

## Available Resources

### `diagrams://workspace/list`
List of all diagram files in the workspace with metadata.

### `diagrams://types/supported`
List of supported diagram types with descriptions.

## Usage Examples

### Create a simple BPMN diagram
```bash
# Through Cline, use the tool:
create_diagram({
  "name": "sales-process",
  "type": "bpmn-process",
  "processName": "Sales Process",
  "tasks": ["Receive Order", "Check Stock", "Process Payment", "Ship Product"]
})
```

### Create a BPMN diagram with gateway
```bash
create_diagram({
  "name": "approval-process",
  "type": "bpmn-process",
  "processName": "Approval Process",
  "beforeGateway": ["Receive Request"],
  "gatewayType": "exclusive",
  "branches": [
    ["Auto Approve"],
    ["Manual Review", "Approve/Reject"]
  ],
  "afterGateway": ["Notify Result"]
})
```

### Create a UML class diagram
```bash
create_diagram({
  "name": "user-model",
  "type": "uml-class",
  "classes": ["User", "Profile", "Session"]
})
```

### Create an ER diagram
```bash
create_diagram({
  "name": "store-database",
  "type": "er-diagram",
  "entities": ["Customer", "Product", "Order", "OrderDetail"]
})
```

### Create an architecture diagram
```bash
create_diagram({
  "name": "system-architecture",
  "type": "system-architecture",
  "components": ["React Frontend", "API Gateway", "Auth Service", "Product Service", "Database"]
})
```

## Project Structure

```
src/
├── types/
│   └── diagram-types.ts          # Types and enums for diagrams
├── utils/
│   ├── file-manager.ts           # File management (functional)
│   ├── xml-parser.ts             # XML parser for draw.io (functional)
│   └── vscode-integration.ts     # VSCode integration (functional)
├── generators/
│   └── bpmn-generator.ts         # BPMN diagram generator (functional)
├── tools/
│   └── create-diagram.ts         # Main creation tool
└── index.ts                      # Main MCP server
```

## Functional Architecture

The project is designed following functional programming principles:

- **Pure functions**: No side effects, same inputs produce same outputs
- **Immutability**: Data is not modified, new versions are created
- **Composition**: Functions are combined to create complex functionality
- **No classes**: Functions and types are used instead of classes and objects

### Example of pure function:
```typescript
export const createBPMNElement = (config: BPMNElementConfig): DiagramElement => ({
  id: config.id || generateId(),
  type: config.type,
  label: config.label,
  geometry: {
    x: config.x,
    y: config.y,
    width: config.width || getDefaultWidth(config.type),
    height: config.height || getDefaultHeight(config.type)
  },
  style: getBPMNElementStyle(config.type),
  properties: config.properties || {}
});
```

## Development

### Available scripts:
- `npm run build`: Compiles the TypeScript project
- `npm run dev`: Runs in development mode with watch
- `npm start`: Runs the compiled server

### Adding new diagram types:

1. **Add the type in `diagram-types.ts`**:
```typescript
export enum DiagramType {
  // ... existing types
  NEW_DIAGRAM_TYPE = 'new-diagram-type'
}
```

2. **Create generator in `generators/`**:
```typescript
export const generateNewDiagramType = (input: CreateDiagramInput) => {
  // Functional generation logic
};
```

3. **Add to switch in `create-diagram.ts`**:
```typescript
case DiagramType.NEW_DIAGRAM_TYPE:
  return generateNewDiagramType(input);
```

## Requirements

- Node.js 18+
- VSCode with draw.io extension (`hediet.vscode-drawio`)
- Cline with MCP support

## License

MIT License

## Contributing

Contributions are welcome. Please:

1. Fork the project
2. Create a feature branch (`git checkout -b feature/new-feature`)
3. Commit your changes (`git commit -am 'Add new feature'`)
4. Push to the branch (`git push origin feature/new-feature`)
5. Create a Pull Request

## Support

To report bugs or request features, please create an issue in the repository.