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
git clone https://github.com/Sorbh/basecoat-ui-mcp.git
cd basecoat-ui-mcp
npm install
Option 2: Install via npm
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
{
"mcpServers": {
"basecoat-ui": {
"command": "node",
"args": ["/absolute/path/to/basecoat-ui-mcp/server.js"],
"env": {}
}
}
}
If installed globally via npm:
{
"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:
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-destructivecard-basic,card-with-iconinput-with-label,input-invalidalert-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:
<!-- 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:
- Get the
input-with-labelcomponent for email/password fields - Get the
button-primarycomponent for the submit button - Get the
checkbox-with-labelfor "Remember me" - 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:
get_usagewith "toast" to get documentationget_componentwith "toast" to get the HTMLget_setupto 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
npm start
Development mode (auto-restart on changes)
npm run dev
Run tests
npm test
Verbose test output
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 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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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:
npm test
License
MIT License - see LICENSE for details.
Author
Saurabh K. Sharma - GitHub