figma-to-code-mcp: Instructions file for Codex

AGENTS.md — Figma-Context-MCP

TypeScript MCP server (@tmegit/figma-to-code-mcp). get_figma_design turns Figma REST data into a compact v3 design tree. get_image_fills and render_node_images are image helpers. README.md is loaded as an instruction file too, so keep it accurate.

Commands

• Use pnpm 10.10.0. Node: .nvmrc says 20 and CI uses 20.17.0; the release job uses 24.
• Quality gate, in CI order (.github/workflows/ci.yml):

pnpm prettier --check "src/**/*.ts"   # CI checks formatting first; fix with `pnpm format`
pnpm lint                             # eslint . ; 0 errors, existing warnings (don't add `any`)
pnpm type-check                       # tsc --noEmit
pnpm test                             # vitest run, ~30 s, offline

• Single file or test: pnpm vitest run src/tests/tokenizer.test.ts or pnpm vitest run -t "name".
• pnpm build (tsup + d.ts into dist/) is required before pnpm start. The OpenCode figma-to-code MCP runs node dist/bin.js --stdio (see opencode.json), so it serves the last build. After a change, rebuild and restart that MCP server.
• pnpm dev rebuilds on change and runs node dist/bin.js after each build (HTTP mode). pnpm dev:cli only rebuilds; it starts no server.
• pnpm start serves HTTP on 127.0.0.1:3333. pnpm start:cli serves stdio.

Testing

• Tests live only in src/tests/. Vitest has globals on, maps ~ to src/, and uses a 30 s timeout (vitest.config.ts).
• tsconfig.json excludes src/tests/**, so pnpm type-check and pnpm build do not check test files.
• Live suites are skipped unless gated by an env var. They load .env through dotenv themselves.
  • RUN_FIGMA_INTEGRATION=1: integration, batchFetchIntegration, liveOptimization, renderNodeImages. Needs FIGMA_API_KEY and FIGMA_FILE_KEY; some also need FIGMA_NODE_ID. liveOptimization rewrites fixtures in src/tests/resources/.
  • RUN_FIGMA_RATE_LIMIT_PROBE=1: liveRateLimit sends up to 400 real requests and spends Figma quota.
  • RUN_BENCHMARK_TESTS=1: outputValidation, which needs the local src/tests/resources/testfigmaresult.json.
• src/tests/resources/ and cache/ are gitignored. Only src/tests/resources/.gitkeep is tracked, so fixtures are local.
• documentation.test.ts fails if the README "## Available Tools" table differs from the tools createServer registers, or if the get_figma_design description loses terms such as textRuns, svgViewport or borderWidths. Change the README and the tool description together.
• The stdio and tool-discovery tests spawn tsx src/bin.ts, so they need no build.