basecoat-ui-mcp

Basecoat UI MCP

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)

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

Claude Desktop (claude_desktop_config.json)

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

Claude Code (CLI)

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

Generic npx (no install)

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

npm

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:

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

The compiled entry can also be invoked directly:

{
  "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

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

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 <head> 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 <div class="overflow-x-auto"> wrapper, sticky blurred <thead class="sticky top-0 bg-background/90 backdrop-blur">, and right-aligned numeric cells.
   • FRM-01: Input controls require <div class="field"> wrappers with associated <label class="label" for="id">.
   • NAV-01: Headers must use compact h-12 or h-14 (forbidding oversized h-16).
   • TW4-01: Rejects deprecated Tailwind v3 utilities (bg-opacity-*, flex-shrink-*, @tailwind directives).
   • TOK-01: Rejects arbitrary bracket dimensions (w-[327px]) and hardcoded hex colors (#ff0000, bg-[#123456]).
   • FSM-01: Enforces finite state machine contracts on interactive primitives (dialog, dropdown-menu, accordion, tabs).
5. basecoat_creative_director - Surfaces Kanso minimalism and Basecoat design intelligence:
   • Density profiles: compact (p-4 gap-4, header h-12, table py-2), standard (p-6 gap-4/gap-6, header h-14, table py-3), and comfortable (p-6 md:p-8, header h-14).
   • Mathematical 4px/8px optical rhythm grid and typography ladders (tabular-nums on all metrics and numeric table cells).
   • Subtle 1px card ring elevation without conflicting border utilities.
   • WCAG 2.1 AA (contrast >= 4.5:1) and APCA ($L_c \ge 60$) token pairings.
6. basecoat_component_syntax - Delivers copy-pasteable HTML or Astro component markup from src/registry/components.json with pre-configured FSM state variants (default, active, loading, disabled, open, closed, open/closed), verified inline SVG action icons (plus, edit, trash, search, chevron-down, check, external-link), and composite component patterns:
   • metric-card (metrics-summary, kpi-card) - Stat card with tabular-nums numeral and trend badge.
   • data-table (datatable) - Sticky header table wrapped in overflow-x-auto with right-aligned numeric cells.
   • sidebar-shell (sidebar-dashboard-shell) - Desktop sticky navigation with responsive flyout below md.
7. basecoat_quality_inspector - Audits HTML/Astro compositions against dashboard audit rules: table-overflow-wrapper, kpi-metric-tabular-nums, table-numeric-alignment, a11y-focus-ring (flagging outline-none without focus visible ring), arbitrary color/dimension violations, and WCAG/APCA contrast pairings. Returns score (0-100), letter grade (A-F), structured issues, and actionable autoFixSuggestions.

Theme-Aware Charts and Data Visualization

8. basecoat_list_charts - Discovers and filters 56 theme-aware chart blueprints across 7 categories (area, bar, line, pie, radar, radial, tooltip) with keyword search / query, layout footprint (layoutFootprint), requiredTokens, and variant summaries.
9. basecoat_get_chart_blueprint - Retrieves chart container HTML (chart-container, role="img", accessible <table class="sr-only"> fallback, and glassmorphic tooltip markup with bg-background/95 backdrop-blur-sm), CSS tokens (var(--chart-1) through var(--chart-5), var(--color-border), var(--color-muted-foreground)), client options, layoutFootprint, and framework mount code for 5 frameworks (vanilla, astro, react, vue, svelte) with optional themeTokens overrides. Accepts chartId or alias id (defaults to area-default). Integrated directly into dashboard-01 and svg-area-chart (data-chart-id="area-interactive"). Generated deterministically via node scripts/ingest-shadcn-charts.mjs.

Component tools

• search_components returns up to 8 compact {id, name, intent} summaries across the 62 curated components 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.
• get_component_html returns the HTML markup template and dependencies for any curated component (environment defaults to html).
• validate_composition statically checks up to 256 KiB (262,144 UTF-8 bytes) of HTML or Astro source and returns at most 24 issues (including WCAG 2.1 / APCA token contrast, arbitrary dimensions, dialog focus traps, and aria-controls bindings). Pass code or html, and optional semanticProfile or densityProfile (comfortable|compact). It does not render, execute, resolve application modules, or certify runtime browser accessibility.
• validate_markup statically validates HTML/Astro source syntax, container tags, landmark ordering, and semantic constraints against Basecoat guidelines.

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 across 84 blocks and aliases.
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 (84 blocks and aliases including translated shadcn/ui v4 blocks):

• Canonical Shells & Sidebars: sidebar-01 through sidebar-16, sidebar-dashboard-shell, sidebar-inset-shell, sidebar-collapsible-icon, sidebar-mobile-flyout, sidebar-nav, topbar-shell, topbar-nav, app-shell, page-header.
• Dashboards & Workspaces: dashboard-01 through dashboard-07, dashboard-workspace, dashboard-main, dashboard-activity, analytics, analytics-workspace, ecommerce-overview, tasks, tasks-table-workspace, mail, mail-workspace.
• Metrics & Data Tables: metrics-summary, data-table-rich, data-table, data-table-detail-layout, data-workspace, data-bulk-actions, data-filters, data-pager, products, billing, settings.
• Forms & Authentication: login-01 through login-05, signup-01 through signup-05, otp-01 through otp-05, form-field-group, forms, form-section, authentication, auth-sign-in, auth-sign-up, auth-split-screen, auth-recovery, auth-reset.
• Charts & Feedback: svg-area-chart, empty-state, error-boundary, newsletter-waitlist, pricing-tiers, segmented-toggle, detail-drawer-panel, product-detail-layout, settings-workspace.

Multi-block recipes (11 page recipes):

• workspace-dashboard - full analytics dashboard (KPI cards, activity chart, records table).
• ecommerce-overview - e-commerce operational dashboard with order metrics and product highlights.
• analytics-workspace - analytics dashboard with time-series charts and cohort views.
• workspace-settings - application shell with navigation, header, and settings workspace tabs.
• workspace-detail / tasks-table-workspace - data table workspace with slide-over detail inspection drawer.
• mail-workspace - multi-pane email client layout with inbox list and detail view.
• 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.
• data-records - records page with filters, table, and pager.
• 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:

1. get_rhythm_rules - access approved spacing, typography, surfaces, borders, and layout patterns by profile and family filters.
2. 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 impleme