basecoat-ui-mcp

<p align="center">
  <img src="assets/logo.svg" alt="Basecoat UI MCP" width="64" height="64" />
</p>

<h1 align="center">Basecoat UI MCP</h1>

<p align="center">
  <strong>Offline Model Context Protocol server for Basecoat UI (shadcn/ui look without React).</strong><br>
  Curated templates, macro layouts, rhythm tokens, and static validation for Astro, Next.js, HTML, and Tailwind CSS 4.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@intellmedia/basecoat-ui-mcp"><img src="https://img.shields.io/npm/v/@intellmedia/basecoat-ui-mcp?style=flat&color=3b82f6&logo=npm&label=npm" alt="npm version" /></a>
  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=basecoat-ui-mcp"><img src="https://img.shields.io/badge/MCP_Registry-io.github.zygiu--zygis%2Fbasecoat--ui--mcp-6366f1?style=flat&logo=buffer&logoColor=white" alt="MCP Registry" /></a>
  <a href="https://www.npmjs.com/package/@intellmedia/basecoat-ui-mcp"><img src="https://img.shields.io/npm/dm/@intellmedia/basecoat-ui-mcp?style=flat&color=10b981" alt="npm downloads" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-amber?style=flat" alt="MIT License" /></a>
  <img src="https://img.shields.io/badge/node-%3E%3D22.14-emerald?style=flat&logo=node.js&logoColor=white" alt="Node.js version" />
  <img src="https://img.shields.io/badge/TypeScript-5.9-3178c6?style=flat&logo=typescript&logoColor=white" alt="TypeScript" />
  <img src="https://img.shields.io/badge/Network-0KB_Offline-09090b?style=flat&logo=shield&logoColor=emerald" alt="Offline Safe" />
</p>

The server exposes a deterministic, offline registry for AI coding agents instead of requiring clients to scrape documentation. It runs over local stdio with **zero runtime network requests**, bounded **&lt; 2 KB** responses, and static AST validation. The host application remains responsible for rendering, data access, authentication, sessions, credentials, OAuth, captcha, and other runtime behavior.

## Install

Requires Node.js **22.14.0** or newer.

### Quick Start by Client

#### Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "basecoat-ui": {
      "command": "npx",
      "args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "${workspaceFolder}"]
    }
  }
}
```

#### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "basecoat-ui": {
      "command": "npx",
      "args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "/absolute/path/to/your/application"]
    }
  }
}
```

#### Claude Code (CLI)

```sh
claude mcp add basecoat-ui -- npx -y @intellmedia/basecoat-ui-mcp --project-root $(pwd)
```

#### Generic npx (no install)

```json
{
  "mcpServers": {
    "basecoat-ui": {
      "command": "npx",
      "args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "/absolute/path/to/your/application"]
    }
  }
}
```

### npm

```sh
npm install --global @intellmedia/basecoat-ui-mcp
```

Add the server to an MCP client. Use an absolute path for the host application so design context and persistent sessions belong to the intended project:

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

The compiled entry can also be invoked directly:

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

Published packages include prebuilt `dist/` and the immutable semantic snapshot
under `src/semantics/`. Server startup reads that snapshot and does not write
inside the installed package. The package contract test builds first, creates
and extracts an actual npm tarball, marks the extracted package tree read-only,
starts its `dist/server/stdio.js` under a network tripwire, completes MCP
initialize and tool-list requests, and closes the connection. A source checkout
does not include `dist/`.

### From source

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

`--project-root` takes precedence over `BASECOAT_PROJECT_ROOT`, which takes precedence over the launch directory. The selected directory is the host project, not the MCP installation directory. The server exposes stdio only.

## Project-root configuration

The configured root controls two things:

- `DESIGN.md` is read from that directory by `basecoat://project/context`.
- Persistent macro sessions are stored under `<project-root>/.basecoat/designer/`.
- `.basecoat/rhythm.json` is an optional strict override. It must live under a
  real `.basecoat` directory inside the project root, be a regular non-symlink
  file no larger than 65,536 UTF-8 bytes, and resolve inside that root; missing
  or rejected files leave the packaged profile unchanged. Matching mapping IDs
  replace in place and keep packaged order.

Only that exact directory is used. The server does not walk parent directories. Keep `.basecoat/` in the host project and back it up if design sessions are part of your workflow. The MCP server never writes host application source files.

## Basecoat MCP tools

The server exposes three component tools, six macro tools, and two semantic tools. Every macro and semantic result is a bounded MCP packet of at most **1,999 UTF-8 bytes**. Larger result sets use cursors; responses are not sliced mid-JSON.

### Component tools

- `search_components` returns up to 8 compact `{id, name, intent}` summaries and never returns markup. `intent` and `query` are optional; an empty search returns an empty list.
- `get_component_details` returns one Astro or HTML template with dependencies and composition guidance. Oversized entries fail closed. `theme-toggle` resolves to `theme-switcher`.
- `validate_composition` statically checks up to **256 KiB** (262,144 UTF-8 bytes) of HTML or Astro source and returns at most 24 issues. Pass `code` or `html`, and optional `semanticProfile` or `densityProfile` (comfortable|compact). It does not render, execute, resolve application modules, or certify accessibility.

### Macro tools

The macro layer is this project's curated, project-specific composition system for shells, auth flows, data workspaces, slots, ports, rules, and recipes. It is compiled into a pinned registry snapshot. These layout contracts are not supplied automatically by shadcn or by MCP.

1. `search_macro_blocks` - find compatible blueprint blocks by query, role, family, or tag.
2. `get_macro_block` - read a block section such as `manifest`, `structure`, `slots`, `ports`, `rules`, `dependencies`, or `provenance`.
3. `begin_design` - create a persistent design session and pin its profile and registry revision. Pinned registries are hash-verified on load.
4. `get_design_context` - read session lists or focused views such as `overview`, `graph`, `rules`, `focus`, and `next`.
5. `apply_design_patch` - apply atomic graph changes with `expectedRevision` and an idempotent `operationId`. A committed mutation always returns a success acknowledgement; oversized optional payload may be omitted with `truncated: true`.
6. `validate_design` - validate a draft or complete design graph and page its diagnostics.

Design sessions persist under `<project-root>/.basecoat/designer/`. Registry revisions are content-addressed; a session keeps using its pinned revision even after the package snapshot changes. Design snapshots use the form `d:<designId>@<revision>`.

Curated block blueprints:
- **Shells & Navigation**: `app-shell`, `sidebar-dashboard-shell`, `sidebar-inset-shell`, `sidebar-collapsible-icon`, `sidebar-mobile-flyout`, `page-header`.
- **Authentication**: `auth-sign-in`, `auth-sign-up`, `auth-split-screen`.
- **Application & Workspace**: `dashboard-workspace`, `dashboard-main`, `dashboard-activity`, `settings-workspace`, `data-table-detail-layout`, `detail-drawer-panel`.
- **Forms & Data**: `form-section`, `data-filters`, `data-records`, `data-pagination`.
- **Marketing, Content & Utility**: `pricing-tiers`, `newsletter-waitlist`, `empty-state`, `error-boundary`, `svg-area-chart`, `segmented-toggle`.

Multi-block recipes:
- `workspace-dashboard` - full analytics dashboard (KPI cards, activity chart, records table).
- `workspace-settings` - application shell with navigation, header, and settings workspace tabs.
- `workspace-detail` - data table workspace with slide-over detail inspection drawer.
- `auth-flow` - bidirectional authentication flow between sign-in and sign-up cards.
- `auth-split-flow` - split-screen auth frame pairing sign-in and sign-up with hero media.
- `marketing-pricing` - 3-tier pricing table paired with newsletter/waitlist banner.

### Semantic tools

The semantic layer provides compiled rhythm profiles and finite state machine recipes:

7. `get_rhythm_rules` - access approved spacing, typography, surfaces, borders, and layout patterns by profile and family filters.
8. `get_fsm_recipe` - read interaction states, events, transitions, guards, and actions for `dialog`, `navigation` (`collapsible-navigation`), `auth-flow`, and `tabs`.

Semantic tools use the same bounded pagination as macro tools. Each rhythm record keeps the semantic token ID separate from its approved Tailwind utility. Put the utility in `class`; keep the semantic ID in design metadata and agent reasoning. Project overrides from `<project-root>/.basecoat/rhythm.json` are reflected in an effective content ref and revision. FSM recipes are structural metadata, not runtime implementations.

### End-to-end example

A dashboard page can follow this sequence:

```text
get_design_context(view="sessions")
begin_design(designId="admin", profile="app-default", operationId="begin-admin")
get_rhythm_rules(profile="default", family="density")
se