The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Basecoat UI MCP listing page.
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.
basecoat-css.DESIGN.md.Requires Node.js 22.14.0 or newer.
Configure an MCP client:
Or invoke the compiled entry directly:
Published tarballs include a prebuilt dist/ (prepublishOnly runs npm run build). Git checkouts omit dist/; build locally before running from a clone.
--project-root overrides BASECOAT_PROJECT_ROOT, 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.
search_components returns up to 8 compact {id, name, intent} summaries and never returns markup. Either intent or query may be omitted; both empty returns an empty list.get_component_details 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. theme-toggle resolves to theme-switcher.validate_composition statically checks up to 65,536 UTF-8 bytes of HTML or Astro source and returns at most 24 issues. Pass code or the alias html (not both with different values). When errors are dropped at the cap, the result includes errorsOmitted: true and an issues-truncated issue. valid is true when only warnings remain.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:
The host application supplies its compiled Tailwind and Basecoat stylesheet:
Basecoat 1.x uses btn with data-variant and data-size. Interactive components list the granular JavaScript modules the host must load.
The checked-in Basecoat 1.0.2 registry contains 39 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.
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 upstream snapshot with npm run sync; this is the only command that uses HTTPS. It validates schema, exports, notices, response budgets, version direction, and atomic replacement before changing the registry.
Development was AI-assisted. Behavior and documentation are verified against checked-in source, contract tests, and the pinned registry rather than generated claims.
See ARCHITECTURE.md for runtime boundaries, packaging, byte caps, and sync policy.
Created and maintained by Žygimantas Jasiulionis / Intellmedia under the MIT 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. Basecoat adapts design patterns from shadcn/ui; the notice preserves that attribution. No Basecoat CSS or shadcn source is vendored here.