MCP Tools Reference

The CalibrateDS MCP server exposes 23 tools across six categories. Your AI IDE calls these automatically during implementation — you can also invoke them by name in the chat.

Inspection

get_component

Returns the full design context for a component. This is what the AI reads before writing code.

get_component({ name: "Button" })
get_component({ name: "Button", detail: "full" })  // includes raw render tree

By default returns a compact summary. Pass detail: "full" when the AI needs the complete variant matrix, interaction contracts, and render tree.

list_components

Lists all components in the design system with their current implementation status (not implemented / stale / ready).

list_components()
list_components({ status: "stale" })  // only stale components

find_component_by_figma_node

Given a Figma node ID (from the Figma URL ?node-id=...), returns the matching component and its file path. Enables design-to-code navigation from Figma links.

find_component_by_figma_node({ nodeId: "123:456" })

get_variant_tokens

Returns a compact, pre-resolved per-variant token/style matrix for a component set. For every variant combination, it gives the resolved --ptb-* binding + value for background / text-color / border-color, plus border-radius, padding, gap, per-node text, and stroke weight + align — everything needed to implement all variants without reading the full context render tree or reconstructing it from variant diffs. A 42-variant set is roughly 6k tokens.

get_variant_tokens({ name: "ChipsWeb" })

list_themes

Lists all token collections and their modes (e.g., Light/Dark).

list_themes()

get_token

Resolves a token by name to its value, alias chain, and which components reference it. Also accepts a hex color to find matching tokens.

get_token({ query: "colors.brand.900" })
get_token({ query: "#103D1A" })          // reverse lookup by hex
get_token({ query: "--ptb-colors-brand-900" })

Pipeline Actions

run

Runs a PTB pipeline stage. Replaces running commands in a terminal.

run({ stage: "scan" })       // fetch fresh data from Figma
run({ stage: "generate" })   // scaffold component shells
run({ stage: "tokens" })     // regenerate CSS token files
run({ stage: "context" })    // export .ptb/context/ for AI IDEs
run({ stage: "prune" })      // remove files for deleted components

implement_component

Returns a structured implementation brief — component context, prompt, thumbnail path, and workflow steps — that the AI uses to write the full component: types, styles, and logic.

implement_component({ name: "Button" })

This is the highest-value tool in the server. A single call gives the AI everything it needs to produce production-ready code on the first attempt.

document_component

Generates MDX documentation and/or Storybook stories for a component.

document_component({ name: "Button" })
document_component({ name: "Button", format: "mdx" })

assign_component

Assigns a component to a team member.

assign_component({ name: "Button", to: "@alice" })
assign_component({ name: "Button" })  // self-assign

start_work

Marks a component as in-progress and returns the full implementation brief. Also reconciles the dependency readiness list against ptb.lock — a dependency is only marked "ready" when its stampedHash strictly equals its designHash. Blockers (unbuilt or stale deps) are returned in build order so the AI knows what to implement first.

start_work({ name: "Button" })

submit_work

Stamps a component as implemented. Before recording the stamp, the tool:

1. Reads the actual .ptb/verify/<slug>/report.json from disk — never trusts self-reported scores from the caller.
2. Hard-blocks if no report exists (never verified) or if the component is still an unimplemented scaffold (@ptb-scaffold marker detected).
3. Enforces a regression gate: the new score must meet or exceed the previously-stamped score on the same design. Pass skipVerifyRegression: true to override.

submit_work({ name: "Button" })
submit_work({ name: "Button", transitionTo: "stamped", artifacts: ["src/components/button/Button.tsx"] })
submit_work({ name: "Button", skipVerifyRegression: true })  // override regression gate

Run run_verify before submit_work — the stamp will be blocked if no verify report exists.

Governance

get_status

Compares stampedHash against designHash for all components. Shows what is ready, stale, or not yet implemented.

get_status()
get_status({ quick: true })   // fast check using ptb.lock only, no file reads

run_diff

Shows what changed in Figma, grouped into three lifecycle buckets so you (and the AI) know what to do with each change:

• new — a component that appeared for the first time.
• notImplemented — a component that's in the lock but has never been built. A design change here is folded into the pending build rather than scheduled as a fix.
• drifted — a stamped (implemented) component whose design has moved since you built it. This is what to re-implement.

Every changed component surfaces with full granular detail regardless of stamp state — variant axes, layout, size, typography (text-style swaps and font metrics), text content, render-tree structure, dependencies, and per-variant styling (naming the exact variant, node, and property that moved). Scan-timing-independent: stamped components diff against their stamp-time baseline, unstamped ones against the acknowledgement point (see diff_clear) or the most recent differing history snapshot, so a change stays visible across any number of scans until it's built or acknowledged.

run_diff()                      // full library
run_diff({ name: "Button" })    // scope to one component (name or slug)

Pass name to scope the diff to a single component — for the "diff this component, then implement it" flow. Omit for the full-library diff. Returns { totalChanges, summary, components: { new, notImplemented, drifted, removed }, tokens }.

Each changed component also carries its visual reference — a thumbnail (the variant grid) and variantThumbnails (per-variant PNGs keyed by selection) — so an agent can load the exact image for the variant a change names, without re-deriving the filename convention.

diff_clear

Acknowledges the current design state as the diff baseline. Future run_diff calls suppress everything up to this moment for unstamped and contractless components.

Reporting-only — this never touches ptb.lock. Stamps, contracts, and verify state are preserved, so staleness detection and the verify gate keep working.

diff_clear()

what_uses

Finds all components that depend on a given component. Essential before refactoring shared primitives.

what_uses({ name: "Button" })
what_uses({ name: "Icon" })

token_impact

Finds all components that reference a specific token. Run before changing a token value to understand blast radius.

token_impact({ tokenName: "colors.brand.900" })
token_impact({ tokenName: "--ptb-colors-brand-900" })

my_queue

Returns the components assigned to the current developer, sorted by status (stale first).

my_queue()

whats_new

Returns the per-version upgrade changelog — what to re-run after updating PTB.

whats_new()

Verification

run_verify

Pixel-diffs the current implementation against the Figma thumbnails captured at scan time. Returns a composite verdict from three signals — token content, DOM structure, and pixel similarity. The primary signal is token content (falling back to DOM structure when the design has no text); since v0.1.76, pixel evidence can rescue a low token score when the scanner has blind spots (attribute-borne text like placeholders and aria-labels, short badge text) — so a pixel-perfect render no longer fails on invisible-to-the-scanner text. Also runs a per-variant pixel diff loop when the component has multiple variants. Requires Storybook to be running locally.

run_verify({ name: "Button" })
run_verify({ name: "Button", story: "Primary" })

A score ≥ 0.90 is the passing threshold. pixelMatch.score is always the worst across all variant diffs — a single failing variant cannot hide behind a passing default. PNG artifacts (impl, diff, per-variant screenshots) are deleted after scoring — all scores and AI feedback are persisted in report.json. If verification fails, use get_verify_report to read the structured diff details and AI assessment, then adjust styles and re-run.

get_verify_report

Returns the last verification report for a component without re-running the pixel diff.

get_verify_report({ name: "Button" })

Setup & Info

get_checklist

Returns a live setup or upgrade checklist with status detection.

get_checklist({ kind: "setup" })    // first-time setup guide with live state
get_checklist({ kind: "upgrade" })  // what to re-run after updating PTB

The setup checklist is smart — it checks your actual workspace state and marks steps as done, pending, or blocked. Steps that can be auto-run include the MCP tool to call next.

If the running MCP server process is older than the CLI installed on disk (common after a global upgrade — a long-running server can't pick up new code without a restart), the response is prefixed with a warning telling you to restart your MCP connection.

setup_mcp

Configures PTB's MCP server in additional IDEs from inside the chat.

setup_mcp({ ide: "cursor" })
setup_mcp({ ide: "windsurf" })

Using Tools in Chat

Most AI IDEs let you invoke tools explicitly. Examples:

"Check which components are stale" → AI calls get_status()
"Implement the Card component" → AI calls implement_component({ name: "Card" })
"What changed in Figma since I last built these?" → AI calls run_diff()
"Scan Figma and regenerate tokens" → AI calls run({ stage: "scan" }) then run({ stage: "tokens" })

Next Steps

Back to MCP Overview →