figma-custom-mcp

A small MCP + Figma plugin that patches three specific, confirmed capability gaps in Plumb — it does not modify, fork, or replace Plumb, and is designed to be paired in Figma alongside it.

The gaps, and the full source-level evidence for them, are documented in PLUMB_GAP_ANALYSIS.md (a from-source audit of Plumb v0.13.2). This project implements the P0 and P1 items from that audit:

P0 — foundation

• P0-1 — Absolute / overlapping positioning. Plumb's DSL compiler forces every container into auto-layout and never sets Figma's layoutPositioning="ABSOLUTE", so overlapping compositions (badge over image, text over photo, etc.) are structurally impossible to build. This project's compiler defaults to free (x/y) positioning and supports absolute: true children inside auto-layout regions.
• P0-2 — Local/custom image import. Plumb's image.src is always compiled into a web-search query against six fixed stock-photo providers; a user's own file can never enter a Plumb-built design. This project reads file:/data: URIs directly, with typed errors and zero placeholder substitution.
• P0-3 — Strict schema validation. Plumb's Zod schemas silently strip unknown/misspelled fields. Every schema here is .strict().

P1 — advanced construction primitives (all absent from Plumb entirely)

• Boolean operations (union/subtract/intersect/exclude) — real BOOLEAN_OPERATION nodes, either authored fresh in a figma_design tree or combined from existing nodes via figma_boolean.
• True grouping — real GROUP nodes via figma_group, with figma_ungroup reconstructing Figma's missing native ungroup.
• Components, component sets, and variants — real COMPONENT/COMPONENT_SET structures with genuine variantProperties, via a "component" node type + figma_create_component_set.
• Constraints — real node.constraints, both for newly-authored and existing nodes.
• Paint styles — real, idempotent-by-name PaintStyle creation and application.

See docs/P0-CAPABILITY-MATRIX.md and docs/P1-CAPABILITY-MATRIX.md for the full audit-item-by-item traceability, and docs/ for the rest of the documentation set.

Status

P0 COMPLETE, P1 COMPLETE — see P0-FINAL-REPORT.md and P1-FINAL-REPORT.md for the full acceptance-criteria checklists and real live-Figma test results. tests/p1-live-screenshot.png is a real, live, 59+-node composition this project built and screenshotted — overlapping images/shapes, real boolean-combined shapes, real component variants, real groups, constraints, and a shared paint style — not a flattened image, not a mock.

Quickstart

npm install
npm run build
npm test

Then see docs/QUICKSTART.md to pair the Figma plugin and run the live end-to-end test.

Documentation

• docs/ARCHITECTURE.md
• docs/P0-CAPABILITY-MATRIX.md / docs/P1-CAPABILITY-MATRIX.md
• docs/P0-TOOLS.md (all 13 tools, P0 + P1)
• docs/P0-DESIGN-SCHEMA.md (includes P1 additions)
• docs/P0-TEST-PLAN.md / docs/P1-TEST-REPORT.md
• docs/P0-IMPLEMENTATION.md / docs/P1-IMPLEMENTATION.md
• docs/P0-LIMITATIONS.md
• docs/QUICKSTART.md

License

MIT