figwright

# CLAUDE.md

Read **[AGENTS.md](./AGENTS.md)** first — it's the single source of guidance for this repo: architecture, layout, tech stack, commands, conventions, release flow, and gotchas.

Claude Code specifics:

- This repo **is** a Figma MCP server. The project-scoped `.mcp.json` launches the local build (`packages/mcp/dist/index.mjs`), so after changing `packages/mcp` or `packages/shared` you must `pnpm build` and restart the MCP connection before the `figwright` tools reflect your change.
- There are no git hooks; CI is the gate. When you edit through Claude Code, the PostToolUse hook (`.claude/hooks/format-on-edit.mjs`) auto-formats and lints the file — don't hand-format.
- The canonical checks before pushing are `pnpm typecheck && pnpm lint && pnpm format:check && pnpm knip && pnpm build && pnpm test` (the same gates CI runs).
- The MCP SDK is **v2** — `@modelcontextprotocol/server` (plus its transitive `@modelcontextprotocol/core`), not the v1 `@modelcontextprotocol/sdk`. `src/index.ts` builds the server in a factory and hands it to `serveStdio`, which owns the transport and the protocol-era decision.
- The SDK is a _runtime_ dependency — it generates every tool's JSON Schema and negotiates the protocol version — so a release can move what clients see while `tsc` stays green. `packages/mcp/test/e2e/mcp-wire.test.ts` is the gate for exactly that: it spawns the built `dist` over real stdio, speaks raw JSON-RPC (never the SDK's own `Client`, which would move in lockstep and hide the regression), and asserts the advertised tool set, each schema against an SDK-independent derivation, the dialect, annotations, prompts, a live `tools/call`, that a 2024-11-05 client is still served, that a 2026-07-28 client gets the modern era and is refused the `ping` that revision deleted, and that the process still exits cleanly when the client goes away mid-session. It runs in `pnpm test` but needs `pnpm build` first, and skips when `dist` is missing.
- The **`mcp-sdk-audit`** skill (`.claude/skills/`) owns SDK upgrades. The gate answers _did anything break_; the skill's `probe.mjs` answers _what moved_, by snapshotting the live wire contract before and after a bump and diffing. Reach for it on any `@modelcontextprotocol/*` bump.
- The **`figma-typings-audit`** skill (`.claude/skills/`) owns `@figma/plugin-typings` upgrades end to end: it diffs the `.d.ts` between the installed and target version (that package ships no changelog), maps the result onto the sandbox handlers, the hand-written Zod mirrors in `shared`, and the tool registry, then bumps and implements what's worth having. It diffs _before_ upgrading — the installed version is the baseline. Reach for it on a Renovate bump PR for that package: a green pipeline does **not** mean the update was absorbed, since `shared` mirrors Figma's shapes with no compile-time coupling to the typings.