tldraw-mcp-server: Instructions file for Codex

AGENTS.md — tldraw MCP Server

Guidance for AI agents (AdaL, Claude Code, Codex CLI, etc.) working in this repository.

What This Project Is

An MCP (Model Context Protocol) server that gives AI agents programmatic control over a live tldraw infinite canvas. Two processes run together:

1. Canvas Server (src/canvas-server.ts) — Express HTTP + WebSocket server on port 3000. Owns the in-memory element store and broadcasts mutations to connected browsers.
2. MCP Server (src/index.ts) — Stdio MCP server. Validates tool calls with Zod and proxies them to the canvas server via HTTP REST.
3. Frontend (frontend/src/App.tsx) — React + tldraw app. Connects to canvas server via WebSocket, applies all mutations to the tldraw editor in real time.

Repository Layout

tldraw-mcp-server/
├── src/
│   ├── index.ts          # MCP server entry point — 27 tools, Zod schemas
│   ├── canvas-server.ts  # Express + WebSocket canvas server — REST CRUD + snapshot
│   ├── types.ts          # Shared types: CanvasElement, WSMessage, ApiResponse, generateId
│   ├── layout/
│   │   ├── engine.ts     # Main layout engine entry point
│   │   ├── dagre.ts      # Hierarchical layout using @dagrejs/dagre
│   │   ├── force.ts      # Force-directed layout using d3-force
│   │   ├── grid.ts       # Grid layout algorithm
│   │   ├── graph.ts      # Graph building helpers for layout algorithms
│   │   └── types.ts      # Layout types and interfaces
│   └── export/
│       ├── svg.ts        # SVG generation from elements
│       └── pdf.ts        # PDF export using Playwright or pdf-lib fallback
├── frontend/
│   ├── src/
│   │   ├── App.tsx       # React component — WS sync, tldraw shape mapping
│   │   └── main.tsx      # React entry point
│   ├── index.html
│   ├── vite.config.ts    # Dev proxy /api → :3000, build → dist/public
│   ├── tsconfig.json
│   └── package.json
├── dist/                 # Compiled backend (tsc output) — gitignored
│   └── public/           # Compiled frontend (vite build output) — gitignored
├── .mcp.json             # Project-level MCP config for AdaL CLI / Claude Code
├── package.json          # Root — backend deps + build scripts
└── tsconfig.json         # Backend TS config