Enables composing Basecoat UI components in Astro projects, with setup guidance for Vite, Tailwind CSS 4, selective JavaScript imports, and native dialog wiring.
Provides Tailwind CSS 4 integration for Basecoat UI components, including CSS ordering and stylesheet setup for Astro or static HTML projects.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@basecoat-ui Search for a card component template"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Agents and editors that need bounded Basecoat templates and dependency guidance.
Astro or static HTML projects built with Tailwind CSS 4 and basecoat-css.
Teams that keep project-specific design tokens and density guidance in DESIGN.md.
Related MCP server: UI Preset MCP Server
Requires Node.js 22.14.0 or newer.
npm ci
npm run build
npm start -- --project-root path/to/your/applicationThe npm package is intentionally source-only. A cloned checkout generates dist/server/stdio.js only when npm run build is run; packing the source does not build or publish generated output.
Configure an MCP client after building:
{
"mcpServers": {
"basecoat-ui": {
"command": "node",
"args": [
"path/to/basecoat-ui-mcp/dist/server/stdio.js",
"--project-root",
"path/to/your/application"
]
}
}
}--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.
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.
validate_composition statically checks up to 65,536 UTF-8 bytes of HTML or Astro source and returns at most 24 issues.
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:
Read the rhythm and project-context resources.
Decide content hierarchy and layout.
Search summaries, then request details only for selected components.
Read the Astro integration resource when connecting production assets.
Validate the final source.
The host application supplies its compiled Tailwind and Basecoat stylesheet:
<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.
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.
npm run typecheck
npm run test
npm run sync -- --checkDevelopment 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.
Get one minimal component template, dependencies, and composition tips for Astro or HTML. Response is bounded below 2000 UTF-8 bytes.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| environment | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds a concrete behavioral constraint by stating the response is bounded to 2000 UTF-8 bytes, and discloses that the result contains a minimal template, dependencies, and composition tips. This adds value beyond the annotations, though the size-bound phrasing is slightly ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, front-loaded sentences with no filler. The core retrieval statement comes first, and the response-size note is a useful addition. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with two required parameters and no output schema, the description covers the main invocation facts: input language, single-component resource, and response contents and size limit. It does not mention response format or how to discover valid IDs, but the sibling search_components tool likely fills that gap. Overall it is sufficiently complete for a correct call, with minor discoverability gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It maps the environment parameter to Astro or HTML and implies id selects a single component, but it never explicitly defines id as a component identifier or explains how valid ids are discovered. This is only partial compensation for the absent schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'Get', and names a concrete resource: one minimal component template with dependencies and composition tips, scoped to Astro or HTML. This clearly differentiates it from search_components (searching) and validate_composition (validating), and 'one minimal' signals single-item retrieval rather than a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus search_components or validate_composition. The description does not say to use search_components first to find an id, nor does it mention when validation would be more appropriate. Usage context is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find up to 8 compact component summaries by intent and query. No matches returns an empty list; no markup is returned.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| intent | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavior beyond these: a hard cap of 8 results, compact summaries, empty-list behavior on no matches, and the absence of markup in responses. This gives the agent concrete expectations without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence conveys the core behavior, result limit, and edge-case behavior. Every clause earns its place; there is no filler or repetition of annotation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does disclose the most important output traits: up to 8 summaries, empty list on no match, and no markup. However, it omits what a 'compact summary' contains, how results are ordered, and whether there are any constraints on intent or query semantics. The description is adequate for a simple search tool but not fully complete for an agent deciding how to call it correctly the first time.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the burden falls on the description. The text only repeats the parameter names ('by intent and query') without explaining the distinction between intent and query, expected value formats, or examples. An agent cannot confidently know what to supply for each parameter beyond the schema's string type and maxLength.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Find up to 8 compact component summaries by intent and query.' It clearly identifies the tool as a search/find operation and distinguishes it from the sibling get_component_details (which implies a singular fetch) and validate_composition (which implies validation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus get_component_details or validate_composition. The description implies a search scenario but never states exclusions, prerequisites, or alternative selection conditions. The agent is left to infer usage from the tool name and generic 'search' semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Statically check HTML/Astro source for Basecoat migration errors, missing scripts, nested cards, spacing and hierarchy issues. Include layout imports. Does not render or evaluate dynamic code.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral detail: 'Does not render or evaluate dynamic code' and 'Statically check' clarify that no execution occurs, which is crucial for an agent to avoid expecting runtime behavior. This goes beyond annotations and is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the purpose and includes the key behavioral caveat in the second sentence. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema). The description covers what the tool does, what it checks, and that it does not execute code. It does not mention the return format, but given the absence of an output schema and the straightforward nature of a validation tool, this is a minor gap. An agent can reasonably expect a list of issues.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must compensate for parameter documentation. It implies the 'code' parameter is the HTML/Astro source to check by mentioning 'HTML/Astro source', but it does not explicitly map the parameter to that role or explain constraints beyond the schema's maxLength. The mapping is inferable but not explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Statically check') and resource ('HTML/Astro source'), and enumerates the exact checks (migration errors, missing scripts, nested cards, spacing, hierarchy issues). It clearly differentiates from siblings search_components and get_component_details, which are about searching and retrieval, not validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context that the tool is for static validation of source code, which implies it should be used when checking for those specific issues. It does not explicitly state when not to use it or name alternatives, but the purpose is so distinct that an agent can infer the appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1get_component_detailssearch_componentsvalidate_compositionScored across 3 tools
Each tool has a clearly distinct purpose: searching, retrieving details, and validating composition. No two tools overlap in functionality, so agents can easily select the correct one.
All tool names follow a consistent verb + noun pattern (search_components, get_component_details, validate_composition). The verbs describe the exact action and the nouns indicate the target resource, making the pattern predictable.
Three tools is well-scoped for a read-only component reference server. Each tool addresses a core need—discovery, deep detail, and safety validation—without unnecessary bloat.
The server covers the full arc of a component reference workflow: search to find components, get details to use them, and validate to ensure correct integration. No obvious operations are missing for its stated purpose.
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
AI-native Git-based CMS for Astro. Create and publish content in the browser, without learning git.
Provides style context & tokens to design or restyle web UIs in any framework
