# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Build & Development Commands
```bash
# Install dependencies (uses Bun)
bun install
# Build all packages
bun run build
# Build specific package
bun run build --filter=@caelinsutch/mcp-server
bun run build --filter=@caelinsutch/relay-server
bun run build --filter=@caelinsutch/figma-plugin
# Type checking
bun run type:check
# Linting (uses Biome)
bun run lint
bun run lint:fix
# Development mode
bun run --filter=@caelinsutch/relay-server dev # Relay server with hot reload
bun run --filter=@caelinsutch/figma-plugin dev # Figma plugin with hot reload
# Run relay server
bun run --filter=@caelinsutch/relay-server start
# Run MCP server directly
node apps/mcp-server/dist/index.js
```
## Architecture
This is a Turborepo monorepo enabling AI agents (Claude) to manipulate Figma designs via MCP (Model Context Protocol).
### Communication Flow
```
Claude (MCP Client) <--stdio--> MCP Server <--WebSocket--> Relay Server <--WebSocket--> Figma Plugin
```
1. **MCP Server** (`apps/mcp-server`): Exposes 50+ tools to Claude via stdio transport. Connects to relay server to forward commands.
2. **Relay Server** (`apps/relay-server`): Bun WebSocket server on port 3055. Routes messages between MCP server and Figma plugin via named channels.
3. **Figma Plugin** (`apps/figma-plugin`): Runs inside Figma, executes commands on the design document, returns results.
### Key Patterns
**Tool Registration**: MCP tools are registered in `apps/mcp-server/src/tools/index.ts`. Each tool module (document.ts, shapes.ts, etc.) exports a `register*Tools(server)` function.
**Command Handling**: Commands flow through:
- MCP Server: `sendCommandToFigma()` in `apps/mcp-server/src/communication/client.ts`
- Relay Server: Broadcasts to channel peers in `apps/relay-server/src/server.ts`
- Figma Plugin: `handleCommand()` switch statement in `apps/figma-plugin/src/plugin/handlers/index.ts`
**Adding New Tools**: Create handler in both:
1. `apps/mcp-server/src/tools/<category>.ts` - MCP tool definition with Zod schema
2. `apps/figma-plugin/src/plugin/handlers/<category>.ts` - Figma API implementation
3. Register in respective `index.ts` files and add case to handler switch
**Shared Types**: `packages/types` contains TypeScript types shared across all packages. Import from `@caelinsutch/types`.
### Tool Categories
Tools are organized by feature: document, nodes, shapes, text, styling, transform, layout, components, annotations, export, selection, prototyping, scanning, variables.
## Code Style
- Uses Biome for linting/formatting (tab indentation, double quotes)
- TypeScript strict mode
- ESM modules throughout
