@sanjibdevnath/mcp-excalidraw-local 1.0.0

package/skills/excalidraw-skill/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: excalidraw-skill
+description: Programmatic canvas toolkit for creating, editing, and refining Excalidraw diagrams via MCP tools (32 tools) or REST API with real-time canvas sync, multi-tenant workspace isolation, SQLite persistence, project management, full-text search, and element version history. Use when an agent needs to draw or lay out diagrams on a live canvas, iteratively refine diagrams using screenshots, manage workspaces/tenants and projects, export/import .excalidraw files or PNG/SVG images, search elements, view change history, save/restore canvas snapshots, or perform element-level CRUD. Canvas server port is configurable via CANVAS_PORT env var (default 3000).
+---
+
+# Excalidraw Skill
+
+## Step 0: Detect Connection Mode
+
+Run these checks **in order**:
+
+1. **MCP Server** (best): If tools like `batch_create_elements` are available → use MCP mode.
+2. **REST API** (fallback): `curl -s http://localhost:3000/health` returns `{"status":"ok"}` → use REST API mode.
+3. **Nothing works**: Guide user to install (clone `sanjibdevnathlabs/mcp-excalidraw-local`, build, configure MCP).
+
+See `references/cheatsheet.md` for the full MCP-vs-REST mapping and REST API gotchas.
+
+## Core Principles (Read Before Any Diagram)
+
+These principles were learned through extensive iterative use. Violating them produces bad diagrams.
+
+### 1. Never Trust Blind Output — Use the Write-Check-Review Cycle
+
+Every diagram iteration follows this mandatory loop:
+
+```
+WRITE (create/update elements)
+  → CHECK (screenshot to see actual rendering)
+    → REVIEW (critically evaluate against Quality Checklist)
+      → FIX (if issues found, fix and re-screenshot)
+        → only proceed when ALL checks pass
+```
+
+**Screenshot strategy**: `get_canvas_screenshot` may return empty images. When it fails, use Chrome DevTools MCP (`take_screenshot` after `navigate_page` to canvas URL) as a reliable fallback.
+
+### 2. Use batch_create_elements, Not Mermaid
+
+The `create_from_mermaid` tool produces **low-quality output**: overlapping text, poor spacing, unreadable labels. It is a quick preview tool, not a production tool.
+
+For quality diagrams, **always use `batch_create_elements`** with precise coordinates, explicit sizing, and color coding. The extra planning time pays for itself in fewer fix iterations.
+
+### 3. Shapes First, Arrows Second — Two Separate Batches
+
+Create shapes in one batch, then arrows in a separate batch. Arrow binding (`startElementId`/`endElementId`) requires shapes to already exist in the scene. Mixing both in one call can work but often produces binding errors.
+
+### 4. Multiple Diagrams on One Canvas
+
+**Never clear the canvas** between diagrams. Place them side-by-side or in a grid:
+
+```
+Diagram 1: x=0 to ~1100
+Diagram 2: x=1400 onward  (300px gap)
+— or —
+Row 1: y=0 to ~800
+Row 2: y=1100 onward  (300px gap)
+```
+
+Use a title text element above each diagram to label it.
+
+### 5. Set roughness: 0 for Clean Diagrams
+
+Excalidraw defaults to hand-drawn style (roughness > 0). For professional, readable diagrams, always set `"roughness": 0` on every element. Also use `"strokeWidth": 2` for arrows to ensure visibility.
+
+## Sizing Rules (Critical — Prevents Truncation)
+
+Excalidraw's Virgil font is ~30% wider than standard fonts. These rules account for that.
+
+### Rectangles
+
+```
+width:  max(200, characterCount * 11)
+height: 70 (1 line), 80 (2 lines), 100 (3 lines)
+fontSize: 16-20
+```
+
+### Diamonds (Decision Nodes)
+
+Diamond usable text area is ~50% of the bounding box. **Double your width estimate.**
+
+```
+width:  max(400, longestLineChars * 18)
+height: max(160, lineCount * 50)
+fontSize: 16
+```
+
+A diamond with text "Behavioral guideline\nor project standard?" (20 chars) needs at least 400x160.
+
+### Ellipses
+
+Ellipse text area is ~60% of bounding box. Size generously.
+
+```
+width:  max(280, characterCount * 14)
+height: max(65, lineCount * 35)
+fontSize: 16-18
+```
+
+### Text Elements (Standalone Titles)
+
+```
+fontSize: 24-28 for diagram titles
+fontSize: 16-20 for annotations
+```
+
+## Arrow Visibility Rules (Critical — Prevents Invisible Arrows)
+
+When arrows are bound to shapes via `startElementId`/`endElementId`, the actual rendered arrow length equals the **gap between shape edges minus binding padding (8px each side)**. If shapes are too close, arrows shrink to 0px and become invisible.
+
+### Minimum Gap Between Connected Shapes
+
+| Connection Direction | Minimum Gap | Recommended Gap |
+|---------------------|-------------|-----------------|
+| Vertical (top-down flow) | 80px | 120px |
+| Horizontal (left-right) | 100px | 140px |
+
+### Calculating Vertical Gap for Flowcharts
+
+```
+gap = nextShapeY - (currentShapeY + currentShapeHeight)
+
+Example (diamonds h=160, gap needed ≥ 120):
+  Q1: y=260, h=160 → bottom edge = 420
+  Q2: y=540         → gap = 540 - 420 = 120px ✓
+```
+
+If the gap is < 80px, arrows will be too short to see — especially with labels like "YES"/"NO".
+
+## Workflow: Draw A Diagram
+
+### Phase 1: Plan
+
+Before writing any JSON, plan on paper:
+
+1. **List all elements**: shapes, labels, connections
+2. **Choose layout direction**: top-down (flowcharts), left-right (timelines), grid (architecture)
+3. **Assign coordinates**: use the sizing rules above to compute widths/heights, then lay out with proper gaps
+4. **Assign IDs**: every shape needs a custom `id` so arrows can reference it
+
+### Phase 2: Create Shapes (Batch 1)
+
+```json
+{"elements": [
+  {"id": "title", "type": "text", "x": 100, "y": 0,
+   "text": "MY DIAGRAM", "fontSize": 28, "strokeColor": "#1e1e1e"},
+  {"id": "box-a", "type": "rectangle", "x": 0, "y": 80,
+   "width": 200, "height": 70, "text": "Service A",
+   "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2",
+   "roughness": 0, "fontSize": 18},
+  {"id": "box-b", "type": "rectangle", "x": 0, "y": 280,
+   "width": 200, "height": 70, "text": "Service B",
+   "backgroundColor": "#b2f2bb", "strokeColor": "#2f9e44",
+   "roughness": 0, "fontSize": 18}
+]}
+```
+
+### Phase 3: Create Arrows (Batch 2)
+
+```json
+{"elements": [
+  {"type": "arrow", "x": 100, "y": 150,
+   "startElementId": "box-a", "endElementId": "box-b",
+   "width": 0, "height": 130, "text": "calls",
+   "strokeColor": "#1e1e1e", "roughness": 0, "strokeWidth": 2,
+   "endArrowhead": "arrow"}
+]}
+```
+
+### Phase 4: Check (MANDATORY)
+
+1. `set_viewport` with `scrollToContent: true`
+2. Wait 1-2 seconds for render
+3. Take screenshot (MCP `get_canvas_screenshot` or Chrome DevTools `take_screenshot`)
+4. **Critically evaluate** against the Quality Checklist below
+5. Fix any issues, re-screenshot, repeat until clean
+
+## Quality Checklist
+
+After EVERY batch of elements, verify ALL of these:
+
+| Check | What to Look For | Fix |
+|-------|-----------------|-----|
+| **Text truncation** | Any label cut off or hidden? | Increase shape width/height |
+| **Invisible arrows** | Can you see arrows between all connected shapes? | Increase gap between shapes to ≥ 120px |
+| **Arrow labels** | Do YES/NO/labels overlap with shapes? | Shorten labels or increase gap |
+| **Overlap** | Do any elements share space? | Reposition with more spacing |
+| **Readability** | Can all text be read at 50-70% zoom? | Increase fontSize to ≥ 16 |
+| **Spacing** | At least 40px gap between unconnected elements? | Spread elements apart |
+
+### If ANY Check Fails
+
+**STOP.** Do not add more elements. Fix the issue first:
+
+1. Use `update_element` to resize/reposition
+2. Or `delete_element` + recreate with better coordinates
+3. Re-screenshot to verify the fix
+4. Only proceed when ALL checks pass
+
+### How to Honestly Evaluate a Screenshot
+
+- Zoom into different regions — don't just glance at the overview
+- Check every label individually for truncation
+- Trace every arrow path for visibility
+- **If you see ANY issue, say "I see [issue], fixing it"** — never say "looks great" unless it truly is
+
+## Color Palette
+
+Use consistent colors from this palette:
+
+| Role | Fill | Stroke | Use For |
+|------|------|--------|---------|
+| Primary | #a5d8ff | #1971c2 | Main flow, services |
+| Success | #b2f2bb | #2f9e44 | Approved, healthy, YES paths |
+| Warning | #ffd8a8 | #e8590c | Attention, agents |
+| Error | #ffc9c9 | #e03131 | Critical, NO paths, failures |
+| Purple | #eebefa | #9c36b5 | Rules, governance |
+| Cyan | #99e9f2 | #0c8599 | Data stores, MCP |
+| Neutral | #e9ecef | #868e96 | Secondary, annotations |
+| Default | #ffffff | #1e1e1e | Decisions, generic |
+
+## Flowchart Template (Tested & Verified)
+
+This template produces clean, readable decision flowcharts:
+
+```
+Layout:
+  Diamonds: w=400, h=160, fontSize=16, gap=120px vertical
+  Answer boxes: w=300, h=80, fontSize=20, offset 130px right of diamonds
+  Start ellipse: w=340, h=70, fontSize=18
+  Title: fontSize=28
+  Arrows: strokeWidth=2, roughness=0
+  YES arrows: strokeColor=#2f9e44 (green), horizontal right
+  NO arrows: strokeColor=#e03131 (red), vertical down
+  All elements: roughness=0
+```
+
+## Architecture Diagram Template
+
+```
+Layout:
+  Zones: large rectangles, backgroundColor=#e9ecef, opacity=30
+  Services: w=200, h=70, fontSize=18, spaced 60px apart
+  Data stores: w=180, h=60, fontSize=16, strokeColor=#0c8599
+  Arrows: solid for sync, dashed (strokeStyle="dashed") for async
+  Title: fontSize=24 above each zone
+```
+
+## Workflow: Iterative Refinement
+
+```
+create shapes (batch 1)
+  → create arrows (batch 2)
+    → set_viewport(scrollToContent: true)
+      → wait 1-2s
+        → screenshot
+          → evaluate quality checklist
+            → issues? fix → re-screenshot → re-evaluate
+              → clean? proceed to next diagram section
+```
+
+For multi-diagram canvases, offset each new diagram by 300px+ from the previous one's bounding box.
+
+## Workflow: Multi-Tenancy (Workspaces)
+
+The MCP is multi-tenant. Each Cursor workspace automatically gets its own tenant (identified by a SHA-256 hash of the workspace path). All elements, projects, and snapshots are scoped to the active tenant.
+
+### Automatic Tenant Detection
+
+On MCP startup, the server:
+1. Creates a tenant from `process.cwd()` (initial guess)
+2. After connecting, calls `server.listRoots()` to get the real workspace path from Cursor
+3. If different, re-creates/switches to the correct tenant and notifies the canvas
+
+This means globally-configured MCPs (`~/.cursor/mcp.json`) correctly detect the per-window workspace — no manual setup needed.
+
+### Tenant Operations
+
+| Task | Tool | Notes |
+|------|------|-------|
+| See all workspaces | `list_tenants` | Returns id, name, workspace_path, created_at |
+| Switch workspace | `switch_tenant` with `tenantId` | Canvas reloads that tenant's elements via WebSocket |
+| Check current tenant | (from describe_scene or frontend header) | Shows "Workspace: [name]" in canvas |
+
+### Multiple Cursor Instances
+
+Each instance sends its own `X-Tenant-Id` header on every HTTP/MCP request. SQLite uses `busy_timeout` for concurrent write safety. No state conflicts between windows.
+
+## Workflow: Projects (Within a Tenant)
+
+Projects group diagrams within a tenant. Each tenant has a "Default Project" created automatically. Use projects to organize different diagram sets (e.g., "Architecture", "User Flows", "Sprint Planning").
+
+| Task | Tool | Notes |
+|------|------|-------|
+| List projects | `list_projects` | Shows all projects in active tenant |
+| Switch project | `switch_project` with `projectId` | Elements change to that project's set |
+| Create new project | `switch_project` with `createName` | Creates and switches in one call |
+
+## Workflow: Search & History
+
+### Full-Text Search
+
+`search_elements` with `query` — searches across element labels and text content in the active project. Useful for finding specific elements in large diagrams.
+
+### Element Version History
+
+`element_history` — view create/update/delete operations for:
+- A specific element: pass `elementId`
+- Entire active project: omit `elementId`
+- Control result count with `limit` (default 50)
+
+Use history to debug unexpected changes or audit what was modified.
+
+## Workflow: Refine An Existing Diagram
+
+1. `describe_scene` to understand current state
+2. Identify targets by `id` or label text (or use `search_elements` for text search)
+3. `update_element` to move/resize/recolor
+4. Screenshot to verify
+5. If updates fail: check element id exists (`get_element`), element isn't locked
+6. Use `element_history` to see what changed if something looks wrong
+
+## Workflow: File I/O
+
+- Export: `export_scene` (optional `filePath`)
+- Import: `import_scene` with `mode: "replace"` or `"merge"`
+- Image export: `export_to_image` with `format: "png"` or `"svg"` (requires browser)
+
+## Workflow: Snapshots
+
+1. `snapshot_scene` with a name before risky changes
+2. Make changes, screenshot to evaluate
+3. `restore_snapshot` to rollback if needed
+
+**Note**: Snapshot restore may not always reload elements into the active view. If the canvas appears empty after restore, re-fetch elements or recreate.
+
+## Workflow: Viewport Control
+
+- `scrollToContent: true` — auto-fit all elements
+- `scrollToElementId: "my-element"` — center on specific element
+- `zoom: 0.7, offsetX: 100, offsetY: 50` — manual camera for close-up review
+
+## Anti-Patterns (Common Mistakes)
+
+| Mistake | Why It Fails | Do This Instead |
+|---------|-------------|-----------------|
+| Using `create_from_mermaid` for final diagrams | Overlapping text, poor layout | Use `batch_create_elements` with coordinates |
+| Shapes too small for text | Truncation, especially in diamonds | Use sizing formulas above |
+| No gap between connected shapes | Arrows become invisible (0px length) | Maintain 120px+ vertical gap |
+| Clearing canvas between diagrams | Loses previous work | Place diagrams side-by-side |
+| Skipping screenshot verification | Invisible defects compound | Screenshot after EVERY batch |
+| Shapes + arrows in one batch | Binding errors | Shapes first, arrows second |
+| Default roughness (hand-drawn look) | Unprofessional for technical diagrams | Set `roughness: 0` on all elements |
+| Trusting MCP screenshot alone | May return empty image | Use Chrome DevTools as fallback |
+
+## MCP Tool Quick Reference (32 Tools)
+
+| Category | Tools |
+|----------|-------|
+| Element CRUD (9) | `create_element`, `get_element`, `update_element`, `delete_element`, `query_elements`, `batch_create_elements`, `duplicate_elements`, `search_elements`, `element_history` |
+| Layout (6) | `align_elements`, `distribute_elements`, `group_elements`, `ungroup_elements`, `lock_elements`, `unlock_elements` |
+| Scene (4) | `describe_scene`, `get_canvas_screenshot`, `get_resource`, `read_diagram_guide` |
+| File I/O (4) | `export_scene`, `import_scene`, `export_to_image`, `export_to_excalidraw_url` |
+| State (3) | `clear_canvas`, `snapshot_scene`, `restore_snapshot` |
+| Viewport (1) | `set_viewport` |
+| Tenants (2) | `list_tenants`, `switch_tenant` |
+| Projects (2) | `list_projects`, `switch_project` |
+| Conversion (1) | `create_from_mermaid` (⚠ low quality — use `batch_create_elements` instead) |
+
+## References
+
+- `references/cheatsheet.md`: Complete MCP tool list (32 tools) + REST API endpoints + payload shapes + env vars

package/skills/excalidraw-skill/references/cheatsheet.md

@@ -0,0 +1,195 @@
+# Excalidraw Skill Cheatsheet
+
+## Defaults
+
+- Canvas base URL: configurable via `CANVAS_PORT` env var (default `3000`), resolves to `http://localhost:<CANVAS_PORT>`
+- Canvas health: `GET /health`
+- Data persistence: SQLite database at `~/.excalidraw-mcp/excalidraw.db`
+- Multi-tenancy: each Cursor workspace auto-creates a tenant (hash of workspace path)
+
+## MCP Tools (32 total)
+
+### Element CRUD
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `create_element` | Create shape/text/arrow/line | `type`, `x`, `y` |
+| `get_element` | Get single element by ID | `id` |
+| `update_element` | Update element properties | `id` |
+| `delete_element` | Delete element | `id` |
+| `query_elements` | Query by type | (optional) `type` |
+| `batch_create_elements` | Create many at once (recommended) | `elements[]` |
+| `duplicate_elements` | Clone with offset | `elementIds[]`, (optional) `offsetX`, `offsetY` |
+| `search_elements` | Full-text search over labels/text | `query` |
+| `element_history` | View version history (create/update/delete ops) | (optional) `elementId`, `limit` (default 50) |
+
+### Layout & Organization
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `align_elements` | Align to left/center/right/top/middle/bottom | `elementIds[]`, `alignment` |
+| `distribute_elements` | Even spacing horizontal/vertical | `elementIds[]`, `direction` |
+| `group_elements` | Group elements | `elementIds[]` |
+| `ungroup_elements` | Ungroup | `groupId` |
+| `lock_elements` | Lock elements | `elementIds[]` |
+| `unlock_elements` | Unlock elements | `elementIds[]` |
+
+### Scene Awareness (Iterative Refinement)
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `describe_scene` | AI-readable scene description (types, positions, labels, connections, bounding box) | (none) |
+| `get_canvas_screenshot` | Returns PNG image of canvas for visual verification (may return empty — use Chrome DevTools as fallback) | (optional) `background` |
+| `get_resource` | Get scene/library/theme/elements | `resource` |
+| `read_diagram_guide` | Get design best practices (colors, sizing, layout, anti-patterns) | (none) |
+
+### File I/O & Export
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `export_scene` | Export to .excalidraw JSON | (optional) `filePath` |
+| `import_scene` | Import from .excalidraw JSON | `mode` ("replace"\|"merge"), `filePath` or `data` |
+| `export_to_image` | Export to PNG/SVG (needs browser) | `format` ("png"\|"svg"), (optional) `filePath`, `background` |
+| `export_to_excalidraw_url` | Upload & get shareable excalidraw.com URL (may fail if org blocks excalidraw.com) | (none) |
+
+### State Management
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `clear_canvas` | Remove all elements from active project | (none) |
+| `snapshot_scene` | Save named snapshot of current canvas state | `name` |
+| `restore_snapshot` | Restore from snapshot (may not reload into view — re-fetch if canvas appears empty) | `name` |
+
+### Viewport & Camera
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `set_viewport` | Control camera: zoom-to-fit, center on element, manual zoom/scroll (needs browser) | (optional) `scrollToContent`, `scrollToElementId`, `zoom`, `offsetX`, `offsetY` |
+
+### Multi-Tenancy (Workspaces)
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `list_tenants` | List all tenants (workspaces). Each tenant maps to a Cursor workspace. | (none) |
+| `switch_tenant` | Switch active tenant. All later operations use that tenant's projects/elements. | `tenantId` |
+
+### Projects (Within a Tenant)
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `list_projects` | List all diagram projects in the active tenant | (none) |
+| `switch_project` | Switch active project or create a new one | (optional) `projectId`, `createName`, `createDescription` |
+
+### Conversion
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `create_from_mermaid` | Mermaid diagram to Excalidraw (⚠ produces low-quality output — use `batch_create_elements` for production diagrams) | `mermaidDiagram` |
+
+## Key Notes
+
+### MCP vs REST API Format Differences
+
+| Concept | MCP Tool Format | REST API Format |
+|---------|----------------|-----------------|
+| Shape labels | `"text": "My Label"` (auto-converts) | `"label": {"text": "My Label"}` |
+| Arrow binding | `"startElementId": "id"` / `"endElementId": "id"` | `"start": {"id": "id"}` / `"end": {"id": "id"}` |
+| `fontFamily` | String `"1"` or omit | String `"1"` or omit (never a number) |
+| Tenant scoping | Auto (uses active tenant) | Include `X-Tenant-Id` header on every request |
+
+### Element Creation Best Practices
+
+- **Always set `roughness: 0`** for clean, professional diagrams (default is hand-drawn).
+- **Always set `strokeWidth: 2`** on arrows for visibility.
+- **Create shapes first, arrows second** (two separate `batch_create_elements` calls).
+- **Assign custom `id`** to every shape so arrows can reference it.
+- **Size shapes for their text** — Virgil font is ~30% wider than standard. Use sizing formulas from SKILL.md.
+- `points` accepts both `[[x,y]]` tuples and `[{x,y}]` objects — normalized automatically.
+- **Curved arrows**: Use `"roundness": {"type": 2}` with 3+ points. **Elbowed arrows**: Use `"elbowed": true`.
+
+### Multi-Tenancy Architecture
+
+- **Tenant**: Maps to a Cursor workspace. Auto-created on MCP startup from workspace path hash.
+- **Project**: Groups diagrams within a tenant. Default project created per tenant.
+- **Elements**: Belong to the active project within the active tenant.
+- **Hierarchy**: Tenant → Project → Elements
+- **Concurrent instances**: Multiple Cursor windows each send `X-Tenant-Id` header for isolation. SQLite `busy_timeout` handles concurrent writes.
+- **Frontend workspace switcher**: Dropdown in the canvas UI header labeled "Workspace: [name] ▾" with search filter.
+
+## Canvas REST API (HTTP)
+
+All endpoints accept an optional `X-Tenant-Id` header to scope operations to a specific tenant.
+
+### Elements
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/elements` | List all elements in active project |
+| `GET` | `/api/elements/:id` | Get element by ID |
+| `POST` | `/api/elements` | Create element |
+| `PUT` | `/api/elements/:id` | Update element |
+| `DELETE` | `/api/elements/:id` | Delete element |
+| `DELETE` | `/api/elements/clear` | Clear all elements |
+| `GET` | `/api/elements/search?type=...` | Search with filters |
+| `POST` | `/api/elements/batch` | Batch create |
+| `POST` | `/api/elements/sync` | Full sync (clear + write all elements) |
+| `POST` | `/api/elements/from-mermaid` | Mermaid conversion via frontend |
+
+### Tenants
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/tenants` | List all tenants |
+| `GET` | `/api/tenant/active` | Get active tenant |
+| `PUT` | `/api/tenant/active` | Switch active tenant `{"tenantId": "..."}` (broadcasts to all WebSocket clients) |
+
+### Export
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/export/image` | Request image export (needs browser) |
+| `POST` | `/api/export/image/result` | Frontend posts export result back |
+
+### Viewport
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/viewport` | Set viewport/camera (needs browser) |
+| `POST` | `/api/viewport/result` | Frontend posts viewport result back |
+
+### Snapshots
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/snapshots` | Save snapshot `{"name": "..."}` |
+| `GET` | `/api/snapshots` | List all snapshots |
+| `GET` | `/api/snapshots/:name` | Get snapshot by name |
+
+### System
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/health` | Health check |
+| `GET` | `/api/sync/status` | Element count and WebSocket stats |
+
+## Skill Scripts
+
+All scripts accept `--url <canvasUrl>` (defaults to `EXPRESS_SERVER_URL`).
+
+```bash
+node scripts/healthcheck.cjs
+node scripts/clear-canvas.cjs
+node scripts/export-elements.cjs --out diagram.elements.json
+node scripts/import-elements.cjs --in diagram.elements.json --mode batch|sync
+node scripts/create-element.cjs --data '{...}'
+node scripts/update-element.cjs --id <id> --data '{...}'
+node scripts/delete-element.cjs --id <id>
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CANVAS_PORT` | `3000` | Port the canvas server listens on |
+| `EXPRESS_SERVER_URL` | `http://localhost:3000` | Full canvas URL (derived from CANVAS_PORT if not set) |
+| `EXCALIDRAW_EXPORT_DIR` | `process.cwd()` | Allowed base directory for file exports (path traversal protection) |

package/skills/excalidraw-skill/scripts/clear-canvas.cjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const DEFAULT_URL = process.env.EXPRESS_SERVER_URL || "http://localhost:3000";
+
+function parseArgs(argv) {
+  const out = { url: DEFAULT_URL };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+  }
+  return out;
+}
+
+async function main() {
+  if (typeof fetch !== "function") {
+    throw new Error("This script requires Node 18+ (global fetch).");
+  }
+
+  const { url } = parseArgs(process.argv.slice(2));
+  const baseUrl = url.replace(/\/$/, "");
+
+  const res = await fetch(`${baseUrl}/api/elements/clear`, {
+    method: "DELETE",
+  });
+
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json || json.success !== true) {
+    throw new Error(`Failed to clear canvas: ${res.status} ${res.statusText} ${json?.error ? `- ${json.error}` : ""}`);
+  }
+
+  console.log(`Cleared canvas (${json.count} elements removed)`);
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/skills/excalidraw-skill/scripts/create-element.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require("node:fs");
+
+const DEFAULT_URL = process.env.EXPRESS_SERVER_URL || "http://localhost:3000";
+
+function usage() {
+  console.error(
+    [
+      "Usage:",
+      "  node scripts/create-element.cjs (--data <json> | --file <path>) [--url <canvasUrl>]",
+      "",
+      "Examples:",
+      '  node scripts/create-element.cjs --data \'{"type":"rectangle","x":100,"y":100,"width":300,"height":200}\'',
+      "  node scripts/create-element.cjs --file element.json",
+    ].join("\n"),
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const out = { url: DEFAULT_URL, data: null, file: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+    else if (a === "--data") out.data = argv[++i];
+    else if (a === "--file") out.file = argv[++i];
+  }
+  return out;
+}
+
+function readJson({ data, file }) {
+  if (data) return JSON.parse(data);
+  if (file) return JSON.parse(fs.readFileSync(file, "utf8"));
+  usage();
+}
+
+async function main() {
+  if (typeof fetch !== "function") {
+    throw new Error("This script requires Node 18+ (global fetch).");
+  }
+
+  const args = parseArgs(process.argv.slice(2));
+  const payload = readJson(args);
+
+  const baseUrl = args.url.replace(/\/$/, "");
+  const res = await fetch(`${baseUrl}/api/elements`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json || json.success !== true) {
+    throw new Error(
+      `Failed to create element: ${res.status} ${res.statusText} ${json?.error ? `- ${json.error}` : ""}`,
+    );
+  }
+
+  process.stdout.write(JSON.stringify(json.element, null, 2) + "\n");
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});
+