untitledui-mcp

UntitledUI Official MCP Integration

UntitledUI provides an official MCP server with 6 tools for AI-assisted component development. This skill provides background knowledge for Rune agents working with UntitledUI components.

Prerequisites

• MCP server configured in .mcp.json with server name untitledui
• For PRO components: UNTITLEDUI_ACCESS_TOKEN env var OR OAuth authentication
• For free components: no authentication required

Setup (Claude Code):

# Free + OAuth (recommended — auto-handles login flow):
claude mcp add --transport http untitledui https://www.untitledui.com/react/api/mcp

# PRO with API key (set UNTITLEDUI_ACCESS_TOKEN in your shell profile):
export UNTITLEDUI_ACCESS_TOKEN="<your-token-here>"
claude mcp add --transport http untitledui https://www.untitledui.com/react/api/mcp \
  --header "Authorization: Bearer $UNTITLEDUI_ACCESS_TOKEN"

Access detection: Agents have PRO access when UNTITLEDUI_ACCESS_TOKEN is set OR when the MCP server is OAuth-authenticated (both grant full access to all components and page templates). Without either, agents use free tier (base components only) or fall back to Tailwind + conventions. See agent-conventions.md for the full tier behavior matrix.

MCP Tools (6)

Search & Discovery

search_components

Natural language component search. Primary tool for finding components by functionality.

Parameter	Type	Required	Description
query	string	Yes	Natural language search (e.g., "sidebar navigation with icons")
category_filter	string	No	Filter: base, application, marketing, foundations, shared-assets, examples
limit	number	No	Max results (default: 20)
key	string	No	API key (alternative to OAuth)

When to use: First step when implementing any UI component. Search before building from scratch.

Search tips:

• Use descriptive queries: "file upload with drag and drop" > "upload"
• Include context: "pricing table with toggle" > "table"
• Specify domain: "settings page sidebar" > "sidebar"

list_components

Browse components by category. Use when exploring available components or building a full page.

Parameter	Type	Required	Description
category	string	No	base, application, marketing, foundations, shared-assets, examples
skip	number	No	Pagination offset
limit	number	No	Results per page
key	string	No	API key

Categories:

• base — Core UI: Button, Input, Select, Checkbox, Badge, Avatar, Toggle, etc.
• application — Complex: DatePicker, Modal, Table, Tabs, Pagination, etc.
• marketing — Landing pages, CTAs, testimonials, pricing, features, etc.
• foundations — Design tokens, icons, logos, FeaturedIcon
• shared-assets — Login, signup, 404, error pages (PRO)
• examples — Complete page examples (PRO)

Installation

get_component

Install a single component with its full source code.

Parameter	Type	Required	Description
name	string	Yes	Component name to install
key	string	No	API key for PRO components

Returns: Full component source code, imports, dependencies, and usage examples.

get_component_bundle

Install multiple components simultaneously. Use for page-level implementations.

Parameter	Type	Required	Description
names	string[]	Yes	Array of component names
key	string	No	API key for PRO components

Templates (PRO Only)

get_page_templates

Browse available page templates. Requires PRO subscription.

Parameter	Type	Required	Description
key	string	No	API key

Templates include: Dashboard layouts, settings pages, auth flows, landing pages, etc.

get_page_template_files

Install a complete page template with all component files. Requires PRO subscription.

Parameter	Type	Required	Description
template	string	Yes	Template identifier
key	string	No	API key

Free vs PRO Feature Matrix

Feature	Free	PRO
search_components	All categories	All categories
list_components	All categories	All categories
get_component (base)	Yes	Yes
get_component (application)	Partial	Yes
get_component (marketing)	No	Yes
get_component_bundle	Free components only	All components
get_page_templates	No	Yes
get_page_template_files	No	Yes
Shared assets (login, 404)	No	Yes

Rune behavior: Workers always attempt search/list (free). If get_component fails with auth error on a PRO component, worker falls back to building from scratch with Tailwind + conventions from this skill.

Core Conventions (Quick Reference)

These conventions are injected into worker prompts when UntitledUI is the active builder. For the complete reference, see agent-conventions.md.

Critical Rules

1. React Aria imports MUST use Aria* prefix:

   // CORRECT
   import { Button as AriaButton } from "react-aria-components";
   // WRONG
   import { Button } from "react-aria-components";
   

2. Files MUST be kebab-case:

   date-picker.tsx    // correct
   DatePicker.tsx     // wrong
   

3. Icons MUST include data-icon when passed as JSX:

   // As reference (preferred)
   <Button iconLeading={ChevronDown}>Options</Button>
   // As element (must have data-icon)
   <Button iconLeading={<ChevronDown data-icon className="size-4" />}>Options</Button>
   

4. Colors MUST be semantic — never raw Tailwind colors:

   text-primary       // correct
   text-gray-900      // WRONG
   bg-brand-solid     // correct
   bg-blue-700        // WRONG
   

5. Button icons use iconLeading/iconTrailing props — never pass icons as children.

Component Implementation Workflow

When a Rune worker needs to implement a UI component with UntitledUI:

1. SEARCH: search_components("descriptive query")
   ├── Match found → proceed to step 2
   └── No match → build from scratch with Tailwind + conventions

2. GET: get_component("ComponentName")
   ├── Success → use component source as implementation base
   └── Auth error (PRO) → fall back to conventions-guided Tailwind

3. CUSTOMIZE: Apply project-specific modifications
   ├── Follow import conventions (Aria* prefix)
   ├── Use semantic color classes (text-primary, bg-secondary)
   ├── Add proper icon handling (data-icon attribute)
   └── Ensure kebab-case file naming

4. VALIDATE: Check against conventions
   ├── No raw color classes (text-gray-*, bg-blue-*)
   ├── No react-aria imports without Aria* prefix
   ├── No PascalCase file names
   └── All icons use data-icon when passed as JSX

For full-page implementations, check get_page_templates first (PRO), then fall back to get_component_bundle for composing individual components.

Rune Integration Points

/rune:devise — Planning Phase

• Phase 0.5: discoverDesignSystem() detects untitled_ui → discoverUIBuilder() finds this skill
• Phase 1: Research agents receive UntitledUI tool availability context
• Phase 2: Plan frontmatter includes ui_builder.builder_mcp: untitledui
• Phase 2: Plan includes "Component Strategy" section with library component mapping

/rune:design-sync — Figma Pipeline

• Phase 1: figma_to_react() generates reference code (~50-60% match)
• Phase 1.5: Reference code analyzed → search_components() finds real UntitledUI matches
• Phase 2: Workers import REAL UntitledUI components instead of generated approximations
• Result: Match rate improves from ~50-60% to ~85-95%

/rune:strive — Worker Execution

• Phase 1.5: Worker prompts injected with:
  • Builder workflow block (search → get → customize → validate)
  • Conventions from agent-conventions.md (truncated to 2000 chars)
  • MCP tool context block (tool names + categories)

/rune:appraise — Code Review

• design-system-compliance-reviewer loads UntitledUI conventions as additional review rules
• Generates DSYS-BLD-* findings for convention violations (P2)

/rune:arc — Full Pipeline

• Inherits all above integrations across phases
• Phase 2.8 (Semantic Verification) confirms UntitledUI MCP availability

Talisman Configuration

# talisman.yml — UntitledUI official MCP integration
integrations:
  mcp_tools:
    untitledui:
      server_name: "untitledui"                  # Must match .mcp.json key

      tools:
        - name: "search_components"
          category: "search"
        - name: "list_components"
          category: "search"
        - name: "get_component"
          category: "details"
        - name: "get_component_bundle"
          category: "details"
        - name: "get_page_templates"
          category: "search"
        - name: "get_page_template_files"
          category: "details"

      phases:
        devise: true
        strive: true
        forge: true
        appraise: false
        audit: false
        arc: true

      skill_binding: "untitledui-mcp"            # This skill

      rules: []                                   # Conventions loaded via skill, not rule files

      trigger:
        extensions: [".tsx", ".ts", ".jsx"]
        paths: ["src/components/", "src/pages/"]
        keywords: ["frontend", "ui", "component", "design", "untitledui"]
        always: false                             # Set to true if ALL tasks should use UntitledUI

      metadata:
        library_name: "UntitledUI"
        homepage: "https://www.untitledui.com"
        mcp_endpoint: "https://www.untitledui.com/react/api/mcp"
        transport: "http"
        auth: "oauth2.1-pkce"                     # or "api-key" or "none"
        access_token_env: "UNTITLEDUI_ACCESS_TOKEN"  # env var for PRO API key (optional — free tier works without it)

Design System Discovery Integration

When design-system-discovery runs, UntitledUI is detected via:

Signal	Weight	Source
@untitled-ui/* in package.json	1.0 (conclusive)	Tier 0 — Root Manifests
untitledui MCP server in .mcp.json	0.9	Tier 0 — MCP Detection
@untitledui/icons imports in source	0.8	Tier 1 — Shallow Scan
sortCx utility usage	0.6	Tier 2 — Deep Content Scan

When both library AND MCP are detected, discoverUIBuilder() returns this skill's builder-protocol metadata automatically.

References

• agent-conventions.md — Complete UntitledUI code conventions (from official AGENT.md)
• mcp-tools.md — Detailed MCP tool documentation with search strategies