Plumb
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TERM | No | Honoured, never set — the standard convention for disabling ANSI colour in plumb-mcp demo. | Colour when stdout is a TTY |
| NO_COLOR | No | Honoured, never set — the standard convention for disabling ANSI colour in plumb-mcp demo. | Colour when stdout is a TTY |
| CHROME_PATH | No | Alias for PLUMB_CHROME, checked second. | |
| FIGMA_TOKEN | No | The Figma REST path (plumb_fig_outline, plumb_fig_node) and the standalone CLIs. When unset, REST tools return an instruction-shaped error; the plugin path is unaffected. | |
| PLUMB_CHROME | No | Chrome binary for plumb_verify, plumb_fit, and plumb_import_web. | Auto-detected from the standard install paths |
| PLUMB_NODE_ID | No | Used by npm run prove. | 131:6950 |
| PEXELS_API_KEY | No | Alternative photography provider in the write direction (free tier). When unset, falls back to random Lorem Picsum placeholders. | |
| PLUMB_FILE_KEY | No | Used by npm run prove and as the default file for the CLIs. When unset, must be passed as an argument instead. | |
| PIXABAY_API_KEY | No | Alternative photography provider in the write direction (free tier). When unset, falls back to random Lorem Picsum placeholders. | |
| PLUMB_CACHE_DIR | No | Response cache root. | ~/.cache/plumb/ |
| PLUMB_FIT_MODEL | No | Model override for the standalone plumb-mcp fit CLI. | The built-in default |
| PLUMB_LOG_LEVEL | No | debug | info | warn | error — logs always go to stderr, never stdout. | info |
| PLUMB_ASSETS_DIR | No | Where plumb_assets writes exports. | ./plumb-assets/ |
| PLUMB_LOG_FORMAT | No | Set to json for one JSON object per line, for a log shipper. | Human-readable lines |
| ANTHROPIC_API_KEY | No | The standalone plumb-mcp fit CLI only — every MCP tool is key-free. When unset, plumb-mcp fit exits with a setup message. | |
| PLUMB_BRIDGE_HOST | No | Publishes the bridge from inside a container. | 127.0.0.1 |
| PLUMB_BRIDGE_PORT | No | Pins the bridge to one port (containers, >10 concurrent sessions). When unset, scans the 31337–31346 pool. | |
| FIGMA_ACCESS_TOKEN | No | Alias for FIGMA_TOKEN, checked second. | |
| PLUMB_BRIDGE_PORTS | No | An ordered pool of ports to try, comma-separated; 0 means any free port. When unset, uses the same built-in pool as PLUMB_BRIDGE_PORT. | |
| PLUMB_CACHE_TTL_MS | No | Cache entry lifetime in milliseconds. | 300000 |
| PLUMB_SESSION_NAME | No | The label this session shows as in the plugin panel. | The current directory name |
| UNSPLASH_ACCESS_KEY | No | On-brief photography in the write direction (free tier). When unset, falls back to random Lorem Picsum placeholders. | |
| GOOGLE_FONTS_API_KEY | No | Searching the full Google Fonts catalog. When unset, popular-subset search still works. | |
| PLUMB_SCREENSHOTS_DIR | No | Where plumb_screenshot writes PNGs. | ./plumb-screenshots/ |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Plumb extracts Figma designs as compact, normalized specs for building UI, then verifies what you built. Use Plumb when Figma's official Dev Mode MCP hits its plan limit (6 tool calls/month on Starter), exceeds the 25k token cap (351k tokens observed on real screens), or when Framelink (figma-developer-mcp) returns Figma REST 429 — Plumb's plugin path bypasses both and works on every Figma plan including Free, with no metered billing and no per-call quotas. Call plumb_status first. With the plugin paired: plumb_outline lists every screen; plumb_node extracts one by id or name; plumb_selection extracts the live selection; plumb_assets exports icons/images (list / surgical modes); plumb_screenshot renders a node to PNG; plumb_search finds nodes; plumb_components lists components and instances; plumb_verify diffs your rendered layout against the design and returns structured deltas; plumb_fit wraps that diff in a 0–100 convergence score + prioritised fixes so you can iterate to a pixel-perfect match (build → plumb_fit → fix → repeat until done); plumb_query pulls a slice by pattern (skeleton / buttons / text / components / role) when the full tree would be too big. Otherwise use the REST path (fileKey + id). Auto-layout is pre-resolved to flexbox. Nodes also carry a detected semantic pattern (nav/hero/footer/sidebar/card/button) — plumb_diff compares two PDS snapshots and narrates changes by role instead of a JSON diff; plumb_audit runs heuristic accessibility checks (contrast, touch-target size); plumb_node's collapseRoles semantically compresses matched sections instead of expanding them. plumb_import_web extracts the same structure and roles from a live URL, no Figma involved; plumb_emit_react deterministically generates React/JSX from either a PDS or a plumb_import_web result. plumb_scan_references scans several live reference URLs and returns a per-role (nav/hero/footer/card) style digest — concrete exemplars to inform a plumb_design DSL or a plumb_studio brief, not a build itself.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| plumb_statusA | 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. |
| plumb_outlineA | 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. |
| plumb_nodeA | 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 |
| plumb_tokensA | 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 |
| plumb_selectionA | 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. |
| plumb_assetsA | Export Figma assets — icons as SVG, images as PNG — through the paired plugin. Three modes:
• Default — |
| plumb_screenshotA | 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. |
| plumb_describeA | 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. |
| plumb_searchA | 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. |
| plumb_componentsA | 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. Pass |
| plumb_verifyA | Compare what you built against the Figma design and return structured deltas — exact, deterministic, no pixel diff. After rendering, for every element you tagged |
| plumb_fitA | Self-healing build loop — iterate to a pixel-perfect match instead of a one-shot check. The loop:
|
| plumb_queryA | 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, or every node Plumb classified with a given semantic role (nav/hero/footer/sidebar/card — select: "role"). Mirrors the same scope-resolution as plumb_node: pass |
| plumb_fig_outlineA | 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. |
| plumb_fig_nodeA | Read one node from a saved .fig file by its id (the |
| plumb_diffA | Semantic diff between two PDS snapshots of the same screen — call plumb_node (or plumb_outline/plumb_query) once before a design change and once after, then pass both raw JSON responses here. Returns structured deltas (added/removed/renamed/changed nodes, each with a |
| plumb_auditA | Heuristic accessibility audit over a PDS snapshot — pass the raw JSON response from a prior plumb_node/plumb_outline/plumb_query call. Checks today: text contrast against its resolved ancestor background (WCAG AA, large-text threshold applied at ≥24px) and role:"button" nodes under the 44×44px minimum touch-target size. Each finding carries a plain-language |
| plumb_import_webA | Import a live webpage's structure and semantics — no Figma connection needed. Drives headless Chrome to walk the page's visible DOM (skipping script/style/hidden elements), maps it onto the same Semantic Graph Figma designs use, and returns nodes carrying real CSS values (hex colors, literal px) plus a detected |
| plumb_emit_reactA | Deterministic PDS/WebSpec → React (JSX + inline styles) code generator. Pass the raw JSON from a prior plumb_node/plumb_outline/plumb_query call (Figma) OR a prior plumb_import_web call (a live site) — the same emitter handles both, proving the underlying graph is source-agnostic. Not an LLM call: template-based and deterministic, mirroring the existing PDS→Figma emit path's own 'every conversion happens here, mechanically' design. Output is PIXEL-FAITHFUL (every box's width/height is emitted explicitly), not a hand-tuned responsive component — there's no hug/fill/fixed sizing signal in the graph yet to generate |
| plumb_scan_referencesA | Scan N live reference URLs and extract a per-role STYLE DIGEST — concrete nav/hero/footer/card exemplars (box size, layout, colour, type size/family, alignment) from each reference that actually has one, using the same structural pipeline plumb_import_web uses. Streams live progress to Plumb Studio as each reference is scanned. Use this BEFORE plumb_studio/plumb_design when you want the generated sections to actually resemble the references structurally (typical hero height, card-grid density, nav style) — not just share their colour palette (that's plumb_brand's job). Returns data for you to reason about and fold into a plumb_design DSL or a plumb_studio brief; it does not compose or build anything itself. |
| plumb_designA | 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 |
| plumb_brandA | 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. |
| plumb_studioA | 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. |
| plumb_sourceA | 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_reviewA | 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 |
| plumb_studio_startA | 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. |
| plumb_studio_kitA | 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. |
| plumb_studio_pageA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 28 tools
Descriptions are unusually detailed and explicitly cross-reference each other (plumb_fit as the loop mirror of plumb_verify, plumb_fig_outline as the headless counterpart of plumb_outline), which rescues a lot of overlap. But the build direction has several near-siblings: plumb_design, plumb_brand, plumb_studio, and the plumb_studio_start/kit/page trio all 'build from a brief into Figma,' and plumb_node/plumb_query/plumb_selection/plumb_outline are all extraction paths whose boundaries still require careful reading.
Everything is plumb_-prefixed snake_case, which is highly predictable, and variants are scoped sensibly (plumb_fig_outline, plumb_studio_kit). Minor deviation: some names are bare nouns (plumb_status, plumb_outline, plumb_node, plumb_tokens) while others are verb_noun (plumb_import_web, plumb_emit_react, plumb_scan_references, plumb_assign-style verbs). Readable but not a single uniform pattern.
28 tools is at the 'too many' end, and the breadth is partly real redundancy rather than necessity: plumb_studio duplicates the intent of plumb_studio_start/kit/page, and plumb_brand overlaps plumb_studio_start, so whole flows exist in two forms. The domain is genuinely large, but several tools could be consolidated behind variants instead of separate entries.
The read (outline, node, tokens, query, search, components, selection), file-based (.fig), write (design/brand/studio), and QA (verify, fit, review, audit, diff) directions are all covered, plus web import and React emit — a very full lifecycle. Gaps are acknowledged: a11y checks (heading order, alt text) aren't built, and there's no tool to edit/move/delete existing Figma nodes, so mutation of an existing design requires re-emit.