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-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:

<!-- 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

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.

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:

npm test

License

MIT License - see LICENSE for details.

Author

Saurabh K. Sharma - GitHub

Links

• Basecoat CSS Documentation
• MCP Protocol Specification
• Report Issues