Basecoat UI MCP

# Basecoat UI MCP A Model Context Protocol (MCP) server that provides Claude and other AI assistants with access to a comprehensive library of **Basecoat CSS UI components**. This server enables AI assistants to retrieve pre-built, accessible HTML components and usage documentation for building user interfaces. ## Features - **77 Pre-built Components** - Production-ready HTML components across 5 categories - **7 MCP Tools** - List, search, retrieve components and documentation - **Comprehensive Docs** - 25 detailed usage guides with examples - **Dark/Light Mode** - Built-in theme switching support - **Accessibility First** - All components include proper ARIA attributes ## Requirements - **Node.js** >= 18.0.0 - **npm** (included with Node.js) ## Installation ### Option 1: Clone from GitHub ```bash git clone https://github.com/Sorbh/basecoat-ui-mcp.git cd basecoat-ui-mcp npm install ``` ### Option 2: Install via npm ```bash npm install -g basecoat-ui-mcp ``` ## Configuration ### Claude Desktop Add the server to your Claude Desktop configuration file: **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "basecoat-ui": { "command": "node", "args": ["/absolute/path/to/basecoat-ui-mcp/server.js"], "env": {} } } } ``` If installed globally via npm: ```json { "mcpServers": { "basecoat-ui": { "command": "basecoat-ui-mcp", "env": {} } } } ``` After updating the config, restart Claude Desktop to load the MCP server. ### Other MCP Clients The server uses standard I/O (stdio) transport and is compatible with any MCP-compliant client. Start the server with: ```bash node server.js ``` ## Available Tools The MCP server provides 7 tools that AI assistants can use: ### `list_components` List all available Basecoat components organized by category. ``` No parameters required ``` Returns a complete inventory of all 77 components with names, categories, and filenames. --- ### `get_component` Retrieve the HTML code for a specific component. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | Component name (e.g., "button-primary", "card-basic") | **Example names:** - `button-primary`, `button-secondary`, `button-destructive` - `card-basic`, `card-with-icon` - `input-with-label`, `input-invalid` - `alert-success`, `alert-error` --- ### `get_usage` Get comprehensive usage documentation for a component type. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `component` | string | Yes | Component type (e.g., "button", "card", "input") | Returns detailed markdown documentation with examples, variants, and best practices. --- ### `get_setup` Retrieve Basecoat CSS setup code with CDN links. ``` No parameters required ``` Returns the HTML boilerplate to initialize Basecoat CSS in a new project: ```html <!-- Tailwind CSS --> <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script> <!-- Basecoat CSS --> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@0.3.1/dist/basecoat.cdn.min.css"> <script src="https://cdn.jsdelivr.net/npm/basecoat-css@0.3.1/dist/js/all.min.js" defer></script> ``` --- ### `get_theme_script` Get the theme switcher script for dark/light mode. ``` No parameters required ``` Returns a complete JavaScript implementation for theme switching with localStorage persistence. --- ### `search_components` Search for components by name or category. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | Search term (e.g., "button", "form", "navigation") | Returns matching components with match type (name or category match). --- ### `get_category` Get all components in a specific category. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `category` | string | Yes | One of: `forms`, `navigation`, `feedback`, `interactive`, `layout` | ## Component Library ### Forms (20 components) | Component | Description | |-----------|-------------| | `button-primary` | Primary action button | | `button-secondary` | Secondary action button | | `button-destructive` | Destructive/danger button | | `button-ghost` | Ghost/transparent button | | `button-outline` | Outlined button | | `button-link` | Link-styled button | | `button-large` | Large sized button | | `button-small` | Small sized button | | `button-icon` | Icon-only button | | `button-icon-large` | Large icon button | | `button-group` | Grouped buttons | | `input-basic` | Basic text input | | `input-with-label` | Input with label | | `input-invalid` | Input with error state | | `input-group` | Grouped inputs | | `checkbox-basic` | Basic checkbox | | `checkbox-with-label` | Checkbox with label | | `checkbox-with-description` | Checkbox with description | | `radio-group` | Radio button group | | `select-basic` | Select dropdown | | `textarea-basic` | Text area input | | `switch` | Toggle switch | | `slider` | Range slider | | `label` | Form label | ### Layout (17 components) | Component | Description | |-----------|-------------| | `card-basic` | Basic card container | | `card-with-icon` | Card with icon | | `card-standard` | Standard card layout | | `table` | Data table | | `avatar-small` | Small avatar | | `avatar-medium` | Medium avatar | | `avatar-large` | Large avatar | | `avatar-fallback` | Avatar with fallback | | `pagination` | Pagination controls | | `skeleton-basic` | Basic loading skeleton | | `skeleton-profile` | Profile loading skeleton | | `skeleton-card` | Card loading skeleton | | `spinner` | Loading spinner | | `empty-state` | Empty state display | | `kbd` | Keyboard key element | | `item` | List item | ### Navigation (6 components) | Component | Description | |-----------|-------------| | `accordion` | Expandable accordion | | `breadcrumb-basic` | Basic breadcrumb | | `breadcrumb-advanced` | Advanced breadcrumb | | `sidebar` | Sidebar navigation | | `tabs` | Tab navigation | | `command` | Command palette | ### Feedback (13 components) | Component | Description | |-----------|-------------| | `alert-standard` | Standard alert | | `alert-error` | Error/destructive alert | | `alert-success` | Success alert | | `badge-primary` | Primary badge | | `badge-secondary` | Secondary badge | | `badge-destructive` | Destructive badge | | `badge-outline` | Outlined badge | | `dialog-standard` | Standard dialog | | `dialog-modal` | Modal dialog | | `dialog-alert` | Alert dialog | | `toast` | Toast notification | | `progress` | Progress bar | ### Interactive (8 components) | Component | Description | |-----------|-------------| | `combobox` | Searchable select | | `dropdown` | Dropdown menu | | `popover` | Popover element | | `tooltip` | Standard tooltip | | `tooltip-bottom` | Bottom tooltip | | `tooltip-right` | Right tooltip | | `theme-switcher` | Dark/light mode toggle | ## Usage Examples ### Example 1: Building a Form Ask Claude: > "Create a login form using Basecoat components" Claude will use the MCP tools to: 1. Get the `input-with-label` component for email/password fields 2. Get the `button-primary` component for the submit button 3. Get the `checkbox-with-label` for "Remember me" 4. Combine them into a complete, accessible form ### Example 2: Adding Notifications Ask Claude: > "How do I add toast notifications to my app?" Claude will use: 1. `get_usage` with "toast" to get documentation 2. `get_component` with "toast" to get the HTML 3. `get_setup` to ensure you have the required scripts ### Example 3: Searching for Components Ask Claude: > "What button components are available?" Claude will use `search_components` with "button" to list all button variants. ## Running the Server ### Start the server ```bash npm start ``` ### Development mode (auto-restart on changes) ```bash npm run dev ``` ### Run tests ```bash npm test ``` ### Verbose test output ```bash npm run test:verbose ``` ## Project Structure ``` basecoat-ui-mcp/ ├── server.js # Main MCP server implementation ├── server.test.js # Test suite ├── package.json # Node.js configuration ├── style-guide.md # Comprehensive styling guide ├── claude_desktop_config.json # Example Claude config │ ├── components/ # 77 HTML component files │ ├── forms/ # Form components │ ├── layout/ # Layout components │ ├── navigation/ # Navigation components │ ├── feedback/ # Feedback components │ └── interactive/ # Interactive components │ ├── usage/ # 25 markdown documentation files │ ├── forms/ │ ├── layout/ │ ├── navigation/ │ ├── feedback/ │ └── interactive/ │ └── scripts/ # Setup and theme scripts ├── setup.html # CDN setup code └── theme-script.html # Theme switcher script ``` ## About Basecoat CSS [Basecoat CSS](https://basecoat.dev) is a modern component library built on Tailwind CSS v4. It provides: - Semantic HTML components with proper accessibility - CSS custom properties for theming - Dark mode support out of the box - Minimal JavaScript for interactive components - WAI-ARIA compliant components ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## Testing The project includes comprehensive tests covering: - Component retrieval and validation - Category filtering and organization - Search functionality - Documentation availability - Error handling and edge cases - Performance benchmarks Run the full test suite: ```bash npm test ``` ## License MIT License - see [LICENSE](LICENSE) for details. ## Author **Saurabh K. Sharma** - [GitHub](https://github.com/Sorbh) ## Links - [Basecoat CSS Documentation](https://basecoat.dev) - [MCP Protocol Specification](https://modelcontextprotocol.io) - [Report Issues](https://github.com/Sorbh/basecoat-ui-mcp/issues)