# 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)