figwright CLAUDE.md

CLAUDE.md

Read 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.