Tool Catalog
The full MCP tool catalog, organized by category.
Every tool below is registered on the live server in create-server.ts, this page mirrors
handoff-app's own /developer/mcp tool-reference page, which is generated from the same
source (getMcpToolCatalog() in tool-catalog.ts) rather than hand-duplicated. The Scope
column is the OAuth scope a caller's token must carry for that tool to succeed, see
Authentication for the scope vocabulary. "None" means the tool has no
per-tool scope check; it's still gated by the base MCP auth (a valid bearer in registry mode,
open access in workspace mode, see Authentication).
Four tools aren't in the category map yet
handoff-app's CATEGORY_BY_TOOL map (the source for the categories below) hasn't been
updated for four tools that exist on the live server: handoff_delete_doc_page,
handoff_move_doc_page, handoff_list_review_queue, and handoff_review_page. They render
under an "Other" bucket on the live /developer/mcp page today. This page places them in the
category their name and behavior obviously belong to (Documentation and Pages & Compositions)
and flags them below.
Context
Tools that orient an agent to the active project before it does anything else.
| Tool | Purpose | Scope |
|---|---|---|
handoff_get_project_context | Project hydration: stack profile, paths, Figma key, translation hints. | None |
handoff_get_stack_guide | Markdown authoring rules for the active stack. | None |
handoff_get_design_guidelines | Team Design.MD guidelines from design workspace settings. | reference:read |
handoff_get_brand_voice | Formatted brand voice / copy guidelines from design workspace. | reference:read |
handoff_update_design_guidelines | Replace the team Design.MD guidelines wholesale (no merge — send the complete document). Returns the previous content so the overwritten version is recoverable. | sync:write + admin role |
handoff_update_brand_voice | Merge a subset of brand-voice fields over the stored value; omitted fields are left alone, "" clears one. Returns a per-field before/after. | sync:write + admin role |
Components
| Tool | Purpose | Scope |
|---|---|---|
handoff_search_components | Search component catalog by id, title, group, or tag substring. | None |
handoff_browse_components | Interactive inline card grid of the catalog the user can search and pick from — an MCP App, not plain JSON. Use handoff_search_components for raw data. | None |
handoff_get_component | Component implementation data by id — code/html/sass/css, properties, variants, usage guidance. Slimmed for context use: excludes the compiled sharedStyles CSS (~97% of the raw row), validationResults, and Figma sync metadata. | None |
handoff_get_component_reference | Component style reference image for a slot: buttons | inputs | iconography. | design:read |
handoff_get_reference | Fetch generated reference material by id: catalog | tokens | icons | property-patterns. | None |
Tokens
| Tool | Purpose | Scope |
|---|---|---|
handoff_get_tokens | Foundation design tokens (colors, typography, effects, and spacing/radius/grid when extracted), slimmed for context use. Multi-axis: advertises available axes; pass brand/scheme for axis-resolved tokens. | None |
handoff_browse_tokens | Interactive inline palette (color swatches, type specimens, spacing scale) the user can click to hand a token back — an MCP App. Use handoff_get_tokens for raw data. | None |
handoff_export_design_md | Export a compact DESIGN.md framing brief (system identity, token brief, component vocabulary, brand voice, design guidelines) to commit to a project. | None |
Icons & Logos
| Tool | Purpose | Scope |
|---|---|---|
handoff_get_icon_catalog | Return the full icon catalog, optionally filtered by category. | None |
handoff_search_icons | Search the icon catalog by name, tag, or description substring. | None |
handoff_get_logo_set | Return all logo variants (light/dark/color/mono, primary/alternate/wordmark/icon-only). | None |
Assets
Registry mode only, returns a workspace-mode notice otherwise.
| Tool | Purpose | Scope |
|---|---|---|
handoff_search_assets | Search the asset library (logos, icons, images) by text, type, collection, icon set, or tags. | None |
handoff_get_asset | Full details for a single asset, including component usages and size info. | None |
handoff_list_asset_collections | List all asset collections (Figma sections or manually created groups). | None |
Design Artifacts
Registry mode only for most of these.
| Tool | Purpose | Scope |
|---|---|---|
handoff_list_design_artifacts | List saved design library artifacts. | None |
handoff_get_design_artifact | Get design artifact by id. | None |
handoff_create_design_artifact | Create a design artifact with a base64 image. | Requires a real user JWT — rejects the legacy sync secret. |
handoff_get_component_spec | Get the structured spec + editable markdown for a saved design artifact. | None |
handoff_generate_component_from_design | Fetch (or queue generation of) a design artifact's spec and assets for local component generation. | None |
Design Workbench
The build loop around a design artifact: status transitions, spec/asset generation, and AI image
generation. Registry mode only, and the generating tools need server AI configured
(HANDOFF_AI_API_KEY, or a HANDOFF_CLOUD_URL proxy).
| Tool | Purpose | Scope |
|---|---|---|
handoff_set_design_status | Set an artifact's lifecycle status (draft → review → approved). Moving to review/approved kicks off server-side asset extraction + spec generation. | sync:write |
handoff_transition_to_dev | Transition an artifact to developer-ready: generates the full spec (props, behavior, accessibility, text inventory, token mapping, brand-voice check). Poll handoff_get_design_artifact and read devHandoff for stage progress. Asset extraction is off by default. | sync:write |
handoff_extract_design_assets | Deprecated alias that forwards to handoff_transition_to_dev with extraction off. | sync:write |
handoff_generate_design_image | Queue an async AI design-image generation; a background runner picks it up within ~1 min. Requires a real user JWT (rejects the sync secret alone). | sync:write |
handoff_get_design_job | Poll a generation job by id. Read-only, and a caller only sees its own jobs (admins/service actors excepted). | None |
Change Inquiry
Registry mode only.
| Tool | Purpose | Scope |
|---|---|---|
handoff_recent_changes | Recent changes across the design system (components, tokens, pages, patterns), newest first, with the "why" when available. | None |
handoff_component_history | Version history for one component: what changed, who, when, and why. | None |
handoff_change_why | The reason behind a specific change — the human-authored push message, or a cached AI-generated summary of the diff. | None |
Pages & Compositions
"Pages" here means playground pages (patterns), saved component-block compositions, distinct from markdown doc pages below. Registry mode only.
| Tool | Purpose | Scope |
|---|---|---|
handoff_list_pages | List playground pages, optionally filtered by group. | None |
handoff_get_page | Get one playground page's ordered block composition + metadata. | None |
handoff_scaffold_args | Get a ready-to-fill args template for a component, seeded from a real preview and annotated with each field's editorType and expected shape. Call it before authoring a block or preview. | None |
handoff_create_page | Compose and save a new playground page from validated component blocks. | sync:write |
handoff_update_page | Update a playground page's metadata and/or full block composition. | sync:write |
handoff_delete_page | Archive a playground page (not a hard delete): it leaves every listing, its briefs and their built pages are archived with it, and there is no un-archive. | sync:write |
handoff_list_review_queue (uncategorized in code, see callout above) | List playground pages awaiting review, typically built by a guest through a share link. submittedByName is self-declared and unverified. | sync:read |
handoff_review_page (uncategorized in code, see callout above) | Approve a submitted page, or reject it back to draft (which re-opens editing for the guest). Never changes visibility. Maintainer only. | sync:write |
Previews
Registry-authored, named value-sets for a component (e.g. a "Primary CTA" button), plus the interactive MCP App preview.
| Tool | Purpose | Scope |
|---|---|---|
handoff_create_preview | Author a new registry preview for a component; values are validated against the component's contract. | sync:write |
handoff_update_preview | Update an existing registry preview's title/values/semantic/rationale. | sync:write |
handoff_promote_preview | Mark a preview's value-set canonical (semantic="canonical") so it reads as the blessed reference example for its component. No rebuild, no contract change. | sync:write |
handoff_preview_component | Render an interactive, embedded preview of a real built component with responsive width controls (an MCP App, not plain JSON). | None |
Documentation
Markdown doc pages, registry mode only.
| Tool | Purpose | Scope |
|---|---|---|
handoff_list_doc_pages | List markdown documentation pages (slug, title, description). | None |
handoff_get_doc_page | Get one markdown doc page by slug — frontmatter + body. | None |
handoff_create_doc_page | Create a new markdown doc page (fails if the slug exists). Appears in the sidebar nav automatically. | sync:write |
handoff_update_doc_page | Update an existing markdown doc page by slug (fails if it doesn't exist). | sync:write |
handoff_delete_doc_page (uncategorized in code, see callout above) | Delete a markdown doc page by slug; removes it from the sidebar nav and records the deletion in the changelog. | sync:write |
handoff_move_doc_page (uncategorized in code, see callout above) | Move (rename) a doc page's slug while preserving content and history, so the nav tree updates atomically. | sync:write |
Build & Sync
| Tool | Purpose | Scope |
|---|---|---|
handoff_sync_status | Remote sync cursor and health. Workspace-mode notice if no registry is connected. | None |
handoff_sync_pull | Fetch sync changes since a cursor (JSON patches for local apply). Registry mode only. | None |
handoff_sync_push | Upload sync changes (components, patterns, pages). Registry mode only. | sync:write |
handoff_enqueue_build | Deprecated: server-side builds are retired. Build locally with handoff-app build:components (or build:app), then push. The tool's own message still says handoff-app build, which isn't a registered command. | None |
handoff_list_reference_materials | List reference material ids and sizes. | None |
The get + search pattern
Most listable data types expose both a get tool (single item, or the full set) and a
search tool (filtered by a query string). A few exceptions: assets have search + get
but no bulk "get all"; icons have both get_icon_catalog (bulk, filterable by category) and
search_icons (free-text); design artifacts and doc pages use list rather than search
since they're typically browsed, not queried by relevance.