@uidbai/mcp-server

Model Context Protocol (MCP) server for the UIDB Design System. Enables AI coding assistants (Cursor, Claude Code, etc.) to build consistent, accessible UI components.

Architecture

The UIDB MCP server operates on a local .uidb/ folder in your project. This folder contains your design system configuration, component definitions, and patterns. No external API calls are required for basic operations.

Installation

No installation required! Use directly with npx:

npx -y @uidbai/mcp-server

Quick Start for Cursor

1. Create MCP Configuration

Add UIDB to your MCP config. You have two options:

Option A: Project-level (.cursor/mcp.json in your project root):

{
  "mcpServers": {
    "uidb": {
      "command": "npx",
      "args": ["-y", "@uidbai/mcp-server"]
    }
  }
}

Option B: Global (~/.cursor/mcp.json - applies to all projects):

{
  "mcpServers": {
    "uidb": {
      "command": "npx",
      "args": ["-y", "@uidbai/mcp-server"]
    }
  }
}

Tip: If project-level config doesn't load, try the global config instead. Global config takes precedence.

2. Restart Cursor

Fully quit Cursor (not just close the window) and reopen to load the UIDB MCP server.

3. Initialize Your Design System

Option A: Connect to UIDB Portal (recommended)

If you have a project in the UIDB portal, initialize with your credentials:

uidb_init({
  project_name: "My App",
  api_key: "YOUR_API_KEY",
  project_slug: "your-project-slug"
})

This:

• Fetches your design config from the portal
• Saves credentials locally (.uidb/.credentials.json, gitignored)
• Enables uidb_sync to pull future updates

Option B: Standalone mode

Without portal connection:

uidb_init({
  project_name: "My App",
  template: "standard",
  accent_color: "blue",
  gray_color: "slate",
  radius: "medium"
})

This creates a .uidb/ folder with your design system configuration.

4. Connect Theme to Your App

In your root layout, import the config:

import config from '../.uidb/config.json';
import { Theme } from '@radix-ui/themes';

export default function Layout({ children }) {
  return (
    <Theme
      accentColor={config.theme.accentColor}
      grayColor={config.theme.grayColor}
      radius={config.theme.radius}
    >
      {children}
    </Theme>
  );
}

5. Verify Connection

Ask Cursor: "Use uidb_status to check the design system"

You should see: "initialized: true" with your project info.

Quick Start for Claude Code

1. Add MCP Server

Add to your .mcp.json or Claude settings:

{
  "mcpServers": {
    "uidb": {
      "command": "npx",
      "args": ["-y", "@uidbai/mcp-server"]
    }
  }
}

2. Initialize and verify as above.

Available MCP Tools

Component Guidance

| Tool | Description | | ------------ | ------------------------------------------------- | | uidb_guide | Get component recommendations for what you need |

Initialization & Status

| Tool | Description | | ------------- | ------------------------------------------ | | uidb_init | Initialize .uidb folder (with portal sync) | | uidb_sync | Sync config from UIDB portal | | uidb_status | Check design system status |

Pattern Management

| Tool | Description | | --------------------- | --------------------------------------------------- | | uidb_detect_pattern | Check if a multi-component UI is a reusable pattern | | uidb_submit_pattern | Submit a new pattern to the design system | | uidb_list_patterns | List all documented patterns |

Configuration

| Tool | Description | | ---------------------- | -------------------------------- | | uidb_list_components | List available components | | uidb_get_config | Get project theme configuration | | uidb_update_config | Update theme settings |

Typical Workflow

1. Get Component Guidance

User: "Add a delete button"
Agent: uidb_guide({ description: "delete button for removing items" })
// Returns: recommended components, props, variants, and code examples

2. Implement the Code

Use the exact variant, size, and color from the guidance response.

3. Pattern Detection (MANDATORY for 3+ components)

Agent: uidb_detect_pattern({
  description: "User profile card with avatar and details",
  components_used: ["Avatar", "Text", "Flex", "Button"],
  context: "sidebar"
})

4. Submit Pattern (if detected)

Agent: uidb_submit_pattern({
  name: "User Profile Card",
  description: "Displays user info with action button",
  components: ["Avatar", "Text", "Flex", "Button"],
  code_template: "<Flex>...</Flex>",
  category: "identity"
})

Local Design System Structure

.uidb/
├── manifest.json       # Project metadata
├── config.json         # Theme configuration
├── components/
│   ├── _index.json     # Component registry
│   └── [component].json
├── patterns/
│   ├── _index.json     # Pattern registry
│   └── [pattern].json
└── rules/
    ├── a11y.json       # Accessibility rules
    └── constraints.json # Design constraints

Templates

When running uidb_init, you can choose a template:

• minimal - Basic config and a few core components
• standard - Full component set with patterns (default)

Troubleshooting

"No .uidb folder found"

Run uidb_init to create the design system folder.

"MCP tools not available"

1. Check your MCP config file exists and has valid JSON
2. Fully quit your AI tool (not just close window) and reopen
3. If project-level config doesn't work, try global config:
   • Cursor: ~/.cursor/mcp.json
   • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Verify MCP is working

Ask your AI assistant: "Use uidb_status to check the design system"

You should see a JSON response with project info (or an error if .uidb/ doesn't exist yet - that's expected, just run uidb_init).

Support

• Portal: portal.uidb.ai
• Documentation: See /docs in the UIDB repository

License

MIT