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.

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.

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.

Returns matching components with match type (name or category match).

get_category

Get all components in a specific category.

Component Library

Forms (20 components)

Layout (17 components)

Navigation (6 components)

Feedback (13 components)

Interactive (8 components)

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