# Excalidraw MCP Agent 🎨

Local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that generates beautifully formatted, hand-drawn Excalidraw diagrams (`.excalidraw`) directly from natural language text prompts or structured descriptions.

---

## 🌟 Features

- **Prompt-to-Diagram Generator**: Create complex architecture diagrams, flowcharts, and system pipelines directly from free-text prompts (`generate_diagram_from_prompt`).
- **Structured MCP Control**: Fine-grained shape control (`create_excalidraw_diagram`) supporting Rectangles, Diamonds, Ellipses, and Arrow labels.
- **Dynamic Geometry Engine**:
  - Auto-calculates box dimensions and text metrics to eliminate text clipping.
  - Native Virgil hand-drawn font rendering with 100% mathematical text centering inside containers.
  - Smart perimeter intersection math (`getNodeEdgePoint`) preventing arrows from crossing through shapes.
  - Directional perpendicular arrow label offsets preventing line collisions.
- **Excalidraw Browser Integration**: Open generated diagrams directly on [excalidraw.com](https://excalidraw.com) via `open_excalidraw_diagram`.

---

## 📦 Installation & Setup

### 1. Clone & Install Dependencies

```bash
git clone https://github.com/Anuraj4/Excalidraw-MCP-Agent.git
cd Excalidraw-MCP-Agent
npm install
```

### 2. Link Binary Globally

Link the package binary globally so any MCP client can run `excalidraw-mcp-agent`:

```bash
npm link
```

---

## ⚙️ MCP Client Configuration

Add the server entry to your MCP client configuration file (e.g. **Claude Desktop**, **Cursor**, **VS Code**, or **Antigravity Desktop**):

### Option A: Using the Globally Linked Command (Recommended)

```json
{
  "mcpServers": {
    "excalidraw": {
      "command": "excalidraw-mcp-agent",
      "env": {
        "EXCALIDRAW_WORKSPACE": "C:\\path\\to\\your\\workspace"
      }
    }
  }
}
```

### Option B: Using Node Directly

```json
{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": [
        "C:\\path\\to\\Excalidraw-MCP-Agent\\src\\server.js"
      ],
      "env": {
        "EXCALIDRAW_WORKSPACE": "C:\\path\\to\\your\\workspace"
      }
    }
  }
}
```

---

## 🛠️ Available MCP Tools

| Tool | Description |
| :--- | :--- |
| `generate_diagram_from_prompt` | Generates a complete Excalidraw diagram directly from a natural language prompt string. |
| `create_excalidraw_diagram` | Generates a diagram from structured `nodes` and `arrows` with custom geometry and colors. |
| `list_excalidraw_diagrams` | Lists all `.excalidraw` diagram files in the current workspace directory. |
| `open_excalidraw_diagram` | Launches [excalidraw.com](https://excalidraw.com) in your browser to inspect or edit a file. |

---

## 🎨 Diagram Palette & Style Guidelines

The builder applies color palettes and shape semantics automatically according to standard architectural conventions:

| Component Type | Color | Shape |
| :--- | :--- | :--- |
| **Actors / Users / Clients** | `purple` | Ellipse |
| **Ingestion / Data Sources** | `blue` | Rectangle |
| **Processing / Logic** | `green` | Rectangle |
| **Database / Vector DB / Storage** | `cyan` | Rectangle |
| **Decisions / Conditionals** | `yellow` | Diamond |
| **Output / ERP / External Systems** | `orange` | Rectangle |
| **Exceptions / Errors / Warnings** | `red` | Rectangle |

---

## 💡 Prompt Examples

Once configured, simply interact with your AI assistant using prompts like:

- **RAG Architecture**:
  > *"Create an Excalidraw diagram for a RAG system: User uploads PDFs -> Chunking & embedding -> Vector DB -> User query -> Similarity search -> LLM answer generation."*

- **Invoice Extraction Pipeline**:
  > *"Generate an Excalidraw flowchart for Invoice Data Extraction: Supplier submits invoice -> Document Ingestion -> Classification (Invoice vs Receipt) -> Check valid invoice -> Key data extraction -> Validation rules check -> ERP integration export (if valid) or Exception Queue (if error)."*

---

## 🧪 Testing

Run unit tests and end-to-end stdio MCP integration tests:

```bash
npm test
```

---

## 📄 License

[MIT](LICENSE)