Xenith UI MCP Server

🤖 AI-Powered Component Discovery: A Model Context Protocol (MCP) server that gives AI assistants like Claude complete access to the Xenith UI component registry and source code.

🚀 Quick Start

Using with npx (Recommended)

# Start the MCP server
npx @xenithlabs/xenith-ui-mcp

# Show configuration help
npx @xenithlabs/xenith-ui-mcp config

# Run tests
npx @xenithlabs/xenith-ui-mcp test

# Show all commands
npx @xenithlabs/xenith-ui-mcp help

For Claude Desktop

Add this configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "xenith-ui-registry": {
      "command": "npx",
      "args": ["@xenithlabs/xenith-ui-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

Replace your_github_token_here with your actual GitHub personal access token.

🛠 Available Tools

The MCP server provides these tools to AI assistants:

| Tool | Description | |------|-------------| | read_registry | Access the complete component registry (63+ components) | | get_component_info | Get detailed information about any component with styling examples | | read_file_from_github | Read source code files directly from GitHub | | list_component_files | List all files associated with a component | | search_components | Search components by name, description, or type | | get_component_dependencies | Analyze component dependencies (npm + registry) | | get_theme_info | NEW! Get Xenith UI theme information and semantic classes | | get_styling_guidance | NEW! Get guidance on using Xenith classes instead of generic Tailwind | | convert_to_xenith_classes | NEW! Convert generic Tailwind classes to Xenith semantic classes |

📋 Component Catalog

Access information about 63+ Xenith UI components including:

🎨 UI Components

• Form Elements: Button, Input, Select, Checkbox, Switch, Textarea
• Layout: Card, Sheet, Dialog, Drawer, Tabs, Accordion
• Navigation: Navbar, Sidebar, Breadcrumb, Pagination
• Data Display: Table, Avatar, Badge, Progress, Skeleton
• Feedback: Toast, Alert Dialog, Tooltip
• Pickers: Date Picker, Color Picker, File Uploader
• Charts & Maps: Recharts integration, Leaflet maps
• Specialized: OTP Input, Timeline, Steps, Code Display

🔧 Utilities

• Class merging utilities
• Styling helpers
• TypeScript interfaces

🎨 Xenith UI Styling System

Xenith UI uses semantic CSS classes instead of generic Tailwind classes for better theme support and design consistency:

✅ Use Xenith Classes

• bg-bg-default instead of bg-white or bg-gray-50
• text-text-default instead of text-gray-900
• border-border-default instead of border-gray-200
• bg-bg-weak instead of bg-gray-100

🌙 Automatic Theme Support

• Light/dark themes work automatically
• Set data-theme="light" or data-theme="dark" on root element
• All semantic classes adapt automatically

🔧 Theme Tools Available

• get_theme_info - Complete color and spacing reference
• get_styling_guidance - Context-aware styling help
• convert_to_xenith_classes - Convert generic classes to Xenith classes

🎯 Use Cases

For AI Assistants

• Component Discovery: "Show me all form-related components"
• Implementation Help: "How do I use the DatePicker component?"
• Dependency Analysis: "What dependencies does the Charts component need?"
• Code Reading: "Show me the Button component source code"
• Integration Guidance: "How do I add a new component to my project?"

For Developers

• Documentation: Complete component information at AI's fingertips
• Code Examples: Real implementation code from the repository
• Dependency Management: Automated dependency tracking
• Quick Setup: Instant component installation guidance

🔧 Configuration Options

Environment Variables

• GITHUB_TOKEN: GitHub personal access token for private repository access and rate limiting

MCP Client Examples

Claude Desktop

{
  "mcpServers": {
    "xenith-ui-registry": {
      "command": "npx",
      "args": ["@xenithlabs/xenith-ui-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Other MCP Clients

{
  "mcpServers": {
    "xenith-ui": {
      "command": "npx",
      "args": ["@xenithlabs/xenith-ui-mcp", "start"]
    }
  }
}

📡 Usage Examples

Component Search

AI: Search for all button-related components
→ Returns: Button, Copy Button, Toggle, Toggle Group, etc.

Dependency Analysis

AI: What dependencies does the date-picker component need?
→ Returns: NPM packages + registry dependencies + installation commands

Code Reading

AI: Show me the Button component implementation
→ Returns: Complete TypeScript source code with syntax highlighting

Installation Guidance

AI: How do I add the Charts component to my project?
→ Returns: Step-by-step installation with all dependencies

Theme and Styling Help

AI: How do I style a gray background for a card?
→ Returns: Use bg-bg-weak instead of bg-gray-100, with examples

AI: Convert "bg-gray-100 text-gray-900" to Xenith classes
→ Returns: bg-bg-weak text-text-default with explanations

AI: What colors are available in Xenith UI?
→ Returns: Complete semantic color reference with CSS variables

🏗 Development

Local Development

# Clone the repository
git clone https://github.com/xenithlabs/xenith-ui.git
cd xenith-ui/bin

# Install dependencies
npm install

# Run the server locally
npm start

# Run tests
npm test

Testing

# Basic tests (requires GITHUB_TOKEN env var)
npx @xenithlabs/xenith-ui-mcp test

# Test with configuration
npm run test:config

🔍 Registry Schema

The component registry follows the shadcn/ui registry schema with extensions for Xenith UI components:

{
  "name": "component-name",
  "type": "registry:ui|registry:lib|registry:style",
  "title": "Human Readable Title",
  "description": "Component description",
  "dependencies": ["npm-package"],
  "registryDependencies": ["other-components"],
  "files": [
    {
      "path": "lib/components/Example/index.tsx",
      "target": "components/ui/example.tsx",
      "type": "registry:ui"
    }
  ]
}

🤝 Contributing

We welcome contributions! The MCP server is part of the Xenith UI project:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes in the bin/ directory
4. Test your changes (npm test)
5. Commit your changes (git commit -am 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

MIT License - see the LICENSE file for details.

🔗 Links

• 🏠 Homepage: Xenith UI
• 📦 npm Package: @xenithlabs/xenith-ui-mcp
• 🐛 Issues: GitHub Issues
• 📖 MCP Documentation: Model Context Protocol
• 🤖 Claude Desktop: Anthropic Claude