Offline Model Context Protocol server for Basecoat UI (shadcn/ui look without bundling or requiring React).
Curated templates, macro layouts, rhythm tokens, and static validation for Astro, Next.js, HTML, and Tailwind CSS 4.
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 **< 2 KB** responses, and bounded lexical/heuristic static source 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 `/.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 **22 offline MCP tools** organized across six architectural layers: project setup and configuration, intent-driven layout orchestration, theme-aware charts, component retrieval, macro design graphs, and semantic state contracts. Every tool 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.
### Complete MCP Tool Table
| Tool Name | Layer | Description | Mode |
| --- | --- | --- | --- |
| `basecoat_setup_config` | Setup & Config | Generates framework boilerplates, Tailwind CSS 4 imports, OKLCH variables, and no-flash dark mode scripts | Read-only |
| `basecoat_page_architect` | Intent Fast Path | Plans complete layout scaffolds with container grid contracts and explicit slot topology | Read-only |
| `basecoat_compose_stack` | Intent Fast Path | Assembles composable component stacks into canonical shells (sidebar-01..16, topbar, inset, split) with slot hydration | Read-only |
| `basecoat_rules_enforcer` | Intent Fast Path | Enforces technical constraints across Tailwind v4, FSM state contracts, semantic tokens, and dashboard rules | Read-only |
| `basecoat_creative_director` | Intent Fast Path | Surfaces Kanso minimalism, 4px/8px optical rhythm, density profiles, typography ladders, and contrast pairings | Read-only |
| `basecoat_component_syntax` | Intent Fast Path | Delivers copy-pasteable HTML/Astro component markup with pre-configured FSM state variants and inline SVG icons | Read-only |
| `basecoat_list_charts` | Charts & Data Viz | Lists and filters 56 theme-aware chart blueprints across 7 categories with keyword search | Read-only |
| `basecoat_get_chart_blueprint` | Charts & Data Viz | Retrieves chart HTML using semantic CSS tokens (--chart-1..5) and mount scripts for 5 frameworks | Read-only |
| `basecoat_quality_inspector` | Quality & Audit | Audits HTML/Astro markup with Score (0-100), letter grade, syntax violations, a11y omissions, and auto-fix suggestions | Read-only |
| `search_components` | Components | Searches up to 8 compact component summaries by intent and/or query across 62 curated components | Read-only |
| `get_component_details` | Components | Retrieves minimal component template, dependencies, and composition guidance for Astro or HTML | Read-only |
| `get_component_html` | Components | Retrieves HTML markup template and dependencies for any curated component | Read-only |
| `validate_composition` | Static Analysis | Statically checks up to 256 KiB of markup for migration errors, rhythm, FSM bindings, and accessibility | Read-only |
| `validate_markup` | Static Analysis | Validates HTML/Astro markup syntax, structure, landmark ordering, and semantic constraints | Read-only |
| `search_macro_blocks` | Macro Graph | Searches approved macro layout blocks by query, role, family, or tag across 84 blocks and aliases | Read-only |
| `get_macro_block` | Macro Graph | Retrieves a section of a compiled macro block blueprint (manifest, structure, slots, ports, rules, etc.) | Read-only |
| `begin_design` | Macro Graph | Creates a persistent, hash-verified design session under .basecoat/designer/ pinning profile and registry revision | Mutation (idempotent) |
| `get_design_context` | Macro Graph | Reads focused design session views (sessions, overview, decisions, graph, rules, focus, next) | Read-only |
| `apply_design_patch` | Macro Graph | Applies atomic graph mutations with expectedRevision and idempotent operationId | Mutation (idempotent) |
| `validate_design` | Macro Graph | Validates draft or complete design graphs, returning diagnostic totals and paginated issues | Read-only |
| `get_rhythm_rules` | Semantics & Tokens | Reads effective semantic rhythm profiles and approved utilities by family, supporting project-local overrides | Read-only |
| `get_fsm_recipe` | Semantics & State | Reads finite state machine interaction states, events, transitions, guards, and actions | Read-only |
### Intent-Driven Design Layer (Fast Path)
1. `basecoat_setup_config` - Framework and styling configuration generator. Outputs ready-to-use boilerplate for 6 targets (`astro`, `vanilla`, `nextjs`, `sveltekit`, `vite`, `htmx`), 8 aesthetic style packs (`vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera`, `rhea`), complete OKLCH `@theme inline` blocks, and synchronous `` inline dark mode scripts.
2. `basecoat_page_architect` - Query recipes (`src/macros/authoring/recipes/*.json`) and macro blocks (`src/macros/authoring/blocks/*.json`) by `intent`, `recipe`, or `block`. Delivers full layout scaffolds with explicit `data-slot` markers, semantic HTML skeletons, grid structures, and responsive containers. Fully covers 5 dashboard page archetypes:
- **Executive Dashboard** (`workspace-dashboard`, `executive-dashboard`) - KPI stat cards, revenue chart, and recent activity.
- **E-commerce Overview** (`ecommerce-overview`) - Sales metrics, revenue analytics, top products card, and order summary.
- **Analytics Workspace** (`analytics-workspace`) - Filter toolbar, time-series interactive chart, and cohort analysis breakdown.
- **Data Table Detail** (`workspace-detail`, `data-table-detail`) - Paginated data table with search/filters and slide-over inspection drawer.
- **Settings Split-Screen** (`workspace-settings`, `settings-split-screen`) - Two-column responsive layout with vertical section navigation and form controls.
Supports density controls (`compact` for high-density enterprise tools, `comfortable` for standard interfaces).
3. `basecoat_compose_stack` - Dynamically composes 45 pre-built component stacks across 7 categories (`shell-stacks`, `header-stacks`, `kpi-stacks`, `chart-stacks`, `table-stacks`, `overlay-stacks`, `form-stacks`) into canonical shells (`sidebar-01`..`sidebar-16`, `topbar-shell`, `inset-shell`, `split-shell`) with automated slot hydration.
4. `basecoat_rules_enforcer` - Enforces strict technical constraints across `tailwind-v4`, `fsm-contracts`, `tokens`, `semantic-html`, and `dashboard-patterns`:
- `MET-01`: KPI numerals require `text-2xl`/`text-3xl` with `tabular-nums` and semantic trend indicators.
- `TBL-01`: Data tables require `
