Keystone UI MCP Server

MCP (Model Context Protocol) server that exposes the Keystone UI design system data to AI tools like Claude Code, Cursor, and other MCP-compatible clients.

Installation

Via npx (recommended)

No installation needed — just add to your MCP client:

Claude Code:

claude mcp add keystone-ui -- npx -y keystone-ui-mcp@latest

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "keystone-ui": {
      "command": "npx",
      "args": ["-y", "keystone-ui-mcp@latest"]
    }
  }
}

Cursor / other MCP clients:

{
  "mcpServers": {
    "keystone-ui": {
      "command": "npx",
      "args": ["-y", "keystone-ui-mcp@latest"]
    }
  }
}

From source (for development)

cd mcp-server
npm install
npm run build    # Prebuild data + compile TypeScript
npm run dev      # Prebuild data + watch mode

Then point your MCP client to the local build:

{
  "mcpServers": {
    "keystone-ui": {
      "command": "node",
      "args": ["/absolute/path/to/h1-ui/mcp-server/build/index.js"]
    }
  }
}

The server uses stdio transport — no HTTP port needed.

Resources

| URI | Description | |-----|-------------| | keystoneui://tokens | All design tokens (colors, spacing, typography, radii) | | keystoneui://components | Full component catalog with props and usage examples | | keystoneui://components/{name}/source | Source code (TSX + CSS) for a specific component | | keystoneui://tokens/colors.css | Raw CSS custom properties file | | keystoneui://components/versions | Component version and status metadata | | keystoneui://components/{name}/changelog | Changelog and migration guides per component |

Tools

get_component

Get full details for a component: props, tokens, usage examples, version info, and optionally source code.

Parameters:

• name (required) — Component name (e.g. "Button", "Avatar", "Card")
• includeSource (optional, default false) — Include full TSX and CSS source

Example:

get_component({ name: "Button", includeSource: true })

get_tokens

Get design tokens filtered by category.

Parameters:

• category — One of: "colors", "spacing", "typography", "borderRadius", "all" (default: "all")

Example:

get_tokens({ category: "colors" })

search_components

Search components by keyword (name, description, prop name, or prop value). Optionally filter by status.

Parameters:

• query (required) — Search keyword
• status (optional) — Filter: "stable", "beta", "deprecated", "new", "all" (default: "all")

Example:

search_components({ query: "icon", status: "stable" })

generate_button

Generate JSX code for a Button with specific props and applied tokens.

Parameters:

• variant — "primary" | "secondary" | "ghost" | "accent" | "destructive"
• size — "small" | "medium" | "large" | "xlarge"
• label — Button text (default: "Button")
• iconOnly, leftIcon, rightIcon, disabled — Boolean flags

get_migration_guide

Get breaking change migration guides between two versions of a component.

Parameters:

• name (required) — Component name
• fromVersion (required) — Starting version (e.g. "1.0.0")
• toVersion (optional) — Target version (defaults to latest)

Prompts

use-component

Generates a prompt for using a specific Keystone UI component with import statements, usage examples, props reference, and design tokens.

use-component({ name: "Avatar" })

create-ui

Generates a prompt for building a UI from a description using only Keystone UI components and design tokens.

create-ui({ description: "A settings page with toggles and a save button" })

create-component

Generates a detailed 6-phase workflow prompt for converting a Figma component into production code:

1. Bulk Extraction — Parallel Figma MCP + keystone-ui MCP calls
2. Analysis & Token Mapping — Normalize spec, map colors/spacing/radii
3. Code Generation — TSX, CSS Module, index.ts following project conventions
4. System Registration — Update tokens, MCP server, and public exports
5. Preview Integration — Add to preview page
6. Visual Validation — Build, compare with Figma, verify TypeScript

create-component({ componentName: "Toggle" })

Available Components (36)

| Component | Description | |-----------|-------------| | AIResponseActions | Toolbar for AI response actions (Copy, Retry, Like, etc.) | | Alert | Glass-style alert card with gradient border | | Avatar | Circular avatar (image, initials, icon, placeholder) | | Badge | LabelBadge, NotificationBadge, MarketingBadge | | Banner | Marketing banners (Branded, Countdown, Gradient, Feature, Glass, Strip) | | BlockButton | Square icon button with active/inactive states | | BottomSheet | Modal bottom sheet with grabber, header, scrollable content | | Breadcrumb | Navigation breadcrumb trail with separator | | Button | Multi-variant button (primary/secondary/ghost/accent/destructive) | | Card | Composable card system (Card, CardImage, CardHeader, CardContent, CardActions) | | ChatBubble | Chat message bubble (outgoing, incoming, ai, system) | | Checkbox | Rectangle or rounded checkbox | | Chip | Filter, Choice, Input, Action, Suggestion chips | | ConversationList | Chat conversation list items | | DatePicker | Calendar date picker with time support | | Dialog | Centered modal dialog (alert, confirm, success, input) | | Dropdown | Dropdown menu with checkbox/radio selection | | FileUpload | UploadZone + FileUploadItem with progress | | FloatingActionButton | FAB with primary/surface/accent types | | Icons | 4600+ SVG icons across 29 categories | | List | Composable list (ListHeader, ListItem, ListSeparator) | | Loading | 3-dot pulse loader animation | | MediaPlayer | Mini media player bar | | MessageInput | Chat input + AI prompt input | | Progress | ProgressBar + Spinner | | Radio | Radio button with pill shape | | SearchBar | Search bar with cancel and clear states | | SegmentedControl | Pill segmented control + underline tabs | | Slider | iOS-style slider with optional tick marks | | Stepper | Quantity stepper (minus/plus buttons) | | TabBar | Bottom navigation tab bar | | TextField | Text input with label, helper text, clear, password toggle | | Toggle | iOS-style toggle switch | | TokenUsage | Token usage indicator with colored progress bar | | Tooltip | Dark tooltip with arrow | | Typography | 24 typography variants mapping to SN Pro type system |

Project Structure

mcp-server/
  src/
    index.ts                # Entry point (stdio transport)
    server.ts               # MCP server registrations (resources, tools, prompts)
    data/
      tokens.ts             # Design tokens (colors, spacing, typography, radii)
      components.ts         # Component metadata (props, usage, Figma node IDs)
      generated/            # Auto-generated at build time (gitignored)
        versions.ts         # From src/data/component-versions.json
        colors-css.ts       # From src/tokens/colors.css
        sources.ts          # Component .tsx + .module.css source code
  scripts/
    bundle-data.ts          # Prebuild: embeds project data into TypeScript modules

All design system data is bundled at build time so the server runs standalone via npx without needing the source repo.

Keeping in Sync

When adding or modifying components, update:

1. src/data/tokens.ts — Add/update token entries
2. src/data/components.ts — Add/update component metadata (description, paths, figmaNodeId, props, usage)
3. src/server.ts z.enum() — Add new component names to get_component and get_migration_guide tools
4. src/data/component-versions.json (project root) — Add version entry

Then rebuild: npm run build

Publishing

cd mcp-server
npm run build
npm publish

The files field in package.json ensures only the build/ directory is published. The prebuild step embeds all necessary data so consumers don't need the source repo.

Tech Stack

• TypeScript + Node.js (ES2022)
• @modelcontextprotocol/sdk v1.29+
• zod v4 for schema validation
• stdio transport (no HTTP server)