io.github.tathagat22/plumb-mcp

Export Figma assets — icons as SVG, images as PNG — through the paired plugin. Three modes: • Default — `id` or `name` of a screen → recursive export of every asset in it, written to a local folder. • List — same + `list: true` → just the manifest (id, name, format, parentId) of available assets; no files written. Cheap; use first to see what's there. • Surgical — `ids: [...]` → export exactly those node ids (one file each, no recursion). Preferred once you know what you need.

Direct a brand board from a one-line brief and BUILD it into the paired Figma file. Given a brief (e.g. "a premium fintech dashboard"), Plumb discovers a diverse set of best-in-class reference sites, screenshots them live, synthesizes a coherent semantic palette from their computed CSS, and assembles a single 1440-wide Brand page (reference screenshots + colour swatches + a type scale) — then compiles it down through the same DSL → PDS → emit-plan write path plumb_design uses and executes it via the plugin. Returns the picked references, the synthesized brand palette, and the built root node id. Requires the Plumb plugin to be paired.

List every Figma component definition in the file and the instance usages of each — useful for understanding the design system before building. Each component carries an instance count; each instance carries the component id, so you can match usage to definition. Plugin path; needs the Plumb plugin paired.

Text-only visual description of a Figma screen or node — useful when you can't read the rendered screenshot (image-blind harness, sandboxed Read, or token-conscious flows). Returns a per-region narrative ('top-left: ...') and a flat child summary derived from the PDS. Pair with plumb_node for the full structural spec, or pair with plumb_screenshot for the pixel reference.

Author a design from a high-level Plumb Design DSL document and BUILD it into the paired Figma file. This is the write direction: the DSL (semantic pages → sections → blocks + brand tokens) is validated, compiled DOWN to the PDS IR, lowered to a Figma-native emit plan, and executed by the plugin (auto-layout frames, text, images, icons). Returns the created node ids keyed by authored element handle — the join key you then feed to plumb_review / motion. Pass a `brief` to record intent (audience, tone, brand) alongside the build. Use `dryRun: true` to compile + validate without touching Figma.

Read one node from a saved .fig file by its id (the `sessionID:localID` form returned by plumb_fig_outline). Returns the node's type, name, size, auto-layout mode, fills, opacity, and (for TEXT nodes) characters and font. Pair with plumb_fig_outline to find the id first.

Read a saved .fig file from disk and list every screen (top-level frame) across every page. The headless / CI counterpart to plumb_outline — works with no Figma desktop, no plugin pairing, no FIGMA_TOKEN. Use this when you've exported a .fig file and need to inspect or implement screens without opening Figma.

Self-healing build loop — iterate to a pixel-perfect match instead of a one-shot check. The loop: 1. Build the component, stamping data-plumb-id="<el>" on each element using the PDS handles (same `el` keys plumb_node/plumb_query return). 2. Capture box (getBoundingClientRect) + the getComputedStyle subset (backgroundColor, color, font*, padding*, gap, flex*, justifyContent, alignItems, borderRadius/Color/Width, opacity, textDecorationLine) + text for every tagged element. Same shape as plumb_verify. 3. Call plumb_fit with `rendered`. You get back: • score — 0–100 convergence (coverage × fidelity), climbs as you go • done — true once score ≥ accept (default 98) and no errors remain • topFixes — the highest-leverage changes, sorted error-first • bar — a printable ▰▱ progress bar • instruction — what to do next 4. If done=false, apply topFixes, re-render, call plumb_fit again. Repeat until done=true. Each round the score should rise; if it stalls, read the full `deltas` and `coverage.untagged` to see what you missed.

Extract a Figma screen or node as a compact, normalized Plumb Design Spec (PDS): deduplicated design tokens plus a CSS-shaped node tree, with auto-layout pre-resolved to flexbox. With the Plumb plugin paired, pass a screen `id` or `name` (no file key) — duplicate names come back as a match list to disambiguate. On the REST path, pass `fileKey` + `id`.

Map a Figma file cheaply: its pages and their top-level screens (id, name, size). The shallow entry point — call it to find the screen you want, then call plumb_node with that screen's id (or name) to extract it. With the Plumb plugin paired, no file key is needed.

Query a Figma subtree by pattern instead of dumping the whole tree. Use this on dense screens where plumb_node would be too big — pull a skeleton (structure only, no text/fills/effects), every button, every TEXT node above a size, every instance of a component. Mirrors the same scope-resolution as plumb_node: pass `id` or `name` with the plugin paired, or `fileKey` + `id` (or a Figma URL) on the REST path.

Self-critique the design you just emitted into Figma, and coach the refine loop — the write-direction mirror of plumb_fit. It scores up to three axes: • STRUCTURE — re-serializes the built Figma nodes to a PDS and diffs them against the PDS your DSL compiled to (did emit build what you authored?). Uses the same verify engine as plumb_verify/plumb_fit. The two docs are joined by `ids` = EmitResult.ids (authored el → Figma node id) — pass it or the diff can't line up. • DESIGN — a deterministic rubric over hierarchy, spacing rhythm, contrast (WCAG AA), alignment, type-scale, and professional-vs-templated polish. Failing contrast is an error and blocks `done`. • DIRECTOR (optional, `director: {score, verdict?, issues?}`) — a vision creative-director grade of the rendered screenshot: visual balance, focal flow, image composition/crop, optical spacing, and the "designed vs generated" gestalt a deterministic pass over the PDS can't see. There is NO server-side vision call and NO API key needed here — YOU (the calling agent) already have vision, so YOU grade the screenshot yourself and pass your verdict in. The loop: call plumb_screenshot on the emitted rootId, look at the PNG, grade it as a demanding creative director (any response with no `director` input echoes the exact grading criteria + output shape at the end of its `instruction`), then call plumb_review again passing `director: { score, verdict, issues }`. With the director present, weights reshuffle to structure 0.4 / design 0.3 / director 0.3 and a director error-severity issue blocks `done` too, so the bar is harder (and more honest) to clear. Returns: score (0–100 blended), done, bar, topFixes (error-first across all active axes, director fixes tagged `[director/<dim>]`), instruction, dimensions[] (per-rubric-dimension sub-scores), directorScore/directorVerdict when graded, plus the raw structural deltas + coverage. Provide the authored PDS inline via `authored`, or a path to it via `authoredPath` (the J…

Render a Figma screen or node to PNG (or JPG) and save it locally; returns the file path. Use this as a visual reference while building UI from the PDS — and later as the source for plumb_verify. Plugin path; needs the Plumb plugin paired.

Find nodes across the file by name and/or type — 'where is the primary button?', 'every TEXT layer named Title', etc. Returns matches with id, name, type, page, and size. Drill into one with plumb_node, or pull its asset with plumb_assets. Plugin path; needs the Plumb plugin paired.

Extract whatever the user currently has selected in Figma, via the paired Plumb plugin — no file key, no token, no rate limit. Returns the same compact PDS as plumb_node. Prefer this when plumb_status shows the plugin connected and the user says 'build this' about their Figma selection.

Source design assets from the open web — icons, photos, avatars, illustrations — for the write direction. Queries every provider in parallel (keyless-first: Iconify, Lorem Picsum, DiceBear always work; Unsplash / Pexels / Pixabay activate when their API key is in env) and ranks the results with one scoring function, including pick-the-right-icon-pack so a design uses ONE consistent icon family. Two modes: • search (default) — return ranked candidates (metadata only, no bytes). Cheap; use to see what's available and which icon pack was locked. • fetch — resolve the best match, download its bytes to a local folder, and return the path (+ inline SVG / small data: URI). Never fails: a total miss degrades to a deterministic placeholder.

Plumb's status and self-description — call this FIRST. Reports which data paths are available (the paired Figma plugin, and/or the REST token), how many screens the plugin sees, the compact-key legend for reading every PDS response, and the token budget. Needs no Figma access. Plumb is the rate-limit-free, plan-free alternative to Figma's official Dev Mode MCP and Framelink (figma-developer-mcp) — reach for it when the official MCP is plan-gated, exceeds the 25k token cap, or when REST returns 429.

Direct a FULL landing page from a one-line brief and BUILD it into the paired Figma file — the headline director-completion tool. Given a brief (e.g. "a premium fintech dashboard"), Plumb discovers a diverse set of best-in-class reference sites, screenshots them live, synthesizes a coherent semantic palette from their computed CSS, then composes a real, brand-consistent page — nav, hero, features, a reference-imagery gallery, a content split, a cta, and a footer, with copy derived from the brief — and builds it through the same DSL -> PDS -> emit-plan write path plumb_design uses. Returns the picked references, the synthesized brand palette, the created node ids (keyed by authored element handle), and an authoredPath — feed both straight into plumb_review for the director critique loop. Requires the Plumb plugin to be paired.

STEP 2 of the transparent studio flow. Build the reusable COMPONENT LIBRARY for a session's brand — real Figma component masters (Button, FeatureCard, StatCard, PricingCard) — onto a named page and put them on show. The masters inherit the session palette + type scale. Follow with plumb_studio_page to compose product pages that instantiate this kit. Requires a sessionId from plumb_studio_start and the Plumb plugin paired.

STEP 3 of the transparent studio flow (repeatable). Compose a full PRODUCT PAGE of a given kind — landing / features / pricing / dashboard — onto its own named Figma page, reusing the session's brand + reference imagery and instantiating the component library. Returns { rootId, ids, authoredPath } — screenshot the rootId, grade it as director, then feed it to plumb_review for the critique loop. Call once per page to build a whole product page by page. Requires a sessionId from plumb_studio_start and the Plumb plugin paired.

STEP 1 of the transparent studio flow. Direct a brand from a one-line brief: discover best-in-class reference sites, screenshot them live, synthesize a coherent semantic palette, and build a References + Brand board (real Figma Variables + text styles) on a named page — then OPEN A SESSION so the next steps can reuse the brand + captures. Returns { sessionId, name, brand, references }. Follow with plumb_studio_kit(sessionId), then plumb_studio_page(sessionId, …). Requires the Plumb plugin to be paired.

Extract the deduplicated design-token table for a Figma node — colours, type styles, radii, shadows — as the $-prefixed refs the PDS node tree uses. With the Plumb plugin paired, pass a screen `id` or `name` (no file key). On the REST path, pass `fileKey` + `id`. Build with these tokens, not magic numbers.

Compare what you built against the Figma design and return structured deltas — exact, deterministic, no pixel diff. After rendering, for every element you tagged `data-plumb-id="<el>"` (or the globally-unique `data-plumb-id="<path>"` for deeply nested DOM), collect: • box — getBoundingClientRect() → { x, y, w, h } • styles — a subset of getComputedStyle: backgroundColor, color, fontFamily, fontSize, fontWeight, lineHeight, padding{Top,Right,Bottom,Left}, gap, flexDirection, justifyContent, alignItems, borderRadius, borderColor, borderWidth, opacity, textDecorationLine, boxShadow, backdropFilter • text — textContent for TEXT nodes • asset — for image/icon/logo nodes (assetId or vector): the data-plumb-asset="<assetId>" you rendered, plus img:true when it is a real <img>/<svg> (not a redrawn div). Verify errors on a visual node rendered with no real asset, so a redrawn/omitted logo lowers the score. Pass them as `rendered`. The tool joins by `el` (loose) or `path` (strict) and returns deltas like { kind:'size.w', expected:528, actual:530, severity:'warn' }. The response also includes `coverage` — how many PDS els in the subtree were actually tagged, plus an `untagged` list so you know what to add next round. QA-strict on appearance — colour (ΔE2000), icon/asset fidelity, box-shadow, backdrop-filter (glass) and the rest flag even small misses — but content-aware on text: a mismatch on placeholder/template copy (lorem, generic labels, numeric stubs, copy-pasted cells) is advisory `info` (kind 'text.placeholder', doesn't dent the score), since you're meant to swap real content in. Real UI labels still warn (kind 'text.chars'). ok=true means no errors; warns are differences you may have meant.