🎨 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.

---

✨ 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 (recommended) or pip

Installation

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):

{
  "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):

{
  "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:

   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):

{
  "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:

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

CLI Usage

# 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 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

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.