Basecoat UI MCP server

Basecoat UI MCP server for Astro and HTML

A source-first, offline Model Context Protocol server for composing Basecoat UI interfaces in Astro, static HTML, and Tailwind CSS 4 projects.

It gives AI coding tools a small, deterministic Basecoat registry instead of making every client scrape documentation. The same local stdio configuration can be used by editors and agents, with each client starting its own server process; the server makes no runtime network requests. Composition follows a fixed order: content hierarchy, layout, component selection, spacing, typography, then final review.

Who should use it

• Agents and editors that need bounded Basecoat templates and dependency guidance.
• Astro or static HTML projects built with Tailwind CSS 4 and basecoat-css.
• Teams that keep project-specific design tokens and density guidance in DESIGN.md.

Install and run

Requires Node.js 22.14.0 or newer.

From npm

npm install -g @intellmedia/basecoat-ui-mcp

Configure an MCP client:

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "basecoat-ui-mcp",
      "args": [
        "--project-root",
        "path/to/your/application"
      ]
    }
  }
}

Or invoke the compiled entry directly:

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "node",
      "args": [
        "path/to/node_modules/@intellmedia/basecoat-ui-mcp/dist/server/stdio.js",
        "--project-root",
        "path/to/your/application"
      ]
    }
  }
}

Published tarballs include a prebuilt dist/ (prepublishOnly runs npm run build). Git checkouts omit dist/; build locally before running from a clone.

From source

git clone https://github.com/zygiu-zygis/basecoat-ui-mcp.git
cd basecoat-ui-mcp
npm ci
npm run build
npm start -- --project-root path/to/your/application

--project-root overrides BASECOATPROJECTROOT, which overrides the launch directory. It selects the host application's DESIGN.md; it is not the MCP installation directory. The server exposes stdio only.

Basecoat MCP tools

• search_components returns up to 8 compact {id, name, intent} summaries and never returns markup.
• getcomponentdetails returns one Astro or HTML template with dependencies and composition guidance. The complete JSON response must remain at or below 1,999 UTF-8 bytes; oversized entries fail closed.
• validatecomposition statically checks up to 65,536 UTF-8 bytes** of HTML or Astro source and returns at most 24 issues.

Basecoat design resources

• basecoat://design/rhythm provides content hierarchy, spacing, typography, component-family, and structural composition rules.
• basecoat://integration/astro provides Astro, Vite, Tailwind CSS 4, selective Basecoat JavaScript, and native dialog setup.
• basecoat://project/context reads the configured host project's DESIGN.md on demand. Output is capped at 6,000 UTF-8 bytes and truncates on a newline or sentence boundary when possible. Symlinks and non-regular files are refused.

Recommended flow:

1. Read the rhythm and project-context resources.
2. Decide content hierarchy and layout.
3. Search summaries, then request details only for selected components.
4. Read the Astro integration resource when connecting production assets.
5. Validate the final source.

Minimal HTML example

The host application supplies its compiled Tailwind and Basecoat stylesheet:

<link rel="stylesheet" href="/assets/basecoat.css">
<button type="button" class="btn" data-variant="default">Save changes</button>

Basecoat 1.x uses btn with data-variant and data-size. Interactive components list the granular JavaScript modules the host must load.

Registry and exclusions

The checked-in Basecoat 1.0.2 registry contains 39 curated templates:

Shortened. The full README is on GitHub.