drawio-mcp-server/README.md

# Draw.io MCP Server

An MCP (Model Context Protocol) server for AI-powered diagram generation using draw.io. This server exposes tools to create intelligent diagrams of different types (BPMN, UML, ER, Architecture, etc.) through Streamable HTTP.

## 🚀 Features

- **AI-powered diagram generation**: Create diagrams from natural language descriptions
- **Multiple diagram types**: BPMN, UML, ER, Architecture, Networks, and more
- **MCP over HTTP Protocol**: Compatible with MCP clients using Streamable HTTP
- **Session management**: Support for multiple concurrent sessions
- **REST API**: Additional endpoints for monitoring and documentation

## 📋 Supported Diagram Types

### BPMN (Business Process Model and Notation)
- Business processes
- Collaborations
- Choreographies

### UML (Unified Modeling Language)
- Class diagrams
- Sequence diagrams
- Use case diagrams
- Activity diagrams
- State diagrams
- Component diagrams
- Deployment diagrams

### Database
- ER (Entity-Relationship) diagrams
- Database schemas
- Conceptual models

### Architecture
- System architecture
- Microservices
- Layered architecture
- C4 diagrams (Context, Container, Component)
- Cloud architecture

### Network & Infrastructure
- Network topology
- Infrastructure
- Cloud architecture

### General
- Flowcharts
- Organizational charts
- Mind maps
- Wireframes
- Gantt charts

## 🛠️ Installation

```bash
# Clone the repository
git clone <repository-url>
cd drawio-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start
```

## 🌐 Usage with Streamable HTTP

The server exposes an MCP endpoint through Streamable HTTP at `http://localhost:3000/mcp`.

### Available Endpoints

- **POST /mcp**: Client-to-server MCP communication
- **GET /mcp**: Server-to-client notifications via Server-Sent Events
- **DELETE /mcp**: Session termination
- **GET /health**: Server health check
- **GET /**: API documentation

### Configuration for Cline

To use with Cline, add the following configuration to your MCP file:

```json
{
  "mcpServers": {
    "drawio-diagram-generator": {
      "command": "node",
      "args": ["build/index.js"],
      "cwd": "/path/to/drawio-mcp-server",
      "env": {
        "HTTP_PORT": "3000"
      }
    }
  }
}
```

## 🔧 Available MCP Tools

### `create_diagram`
Creates a new diagram with intelligent AI-based generation.

**Parameters:**
- `name` (required): Diagram file name
- `type` (required): Diagram type (see supported types)
- `description` (recommended): Natural language description for AI generation
- `format` (optional): File format (default: 'drawio')
- `outputPath` (optional): Output directory
- `complexity` (optional): 'simple' or 'detailed' (default: 'detailed')
- `language` (optional): Language for labels (default: 'es')

**Example:**
```json
{
  "name": "sales-process",
  "type": "bpmn-process",
  "description": "Sales process from initial contact to closure, including follow-up and billing",
  "complexity": "detailed",
  "language": "en"
}
```

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

## 📚 Available MCP Resources

### `diagrams://types/supported`
Provides information about all supported diagram types.

## 🧪 Usage Examples

### Create a BPMN diagram
```json
{
  "tool": "create_diagram",
  "arguments": {
    "name": "purchase-process",
    "type": "bpmn-process",
    "description": "Corporate purchasing process including request, approval, purchase order, receipt and payment"
  }
}
```

### Create an architecture diagram
```json
{
  "tool": "create_diagram",
  "arguments": {
    "name": "microservices-architecture",
    "type": "microservices",
    "description": "Microservices architecture for e-commerce with API Gateway, user, product, order and payment services"
  }
}
```

### Create an ER diagram
```json
{
  "tool": "create_diagram",
  "arguments": {
    "name": "store-data-model",
    "type": "er-diagram",
    "description": "Data model for online store with users, products, categories, orders and payments"
  }
}
```

## 🔍 Monitoring

### Check server status
```bash
curl http://localhost:3000/health
```

### View documentation
Visit `http://localhost:3000/` in your browser to see the complete API documentation.

## 🏗️ Architecture

The server is built with:

- **Express.js**: HTTP server
- **MCP SDK**: Communication protocol with MCP clients
- **TypeScript**: Static typing
- **AI Generators**: Intelligent analysis of descriptions
- **Draw.io**: Compatible diagram format

### Project Structure

```
src/
├── index.ts                 # Main server with Streamable HTTP
├── types/                   # TypeScript type definitions
├── tools/                   # MCP tools
├── ai/                      # AI analyzer for descriptions
├── generators/              # Intelligent diagram generators
└── utils/                   # Utilities for format conversion
```

## 🤝 Contributing

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

## 📄 License

This project is under the MIT License. See the `LICENSE` file for more details.

## 🆘 Support

If you encounter any issues or have questions:

1. Check the documentation at `http://localhost:3000/`
2. Verify server status at `http://localhost:3000/health`
3. Check server logs for specific errors
4. Open an issue in the project repository

---

Enjoy creating intelligent diagrams with AI! 🎨✨