mcp-excalidraw-server 1.0.5 → 1.0.7

package/README.md

@@ -1,479 +1,504 @@
-# MCP Excalidraw Server: Advanced Live Visual Diagramming with AI Integration
+# Excalidraw MCP Server & Agent Skill
 
-A comprehensive system that combines **Excalidraw's powerful drawing capabilities** with **Model Context Protocol (MCP)** integration, enabling AI agents to create and manipulate diagrams in real-time on a live canvas.
+[![CI](https://github.com/yctimlin/mcp_excalidraw/actions/workflows/ci.yml/badge.svg)](https://github.com/yctimlin/mcp_excalidraw/actions/workflows/ci.yml)
+[![Docker Build & Push](https://github.com/yctimlin/mcp_excalidraw/actions/workflows/docker.yml/badge.svg)](https://github.com/yctimlin/mcp_excalidraw/actions/workflows/docker.yml)
+[![NPM Version](https://img.shields.io/npm/v/mcp-excalidraw-server)](https://www.npmjs.com/package/mcp-excalidraw-server)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## 🏛️ Architecture Overview
+Run a live Excalidraw canvas and control it from AI agents. This repo provides:
 
-This project is now structured as **two independent components**:
+- **MCP Server**: Connect via Model Context Protocol (Claude Desktop, Cursor, Codex CLI, etc.)
+- **Agent Skill**: Portable skill for Claude Code, Codex CLI, and other skill-enabled agents
 
-### **1. MCP Server (Standalone)**
-- **Location**: Main directory (`src/index.js`, `src/types.js`)
-- **Purpose**: Standalone MCP server that can be published as an npm package
-- **Features**: Creates elements locally, optional canvas sync
-- **Dependencies**: Minimal (only MCP SDK, dotenv, node-fetch, winston, zod)
+Keywords: Excalidraw agent skill, Excalidraw MCP server, AI diagramming, Claude Code skill, Codex CLI skill, Claude Desktop MCP, Cursor MCP, Mermaid to Excalidraw.
 
-### **2. Frontend (Optional)**
-- **Location**: `frontend/` directory
-- **Purpose**: Real-time canvas interface with WebSocket synchronization
-- **Features**: Live canvas, WebSocket updates, RESTful API
-- **Dependencies**: React, Excalidraw, Express, WebSocket
+## Demo
 
-```
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
-│   AI Agent      │───▶│   MCP Server     │───▶│  Canvas Server  │
-│   (Claude)      │    │  (src/index.js) │    │ (frontend/)     │
-└─────────────────┘    └──────────────────┘    └─────────────────┘
-        │                        │                       │
-        │                        │                       ▼
-        │                        │              ┌─────────────────┐
-        │                        │              │  Frontend       │
-        │                        │              │  (React + WS)   │
-        │                        │              └─────────────────┘
-        │                        │
-        │                        ▼
-        │               ┌─────────────────┐
-        │               │  Local Storage  │
-        │               │   (elements)    │
-        │               └─────────────────┘
-        │
-        └─────────────────────────────────────────────────────────┘
-                    (Works standalone without frontend)
-```
-
-## 🚀 What This System Does
-
-- **🎨 Live Canvas**: Real-time Excalidraw canvas accessible via web browser (with frontend)
-- **🤖 AI Integration**: MCP server allows AI agents (like Claude) to create visual diagrams
-- **⚡ Real-time Sync**: Elements created via MCP API appear instantly on the canvas (with frontend)
-- **🔄 WebSocket Updates**: Live synchronization across multiple connected clients (with frontend)
-- **🏗️ Standalone Mode**: MCP server works independently for local element creation
-
-## 🎥 Demo Video
+![MCP Excalidraw Demo](demo.gif)
 
-> **See MCP Excalidraw in Action!**
+*AI agent creates a complete architecture diagram from a single prompt (4x speed). [Watch full video on YouTube](https://youtu.be/ufW78Amq5qA)*
 
-[![MCP Excalidraw Demo](https://img.youtube.com/vi/RRN7AF7QIew/maxresdefault.jpg)](https://youtu.be/RRN7AF7QIew)
+## Table of Contents
 
-*Watch how AI agents create and manipulate diagrams in real-time on the live canvas*
+- [Demo](#demo)
+- [What It Is](#what-it-is)
+- [How We Differ from the Official Excalidraw MCP](#how-we-differ-from-the-official-excalidraw-mcp)
+- [What's New](#whats-new)
+- [Quick Start (Local)](#quick-start-local)
+- [Quick Start (Docker)](#quick-start-docker)
+- [Configure MCP Clients](#configure-mcp-clients)
+  - [Claude Desktop](#claude-desktop)
+  - [Claude Code](#claude-code)
+  - [Cursor](#cursor)
+  - [Codex CLI](#codex-cli)
+  - [OpenCode](#opencode)
+  - [Antigravity (Google)](#antigravity-google)
+- [Agent Skill (Optional)](#agent-skill-optional)
+- [MCP Tools (26 Total)](#mcp-tools-26-total)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+- [Known Issues / TODO](#known-issues--todo)
+- [Development](#development)
 
-## 🌟 Key Features
+## What It Is
 
-### **Standalone MCP Server**
-- Works independently without frontend dependencies
-- Creates and manages elements locally
-- Optional canvas synchronization when frontend is available
-- Can be published as an npm package
+This repo contains two separate processes:
 
-### **Real-time Canvas Integration** (with frontend)
-- Elements created via MCP appear instantly on the live canvas
-- WebSocket-based real-time synchronization
-- Multi-client support with live updates
+- Canvas server: web UI + REST API + WebSocket updates (default `http://127.0.0.1:3000`)
+- MCP server: exposes MCP tools over stdio; syncs to the canvas via `EXPRESS_SERVER_URL`
 
-### **Production-Ready Interface** (with frontend)
-- Clean, minimal UI with connection status
-- Simple "Clear Canvas" functionality
-- No development clutter or debug information
+## How We Differ from the Official Excalidraw MCP
 
-### **Comprehensive MCP API**
-- **Element Creation**: rectangles, ellipses, diamonds, arrows, text, lines
-- **Element Management**: update, delete, query with filters
-- **Batch Operations**: create multiple elements in one call
-- **Advanced Features**: grouping, alignment, distribution, locking
+Excalidraw now has an [official MCP](https://github.com/excalidraw/excalidraw-mcp) — it's great for quick, prompt-to-diagram generation rendered inline in chat. We solve a different problem.
 
-### **Robust Architecture**
-- Express.js backend with REST API + WebSocket (frontend)
-- React frontend with official Excalidraw package (frontend)
-- Dual-path element loading for reliability
-- Auto-reconnection and error handling
+| | Official Excalidraw MCP | This Project |
+|---|---|---|
+| **Approach** | Prompt in, diagram out (one-shot) | Programmatic element-level control (26 tools) |
+| **State** | Stateless — each call is independent | Persistent live canvas with real-time sync |
+| **Element CRUD** | No | Full create / read / update / delete per element |
+| **AI sees the canvas** | No | `describe_scene` (structured text) + `get_canvas_screenshot` (image) |
+| **Iterative refinement** | No — regenerate the whole diagram | Draw → look → adjust → look again, element by element |
+| **Layout tools** | No | `align_elements`, `distribute_elements`, `group / ungroup` |
+| **File I/O** | No | `export_scene` / `import_scene` (.excalidraw JSON) |
+| **Snapshot & rollback** | No | `snapshot_scene` / `restore_snapshot` |
+| **Mermaid conversion** | No | `create_from_mermaid` |
+| **Shareable URLs** | Yes | Yes — `export_to_excalidraw_url` |
+| **Design guide** | `read_me` cheat sheet | `read_diagram_guide` (colors, sizing, layout, anti-patterns) |
+| **Viewport control** | Camera animations | `set_viewport` (zoom-to-fit, center on element, manual zoom) |
+| **Live canvas UI** | Rendered inline in chat | Standalone Excalidraw app synced via WebSocket |
+| **Multi-agent** | Single user | Multiple agents can draw on the same canvas concurrently |
+| **Works without MCP** | No | Yes — REST API fallback via agent skill |
 
-## 📦 Installation & Setup
+**TL;DR** — The official MCP generates diagrams. We give AI agents a full canvas toolkit to build, inspect, and iteratively refine diagrams — including the ability to see what they drew.
 
-### **✅ Option 1: MCP Server Only (Standalone)**
+## What's New
 
-Use this if you only need the MCP server functionality without the visual canvas.
+### v2.0 — Canvas Toolkit
 
-#### **1. Clone the Repository**
-```bash
-git clone https://github.com/yctimlin/mcp_excalidraw.git
-cd mcp_excalidraw
-npm install
-```
-
-#### **2. Start the MCP Server**
-```bash
-npm start
-```
+- 13 new MCP tools (26 total): `get_element`, `clear_canvas`, `export_scene`, `import_scene`, `export_to_image`, `duplicate_elements`, `snapshot_scene`, `restore_snapshot`, `describe_scene`, `get_canvas_screenshot`, `read_diagram_guide`, `export_to_excalidraw_url`, `set_viewport`
+- **Closed feedback loop**: AI can now inspect the canvas (`describe_scene`) and see it (`get_canvas_screenshot` returns an image) — enabling iterative refinement
+- **Design guide**: `read_diagram_guide` returns best-practice color palettes, sizing rules, layout patterns, and anti-patterns — dramatically improves AI-generated diagram quality
+- **Shareable URLs**: `export_to_excalidraw_url` encrypts and uploads the scene to excalidraw.com, returns a shareable link anyone can open
+- **Viewport control**: `set_viewport` with `scrollToContent`, `scrollToElementId`, or manual zoom/offset — agents can auto-fit diagrams after creation
+- **File I/O**: export/import full `.excalidraw` JSON files
+- **Snapshots**: save and restore named canvas states
+- **Skill fallback**: Agent skill auto-detects MCP vs REST API mode, gracefully falls back to HTTP endpoints when MCP server isn't configured
+- Fixed all previously known issues: `align_elements` / `distribute_elements` fully implemented, points type normalization, removed invalid `label` type, removed HTTP transport dead code, `ungroup_elements` now errors on failure
 
-The MCP server will run and create elements locally. Set `ENABLE_CANVAS_SYNC=false` to disable canvas synchronization attempts.
+### v1.x
 
-### **✅ Option 2: MCP Server + Frontend (Full System)**
+- Agent skill: `skills/excalidraw-skill/` (portable instructions + helper scripts for export/import and repeatable CRUD)
+- Better testing loop: MCP Inspector CLI examples + browser screenshot checks (`agent-browser`)
+- Bugfixes: batch create now preserves element ids (fixes update/delete after batch); frontend entrypoint fixed (`main.tsx`)
 
-Use this for the complete system with live canvas visualization.
+## Quick Start (Local)
 
-#### **1. Clone and Setup Main Package**
-```bash
-git clone https://github.com/yctimlin/mcp_excalidraw.git
-cd mcp_excalidraw
-npm install
-```
+Prereqs: Node >= 18, npm
 
-#### **2. Setup Frontend**
 ```bash
-cd frontend
-npm install
+npm ci
 npm run build
 ```
 
-#### **3. Start the System**
-
-##### **Option A: Production Mode (Recommended)**
+Terminal 1: start the canvas
 ```bash
-# Terminal 1: Start frontend server
-cd frontend
-npm start
-
-# Terminal 2: Start MCP server (in main directory)
-cd ..
-npm start
+PORT=3000 npm run canvas
 ```
 
-##### **Option B: Development Mode**
-```bash
-# Terminal 1: Start frontend in dev mode
-cd frontend
-npm run dev
+> **Security note:** The server defaults to binding on `127.0.0.1` only. If you need to expose it on a network interface (e.g. Docker, remote access), set `HOST=0.0.0.0` — but ensure you have network-level access controls in place, as the API has no built-in authentication.
 
-# Terminal 2: Start MCP server (in main directory)
-cd ..
-npm start
-```
+Open `http://127.0.0.1:3000`.
 
-#### **4. Access the Canvas**
-Open your browser and navigate to:
-```
-http://localhost:3000
+Terminal 2: run the MCP server (stdio)
+```bash
+EXPRESS_SERVER_URL=http://127.0.0.1:3000 node dist/index.js
 ```
 
-### **🐳 Option 3: Docker (Full System)**
-
-Use Docker Compose to run both components:
+## Quick Start (Docker)
 
+Canvas server:
 ```bash
-docker-compose up
+docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest
 ```
 
-This will start both the MCP server and frontend in containers.
+MCP server (stdio) is typically launched by your MCP client (Claude Desktop/Cursor/etc.). If you want a local container for it, use the image `ghcr.io/yctimlin/mcp_excalidraw:latest` and set `EXPRESS_SERVER_URL` to point at the canvas.
+
+## Configure MCP Clients
 
-## 🔧 Available Scripts
+The MCP server runs over stdio and can be configured with any MCP-compatible client. Below are configurations for both **local** (requires cloning and building) and **Docker** (pull-and-run) setups.
 
-### **Main Package (MCP Server)**
-| Script | Description |
-|--------|-------------|
-| `npm start` | Start MCP server (`src/index.js`) |
+### Environment Variables
 
-### **Frontend Package**
-| Script | Description |
-|--------|-------------|
-| `npm start` | Start Express server (`server.js`) |
-| `npm run build` | Build React frontend for production |
-| `npm run dev` | Start Express + Vite dev server |
-| `npm run preview` | Preview built frontend |
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `EXPRESS_SERVER_URL` | URL of the canvas server | `http://127.0.0.1:3000` |
+| `ENABLE_CANVAS_SYNC` | Enable real-time canvas sync | `true` |
 
-## 🎯 Usage Guide
+---
 
-### **For End Users**
-1. Open the canvas at `http://localhost:3000` (if using frontend)
-2. Check connection status (should show "Connected")
-3. AI agents can now create diagrams that appear in real-time
-4. Use "Clear Canvas" to remove all elements
+### Claude Desktop
 
-### **For AI Agents (via MCP)**
-The MCP server provides these tools for creating visual diagrams:
+Config location:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
 
-#### **Basic Element Creation**
-```javascript
-// Create a rectangle
+**Local (node)**
+```json
 {
-  "type": "rectangle",
-  "x": 100,
-  "y": 100, 
-  "width": 200,
-  "height": 100,
-  "backgroundColor": "#e3f2fd",
-  "strokeColor": "#1976d2",
-  "strokeWidth": 2
+  "mcpServers": {
+    "excalidraw": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
+      "env": {
+        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
+        "ENABLE_CANVAS_SYNC": "true"
+      }
+    }
+  }
 }
 ```
 
-#### **Create Text Elements**
-```javascript
+**Docker**
+```json
 {
-  "type": "text",
-  "x": 150,
-  "y": 125,
-  "text": "Process Step",
-  "fontSize": 16,
-  "strokeColor": "#333333"
+  "mcpServers": {
+    "excalidraw": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
+        "-e", "ENABLE_CANVAS_SYNC=true",
+        "ghcr.io/yctimlin/mcp_excalidraw:latest"
+      ]
+    }
+  }
 }
 ```
 
-#### **Create Arrows & Lines**
-```javascript
-{
-  "type": "arrow",
-  "x": 300,
-  "y": 130,
-  "width": 100,
-  "height": 0,
-  "strokeColor": "#666666",
-  "strokeWidth": 2
-}
+---
+
+### Claude Code
+
+Use the `claude mcp add` command to register the MCP server.
+
+**Local (node)** - User-level (available across all projects):
+```bash
+claude mcp add excalidraw --scope user \
+  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
+  -e ENABLE_CANVAS_SYNC=true \
+  -- node /absolute/path/to/mcp_excalidraw/dist/index.js
 ```
 
-#### **Batch Creation for Complex Diagrams**
-```javascript
-{
-  "elements": [
-    {
-      "type": "rectangle",
-      "x": 100,
-      "y": 100,
-      "width": 120,
-      "height": 60,
-      "backgroundColor": "#fff3e0",
-      "strokeColor": "#ff9800"
-    },
-    {
-      "type": "text", 
-      "x": 130,
-      "y": 125,
-      "text": "Start",
-      "fontSize": 16
-    }
-  ]
-}
+**Local (node)** - Project-level (shared via `.mcp.json`):
+```bash
+claude mcp add excalidraw --scope project \
+  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
+  -e ENABLE_CANVAS_SYNC=true \
+  -- node /absolute/path/to/mcp_excalidraw/dist/index.js
 ```
 
-## 🔌 Integration with Claude Desktop
+**Docker**
+```bash
+claude mcp add excalidraw --scope user \
+  -- docker run -i --rm \
+  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
+  -e ENABLE_CANVAS_SYNC=true \
+  ghcr.io/yctimlin/mcp_excalidraw:latest
+```
+
+**Manage servers:**
+```bash
+claude mcp list              # List configured servers
+claude mcp remove excalidraw # Remove a server
+```
 
-### **✅ Recommended: Using Local Installation**
+---
 
-For the **local development version** (most stable), add this configuration to your `claude_desktop_config.json`:
+### Cursor
 
+Config location: `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global config)
+
+**Local (node)**
 ```json
 {
   "mcpServers": {
     "excalidraw": {
       "command": "node",
-      "args": ["/absolute/path/to/mcp_excalidraw/src/index.js"]
+      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
+      "env": {
+        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
+        "ENABLE_CANVAS_SYNC": "true"
+      }
+    }
+  }
+}
+```
+
+**Docker**
+```json
+{
+  "mcpServers": {
+    "excalidraw": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
+        "-e", "ENABLE_CANVAS_SYNC=true",
+        "ghcr.io/yctimlin/mcp_excalidraw:latest"
+      ]
     }
   }
 }
 ```
 
-**Important**: Replace `/absolute/path/to/mcp_excalidraw` with the actual absolute path to your cloned repository.
+---
+
+### Codex CLI
 
-### **🔧 Alternative Configurations (Beta)**
+Use the `codex mcp add` command to register the MCP server.
 
-#### **NPM Package (Beta Testing)**
+**Local (node)**
+```bash
+codex mcp add excalidraw \
+  --env EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
+  --env ENABLE_CANVAS_SYNC=true \
+  -- node /absolute/path/to/mcp_excalidraw/dist/index.js
+```
+
+**Docker**
+```bash
+codex mcp add excalidraw \
+  -- docker run -i --rm \
+  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
+  -e ENABLE_CANVAS_SYNC=true \
+  ghcr.io/yctimlin/mcp_excalidraw:latest
+```
+
+**Manage servers:**
+```bash
+codex mcp list              # List configured servers
+codex mcp remove excalidraw # Remove a server
+```
+
+---
+
+### OpenCode
+
+Config location: `~/.config/opencode/opencode.json` or project-level `opencode.json`
+
+**Local (node)**
 ```json
 {
-  "mcpServers": {
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
     "excalidraw": {
-      "command": "npx",
-      "args": ["-y", "mcp-excalidraw-server"]
+      "type": "local",
+      "command": ["node", "/absolute/path/to/mcp_excalidraw/dist/index.js"],
+      "enabled": true,
+      "environment": {
+        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
+        "ENABLE_CANVAS_SYNC": "true"
+      }
     }
   }
 }
 ```
-*Currently debugging tool registration - let us know if you encounter issues!*
 
-#### **Docker Version (Coming Soon)**
+**Docker**
 ```json
 {
-  "mcpServers": {
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
     "excalidraw": {
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "mcp-excalidraw-server"]
+      "type": "local",
+      "command": ["docker", "run", "-i", "--rm", "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000", "-e", "ENABLE_CANVAS_SYNC=true", "ghcr.io/yctimlin/mcp_excalidraw:latest"],
+      "enabled": true
     }
   }
 }
 ```
-*Canvas sync improvements in progress.*
 
-## 🔧 Integration with Other Tools
+---
 
-### **Cursor IDE**
+### Antigravity (Google)
 
-Add to your `.cursor/mcp.json`:
+Config location: `~/.gemini/antigravity/mcp_config.json`
 
+**Local (node)**
 ```json
 {
   "mcpServers": {
     "excalidraw": {
       "command": "node",
-      "args": ["/absolute/path/to/mcp_excalidraw/src/index.js"]
+      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
+      "env": {
+        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
+        "ENABLE_CANVAS_SYNC": "true"
+      }
     }
   }
 }
 ```
 
-### **VS Code MCP Extension**
-
-For VS Code MCP extension, add to your settings:
-
+**Docker**
 ```json
 {
-  "mcp": {
-    "servers": {
-      "excalidraw": {
-        "command": "node",
-        "args": ["/absolute/path/to/mcp_excalidraw/src/index.js"]
-      }
+  "mcpServers": {
+    "excalidraw": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
+        "-e", "ENABLE_CANVAS_SYNC=true",
+        "ghcr.io/yctimlin/mcp_excalidraw:latest"
+      ]
     }
   }
 }
 ```
 
-## 🛠️ Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `EXPRESS_SERVER_URL` | `http://localhost:3000` | Canvas server URL for MCP sync |
-| `ENABLE_CANVAS_SYNC` | `true` | Enable/disable canvas synchronization |
-| `DEBUG` | `false` | Enable debug logging |
-| `PORT` | `3000` | Canvas server port |
-| `HOST` | `localhost` | Canvas server host |
-
-## 📊 API Endpoints
-
-The canvas server provides these REST endpoints:
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/elements` | Get all elements |
-| `POST` | `/api/elements` | Create new element |
-| `PUT` | `/api/elements/:id` | Update element |
-| `DELETE` | `/api/elements/:id` | Delete element |
-| `POST` | `/api/elements/batch` | Create multiple elements |
-| `GET` | `/health` | Server health check |
-
-## 🎨 MCP Tools Available
-
-### **Element Management**
-- `create_element` - Create any type of Excalidraw element
-- `update_element` - Modify existing elements
-- `delete_element` - Remove elements
-- `query_elements` - Search elements with filters
-
-### **Batch Operations**
-- `batch_create_elements` - Create complex diagrams in one call
-
-### **Element Organization**  
-- `group_elements` - Group multiple elements
-- `ungroup_elements` - Ungroup element groups
-- `align_elements` - Align elements (left, center, right, top, middle, bottom)
-- `distribute_elements` - Distribute elements evenly
-- `lock_elements` / `unlock_elements` - Lock/unlock elements
-
-### **Resource Access**
-- `get_resource` - Access scene, library, theme, or elements data
-
-## 🏗️ Development Architecture
-
-### **Frontend** (`frontend/src/`)
-- **React + Vite**: Modern build system
-- **Official Excalidraw**: `@excalidraw/excalidraw` package
-- **WebSocket Client**: Real-time element sync
-- **Clean UI**: Production-ready interface
-
-### **Canvas Server** (`src/server.js`)
-- **Express.js**: REST API + static file serving
-- **WebSocket**: Real-time client communication  
-- **Element Storage**: In-memory with persistence options
-- **CORS**: Cross-origin support
-
-### **MCP Server** (`src/index.js`)
-- **MCP Protocol**: Standard Model Context Protocol
-- **Canvas Sync**: HTTP requests to canvas server
-- **Element Management**: Full CRUD operations
-- **Batch Support**: Complex diagram creation
-
-## 🐛 Troubleshooting
-
-### **NPM Package Issues**
-- **Symptoms**: MCP tools not registering properly
-- **Temporary Solution**: Use local development setup
-- **Status**: Actively debugging - updates coming soon
-
-### **Docker Version Notes**
-- **Symptoms**: Elements may not sync to canvas immediately
-- **Temporary Solution**: Use local development setup
-- **Status**: Improving synchronization reliability
-
-### **Canvas Not Loading**
-- Ensure `npm run build` completed successfully
-- Check that `dist/index.html` exists
-- Verify canvas server is running on port 3000
-
-### **Elements Not Syncing**
-- Confirm MCP server is running (`npm start`)
-- Check `ENABLE_CANVAS_SYNC=true` in environment
-- Verify canvas server is accessible at `EXPRESS_SERVER_URL`
-
-### **WebSocket Connection Issues**  
-- Check browser console for WebSocket errors
-- Ensure no firewall blocking WebSocket connections
-- Try refreshing the browser page
-
-### **Build Errors**
-- Delete `node_modules` and run `npm install`
-- Check Node.js version (requires 16+)
-- Ensure all dependencies are installed
-
-## 📋 Project Structure
+---
+
+### Notes
+
+- **Docker networking**: Use `host.docker.internal` to reach the canvas server running on your host machine. On Linux, you may need `--add-host=host.docker.internal:host-gateway` or use `172.17.0.1`.
+- **Canvas server**: Must be running before the MCP server connects. Start it with `npm run canvas` (local) or `docker run -d -p 3000:3000 ghcr.io/yctimlin/mcp_excalidraw-canvas:latest` (Docker).
+- **Absolute paths**: When using local node setup, replace `/absolute/path/to/mcp_excalidraw` with the actual path where you cloned and built the repo.
+- **In-memory storage**: The canvas server stores elements in memory. Restarting the server will clear all elements. Use the export/import scripts if you need persistence.
+
+## Agent Skill (Optional)
+
+This repo includes a skill at `skills/excalidraw-skill/` that provides:
+
+- **Workflow playbook** (`SKILL.md`): step-by-step guidance for drawing, refining, and exporting diagrams
+- **Cheatsheet** (`references/cheatsheet.md`): MCP tool and REST API reference
+- **Helper scripts** (`scripts/*.cjs`): export, import, clear, healthcheck, CRUD operations
+
+The skill complements the MCP server by giving your AI agent structured workflows to follow.
+
+### Install The Skill (Codex CLI example)
+
+```bash
+mkdir -p ~/.codex/skills
+cp -R skills/excalidraw-skill ~/.codex/skills/excalidraw-skill
+```
+
+To update an existing installation, remove the old folder first (`rm -rf ~/.codex/skills/excalidraw-skill`) then re-copy.
+
+### Install The Skill (Claude Code)
+
+**User-level** (available across all your projects):
+```bash
+mkdir -p ~/.claude/skills
+cp -R skills/excalidraw-skill ~/.claude/skills/excalidraw-skill
+```
+
+**Project-level** (scoped to a specific project, can be committed to the repo):
+```bash
+mkdir -p /path/to/your/project/.claude/skills
+cp -R skills/excalidraw-skill /path/to/your/project/.claude/skills/excalidraw-skill
+```
+
+Then invoke the skill in Claude Code with `/excalidraw-skill`.
+
+To update an existing installation, remove the old folder first then re-copy.
+
+### Use The Skill Scripts
+
+All scripts respect `EXPRESS_SERVER_URL` (default `http://127.0.0.1:3000`) or accept `--url`.
+
+```bash
+EXPRESS_SERVER_URL=http://127.0.0.1:3000 node skills/excalidraw-skill/scripts/healthcheck.cjs
+EXPRESS_SERVER_URL=http://127.0.0.1:3000 node skills/excalidraw-skill/scripts/export-elements.cjs --out diagram.elements.json
+EXPRESS_SERVER_URL=http://127.0.0.1:3000 node skills/excalidraw-skill/scripts/import-elements.cjs --in diagram.elements.json --mode batch
+```
+
+### When The Skill Is Useful
+
+- Repository workflow: export elements as JSON, commit it, and re-import later.
+- Reliable refactors: clear + re-import in `sync` mode to make canvas match a file.
+- Automated smoke tests: create/update/delete a known element to validate a deployment.
+- Repeatable diagrams: keep a library of element JSON snippets and import them.
+
+See `skills/excalidraw-skill/SKILL.md` and `skills/excalidraw-skill/references/cheatsheet.md`.
+
+## MCP Tools (26 Total)
+
+| Category | Tools |
+|---|---|
+| **Element CRUD** | `create_element`, `get_element`, `update_element`, `delete_element`, `query_elements`, `batch_create_elements`, `duplicate_elements` |
+| **Layout** | `align_elements`, `distribute_elements`, `group_elements`, `ungroup_elements`, `lock_elements`, `unlock_elements` |
+| **Scene Awareness** | `describe_scene`, `get_canvas_screenshot` |
+| **File I/O** | `export_scene`, `import_scene`, `export_to_image`, `export_to_excalidraw_url`, `create_from_mermaid` |
+| **State Management** | `clear_canvas`, `snapshot_scene`, `restore_snapshot` |
+| **Viewport** | `set_viewport` |
+| **Design Guide** | `read_diagram_guide` |
+| **Resources** | `get_resource` |
+
+Full schemas are discoverable via `tools/list` or in `skills/excalidraw-skill/references/cheatsheet.md`.
+
+## Testing
+
+### Canvas Smoke Test (HTTP)
 
+```bash
+curl http://127.0.0.1:3000/health
 ```
-mcp_excalidraw/
-├── frontend/
-│   ├── src/
-│   │   ├── App.jsx          # Main React component
-│   │   └── main.jsx         # React entry point
-│   └── index.html           # HTML template
-├── src/
-│   ├── index.js            # MCP server
-│   ├── server.js           # Canvas server (Express + WebSocket)
-│   ├── types.js            # Shared types and utilities
-│   └── utils/
-│       └── logger.js       # Logging utility
-├── dist/                   # Built frontend (generated)
-├── vite.config.js         # Vite build configuration
-├── package.json           # Dependencies and scripts
-└── README.md              # This file
+
+### Local Bind Regression Test
+
+```bash
+npm run test:bind
 ```
 
-## 🔮 Development Roadmap
+### MCP Smoke Test (MCP Inspector)
 
-- **NPM Package**: Resolving MCP tool registration issues
-- **Docker Deployment**: Improving canvas synchronization
-- **Enhanced Features**: Additional MCP tools and capabilities
-- **Performance Optimization**: Real-time sync improvements
+List tools:
+```bash
+npx @modelcontextprotocol/inspector --cli \
+  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
+  -e ENABLE_CANVAS_SYNC=true -- \
+  node dist/index.js --method tools/list
+```
 
-## 🤝 Contributing
+Create a rectangle:
+```bash
+npx @modelcontextprotocol/inspector --cli \
+  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
+  -e ENABLE_CANVAS_SYNC=true -- \
+  node dist/index.js --method tools/call --tool-name create_element \
+  --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 \
+  --tool-arg width=300 --tool-arg height=200
+```
 
-We welcome contributions! If you're experiencing issues with the NPM package or Docker version, please:
+### Frontend Screenshots (agent-browser)
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+If you use `agent-browser` for UI checks:
+```bash
+agent-browser install
+agent-browser open http://127.0.0.1:3000
+agent-browser wait --load networkidle
+agent-browser screenshot /tmp/canvas.png
+```
+
+## Troubleshooting
+
+- Canvas not updating: confirm `EXPRESS_SERVER_URL` points at the running canvas server.
+- Updates/deletes fail after batch creation: ensure you are on a build that includes the batch id preservation fix (merged via PR #34).
+
+## Known Issues / TODO
 
-## 📝 License
+All previously listed bugs have been fixed in v2.0. Remaining items:
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+- [ ] **Persistent storage**: Elements are stored in-memory — restarting the server clears everything. Use `export_scene` / snapshots as a workaround.
+- [ ] **Image export requires a browser**: `export_to_image` and `get_canvas_screenshot` rely on the frontend doing the actual rendering. The canvas UI must be open in a browser.
 
-## 🙏 Acknowledgments
+Contributions welcome!
 
-- **Excalidraw Team** - For the amazing drawing library
-- **MCP Community** - For the Model Context Protocol specification
+## Development
+
+```bash
+npm run type-check
+npm run build
+```