# 🎨 Code Visualizer MCP

An MCP server that generates **Excalidraw diagrams** to visualize algorithm execution step-by-step. Give it your code + an example input, and get a single `.excalidraw` file showing every iteration.

![Python](https://img.shields.io/badge/Python-3.10+-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![MCP](https://img.shields.io/badge/MCP-Compatible-purple)

![Code Visualizer Output](examples/image.png)

---

## ✨ Features

- **Single-file traces** — All iterations in ONE `.excalidraw` diagram
- **12 data structures** — Array, LinkedList, Tree, Graph, HashMap, Stack, Queue, Matrix, Heap, Trie, Priority Queue, Set
- **Dark-mode palette** — YouTube-friendly colors with semantic highlighting
- **MCP + CLI** — Use via AI assistants (Claude, Cursor, Gemini) or command line

## 📐 Supported Data Structures

| Data Structure | Type Key | Visualization |
|:---|:---|:---|
| Array | `array` | Horizontal cells with index labels + pointer arrows |
| Linked List | `linkedlist` | Nodes with next-pointers and cycle detection |
| Binary Tree | `tree` | Hierarchical layout with parent-child edges |
| Graph | `graph` | Circular layout with directed/undirected edges |
| HashMap | `hashmap` | Vertical key-value pair list |
| Stack | `stack` | Vertical cells with TOP label |
| Queue | `queue` | Horizontal cells with FRONT/REAR labels |
| Matrix | `matrix` | 2D grid with row/col labels |
| Heap | `heap` | Binary tree + array representation |
| Priority Queue | `priority_queue` | Same as heap |
| Trie | `trie` | Tree with character-labeled edges |
| Set | `set` | Rounded-rectangle collection |

---

## 🚀 Quick Start

### Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Installation

```bash
git clone https://github.com/your-username/code-visualizer-mcp.git
cd code-visualizer-mcp
uv sync
```

### 🔌 Client Integration & Ways to Use

This MCP server is standard Model Context Protocol compliant and works with a variety of AI assistants and IDEs:

#### 1. Claude Desktop
Add to `claude_desktop_config.json` (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "code-visualizer": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/code-visualizer-mcp",
        "run",
        "code-visualizer"
      ]
    }
  }
}
```

#### 2. Google Antigravity (AGY)
Add to your Antigravity MCP config file (`~/.gemini/antigravity/mcp_config.json` or your project settings):

```json
{
  "mcpServers": {
    "code-visualizer": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/code-visualizer-mcp",
        "run",
        "code-visualizer"
      ]
    }
  }
}
```

#### 3. Cursor IDE
1. Open **Cursor Settings** > **Features** > **MCP**.
2. Click **+ Add New MCP Server**.
3. Set **Name**: `code-visualizer`, **Type**: `stdio`
4. Set **Command**:
   ```bash
   uv --directory /absolute/path/to/code-visualizer-mcp run code-visualizer
   ```

#### 4. VS Code (Cline / Roo Code / Continue)
Add to your extension's MCP settings file (e.g. `cline_mcp_settings.json`):

```json
{
  "mcpServers": {
    "code-visualizer": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/code-visualizer-mcp",
        "run",
        "code-visualizer"
      ]
    }
  }
}
```

#### 5. MCP Inspector (Interactive Testing)
To test and debug tools directly in a browser UI without an AI assistant:

```bash
npx @modelcontextprotocol/inspector uv --directory /absolute/path/to/code-visualizer-mcp run code-visualizer
```

### CLI Usage

```bash
# Generate an array diagram
uv run python examples/generate_cli.py array \
  --title "Two Sum" \
  --data "2,7,11,15" \
  --highlights "0:visited,1:found" \
  --pointers "i:1"

# Generate a full algorithm trace
uv run python examples/sliding_window_maximum.py
```

Output files are saved to the `output/` directory as `.excalidraw` files. Open them at [excalidraw.com](https://excalidraw.com) or in the VS Code Excalidraw extension.

---

## 🏗️ Project Structure

```
code-visualizer-mcp/
├── pyproject.toml                 # Project config, dependencies, entry points
├── LICENSE
├── README.md
│
├── src/code_visualizer/           # Main package
│   ├── __init__.py
│   ├── server.py                  # MCP server entry point (FastMCP)
│   ├── renderer.py                # Excalidraw JSON file writer
│   │
│   ├── primitives/                # Low-level element factories
│   │   ├── elements.py            # make_rectangle, make_ellipse, make_arrow, ...
│   │   ├── colors.py              # Semantic color palette (PALETTE, get_color)
│   │   └── styles.py              # Style presets (CELL_STYLE, NODE_STYLE, ...)
│   │
│   ├── layout/                    # Spatial position calculators
│   │   ├── linear.py              # Arrays, matrices, stacks, queues, hashmaps, sets
│   │   ├── tree_layout.py         # Binary trees, heaps, tries
│   │   └── graph_layout.py        # Circular graph layout
│   │
│   └── tools/                     # MCP tool implementations
│       ├── visualize_array.py     # Array + hashmap diagrams
│       ├── visualize_linkedlist.py
│       ├── visualize_tree.py
│       ├── visualize_graph.py
│       └── visualize_trace.py     # ⭐ Multi-step trace (primary tool)
│
├── tests/                         # Test suite
│   ├── conftest.py                # Shared fixtures
│   ├── test_primitives.py         # Element factory tests
│   └── test_tools.py              # Tool integration tests
│
├── examples/                      # Usage examples
│   ├── generate_cli.py            # CLI diagram generator
│   └── sliding_window_maximum.py  # Full algorithm trace example
│
├── docs/
│   └── architecture.md            # System architecture & workflow guide
│
└── output/                        # Generated .excalidraw files 
```

---

## 🧪 Running Tests

```bash
uv run pytest -v
```

---

## 🎨 Color Palette

| Color Name | Use Case | Preview |
|:---|:---|:---|
| `default` | Unvisited elements | ⬛ |
| `current` | Currently processing | 🟧 |
| `highlighted` | Active window/range | 🟦 |
| `visited` | Already processed | ⬜ |
| `found` | Match / answer found | 🟨 |
| `comparing` | Being compared | 🟠 |
| `swapping` | Being swapped | 🩷 |
| `pointer_a` / `pointer_b` / `pointer_c` | Named pointers | 🟩🟪💛 |
| `success` / `error` | Result indicators | ✅❌ |

---

## 📄 License

MIT — see [LICENSE](LICENSE).