eaccmk_excalidraw-mcp: Instructions file for Claude Code

Excalidraw MCP App Server

Standalone MCP server that streams Excalidraw diagrams as SVG with hand-drawn animations.

Architecture

server.ts          → 2 tools (read_me, create_view) + resource + cheat sheet
main.ts            → HTTP (Streamable) + stdio transports
src/mcp-app.tsx    → ExcalidrawAppCore (widget logic) + ExcalidrawApp (useApp wrapper)
src/mcp-entry.tsx  → Production entry point: createRoot + ExcalidrawApp
src/global.css     → Animations (stroke draw-on, fade-in) + auto-resize
src/dev.tsx        → Dev entry point: mock app + sample elements + control panel
src/dev-mock.ts    → Mock MCP App with event simulation (sendToolInput, streamElements, etc.)
index-dev.html     → Dev HTML entry (served by vite dev server)
vite.config.dev.ts → Dev-only vite config (resolves from node_modules, no esm.sh externals)

Tools

read_me (text tool, no UI)

Returns a cheat sheet with element format, color palettes, coordinate tips, and examples. The model should call this before create_view.

create_view (UI tool)

Takes elements — a JSON string of standard Excalidraw elements. The widget parses partial JSON during streaming and renders via exportToSvg + morphdom diffing. No Excalidraw React canvas component — pure SVG rendering.

Screenshot as model context: After final render, the SVG is captured as a 512px-max PNG and sent via app.updateModelContext() so the model can see the diagram and iterate on user feedback.

Key Design Decisions

Standard Excalidraw JSON — no extensions

The input is standard Excalidraw element JSON. No label on containers, no start/end on arrows. These are Excalidraw's internal "skeleton" API (convertToExcalidrawElements) — not the standard format.

Why: Standard format means any .excalidraw file's elements array works as input.

Trade-off: Labels require separate text elements with manually computed centered coordinates. The cheat sheet teaches the formula: x = shape.x + (shape.width - text.width) / 2.