basecoat-ui-mcp

# Basecoat UI MCP Offline, source-first [Model Context Protocol](https://modelcontextprotocol.io/) server for composing [Basecoat UI](https://basecoatui.com) in Astro, static HTML, and Tailwind CSS 4 projects. The server exposes a small, deterministic registry instead of asking each client to scrape documentation. It runs over local stdio and makes no runtime network requests. 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. ### 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") search_macro_blocks(q="shell", limit=8) apply_design_patch( designId="admin", expectedRevision=0, operationId="add-dashboard", operations=[{ op: "instantiate_recipe", recipe: "workspace-dashboard", pagePrefix: "admin" }] ) get_design_context(view="overview", designId="admin") get_macro_block(idOrRef="app-shell", section="structure", designId="admin") get_fsm_recipe(recipe="dialog", section="transitions") ``` Implement the selected component leaves in the host project, then record completed regions with `apply_design_patch(record_written)`. Finish with `validate_design(mode="complete")` and `validate_composition` on the generated Astro or HTML source. After a conflict or restart, reread the session and use the returned revision and cursors. Copy `templates/cursor/basecoat-designer.mdc` into a host project's `.cursor/rules` for agent guidance. The MCP server does not write consumer application source files. ### Source adaptation and offline import The macro importer is intentionally local-first. It accepts a checked-out or otherwise locally saved shadcn-style `registry-item.json`, a reviewed mapping, and a local dependency lock: ```sh npm run import:blocks -- \ --item=/path/to/registry-item.json \ --mapping=/path/to/mapping.json \ --lock=/path/to/dependency-lock.json \ --dry-run ``` This command does not fetch live shadcn registry items, install packages, execute upstream code, or make runtime network requests. Unknown, unlocked, or explicitly unsupported dependencies produce diagnostics instead of guesses. Omitted OAuth, captcha, session, credential, and other application features are reported as obligations. The importer emits only the curated structural block; the host application must implement the runtime behavior. The mapping and resulting provenance make the boundary explicit: shadcn-style source is an input reference, while layout contracts, slots, ports, rules, and recipes are curated adaptations owned by this project's macro layer. They are not features provided by shadcn or by MCP. Upstream refreshes are separate maintainer authoring operations and never occur from the MCP server. ## 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: ```html <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 **41 curated templates**: `accordion`, `alert`, `alert-dialog`, `avatar`, `badge`, `breadcrumb`, `button`, `button-group`, `card`, `chart`, `checkbox`, `combobox`, `command`, `dialog`, `drawer`, `dropdown-menu`, `empty`, `field`, `input`, `input-group`, `item`, `kbd`, `label`, `native-select`, `popover`, `progress`, `radio-group`, `scroll-area`, `select`, `sidebar`, `skeleton`, `slider`, `switch`, `table`, `tabs`, `textarea`, `theme-switcher`, `toast`, `tooltip` The maintenance snapshot records 41 discovered upstream components. `pagination` and `spinner` remain excluded from search and details until manually curated. Slider uses `basecoat-css/range`, not a `slider` module. The runtime has no network client, remote documentation dependency, frontend framework runtime, remote media analysis, or bundled host assets. Generated templates may not use `basecoat-css/all`; each controller is imported explicitly. Search results do not contain markup, newly discovered components are never auto-promoted, and JSON or HTML is never sliced to fit a response budget. ## Astro and static HTML use cases In Astro, use the integration resource for Vite, Tailwind CSS 4, CSS ordering, selective controller imports, native `<dialog>` wiring, and ClientRouter hooks. In static HTML, copy the listed built controller files from `basecoat-css` into the host application's asset directory and preserve dependency order. Chart templates require host-supplied Chart.js. Maintainers can refresh the pinned Basecoat snapshot only with an explicit immutable commit source, for example `npm run sync -- --ref <40-character-commit-sha>`. This is the only command that uses HTTPS. It validates schema, exports, notices, response budgets, version direction, and atomic replacement before changing the registry. It does not refresh shadcn mappings or macro blocks. ## Development and verification Install dependencies with `npm ci`, then run the focused checks: ```sh npm run check npm pack --dry-run npm audit --omit=dev ``` `npm run check` type-checks, verifies both compiled snapshots, builds and runs the Node test suite, and checks the branch diff for whitespace errors. The test suite also exercises the packed read-only MCP bin offline. `npm pack --dry-run` checks the package file allowlist without retaining a tarball. `npm audit --omit=dev` checks production dependencies against the npm advisory database and therefore requires network access. Maintainers can verify the pinned Basecoat source with: ```sh npm run sync -- --ref <40-character-commit-sha> --check ``` The sync command is the only network boundary. Macro authoring changes require `npm run compile:blocks`; review the generated `src/macros/registry.snapshot.json` and then run `npm run compile:blocks:check`. ## Contributing 1. Create a focused branch from the default branch. 2. Keep component templates, macro contracts, and documentation aligned with checked-in source. 3. Run `npm run typecheck`, `npm run compile:semantics:check`, `npm run compile:blocks:check`, and `npm run test`. 4. Run `npm pack --dry-run` when package contents or metadata change. 5. Describe behavior changes, bounded-output effects, and any required host application work in the pull request. Do not add GitHub Actions workflows. Upstream registry refreshes and macro authoring are maintainer-reviewed changes, not server startup tasks. ## Troubleshooting - **The server starts but reads the wrong project:** set an absolute `--project-root` or `BASECOAT_PROJECT_ROOT`. The fallback is the process launch directory. - **`DESIGN.md` is not available:** place a regular file at the configured root. Parent directories and symlinks are not followed. - **A source checkout cannot start:** run `npm run build` before `npm start`. - **A macro result has a cursor:** request the next page with that cursor; do not concatenate or parse partial JSON. Changed registry, design, or effective rhythm revisions make prior cursors stale. - **An apply acknowledgement includes `truncated: true`:** the mutation committed; reread context or validation tools for the omitted detail. - **An importer diagnostic mentions OAuth, captcha, or an unsupported dependency:** implement or resolve it in the host application or reviewed mapping. The importer does not guess runtime behavior. - **A design patch conflicts:** reread `get_design_context`, use its current revision, and send a new unique `operationId`. See [ARCHITECTURE.md](ARCHITECTURE.md) for runtime boundaries, persistence, packet limits, and sync policy. Report reproducible defects in the [issue tracker](https://github.com/zygiu-zygis/basecoat-ui-mcp/issues). ## Author, license, and upstream attribution Created and maintained by [Žygimantas Jasiulionis](https://zygimantas.jasiulionis.eu/) / Intellmedia under the [MIT License](LICENSE). Basecoat UI is an independent MIT-licensed project by Ronan Berder. Adapted templates and metadata retain the complete Basecoat notice in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Basecoat adapts design patterns from [shadcn/ui](https://ui.shadcn.com); the notice preserves that attribution. No Basecoat CSS or shadcn source is vendored here.