This server lets you compose Basecoat UI interfaces in Astro and static HTML with deterministic, offline MCP tools and design resources.
Search Basecoat components by intent and/or query (up to 8 compact summaries, no markup).
Get one minimal Astro or HTML component template with dependencies and composition tips (response <2,000 UTF-8 bytes).
Validate HTML/Astro source for Basecoat migration errors, missing scripts, nested cards, spacing, and hierarchy issues (up to 65,536 bytes; max 24 issues).
Read Basecoat design rhythm rules, Astro integration guidance, and the host project's DESIGN.md on demand.
Run fully offline over stdio with no runtime network requests and bounded, deterministic responses.
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: Maket
Requires Node.js 22.14.0 or newer.
npm install -g @intellmedia/basecoat-ui-mcpConfigure an MCP client:
{
"mcpServers": {
"basecoat-ui": {
"command": "basecoat-ui-mcp",
"args": [
"--project-root",
"path/to/your/application"
]
}
}
}Or invoke the compiled entry directly:
{
"mcpServers": {
"basecoat-ui": {
"command": "node",
"args": [
"path/to/node_modules/@intellmedia/basecoat-ui-mcp/dist/server/stdio.js",
"--project-root",
"path/to/your/application"
]
}
}
}Published tarballs include a prebuilt dist/ (prepublishOnly runs npm run build). Git checkouts omit dist/; build locally before running from a clone.
git clone https://github.com/zygiu-zygis/basecoat-ui-mcp.git
cd basecoat-ui-mcp
npm ci
npm run build
npm start -- --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. 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:
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/or query (either field may be omitted). No matches returns an empty list; no markup is returned.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| intent | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, closed-world behavior. The description adds genuinely new behavioral facts beyond them: the hard cap of 8 results, empty-list-on-no-match, and that no markup is returned. It does not mention ranking or ordering of results, but the additions are real value.
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 compact sentence with the result cap and the empty-result behavior front-loaded, and no filler. It is perhaps overly terse given the undocumented param distinction, but nothing in it wastes space.
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 two-param search tool with rich annotations and no output schema, the description covers the essentials (cap, empty result, no markup). It stops short of defining the intent/query distinction or result ordering, which are the remaining gaps an agent would hit in practice.
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 carries the burden for both params. It clarifies that both are optional and combinable ('and/or'), but never explains what 'intent' means versus 'query' — the central semantic distinction an agent needs to fill them correctly. Partial compensation only.
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?
States a specific verb (Find) and resource (component summaries), and scopes it with 'up to 8 compact' and 'by intent and/or query'. 'Compact summaries' implicitly distinguishes it from get_component_details, though it never names the sibling or explains the boundary explicitly.
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 parenthetical '(either field may be omitted)' tells the agent both params are optional, which is useful invocation guidance. However, there is no explicit when-to-use-this-vs-validate_composition/get_component_details routing, so usage must be inferred from 'compact summaries'.
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. Pass code or alias html (not both with different values). Unknown input keys are ignored. Does not render or evaluate dynamic code.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | ||
| html | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description is free to add higher-value behavior: it is purely static and 'does not render or evaluate dynamic code', and unknown input keys are silently ignored. These are operationally relevant facts an agent would otherwise have to guess at.
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?
Four tightly packed sentences, purpose front-loaded followed by input rules and the static-evaluation caveat. Little waste; 'Include layout imports' is slightly terse but still earns its place as scope 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?
There is no output schema, so the description should ideally indicate what a validation result looks like (error list, diagnostics, severity). It fully specifies the input contract and the static-only nature of the check but leaves the return shape to inference, which is the main incompleteness.
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 carry the parameter burden, and it does: it explains that `code` and `html` are aliases, that they must not be passed with different values, and that unrecognized keys are ignored. It does not mention the 65536 maxLength constraint, which is the only remaining gap.
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?
States a specific verb ('statically check') and resource ('HTML/Astro source') plus the concrete error classes it detects (Basecoat migration errors, missing scripts, nested cards, spacing/hierarchy). It is unmistakably distinct in domain from the search_components/get_component_details siblings, but it never mentions them, so it falls short of explicit sibling differentiation.
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?
Usage is implied rather than stated: an agent can infer you call this to validate source before or during a Basecoat migration, and 'Include layout imports' hints at scope. There is no explicit when-to-use/when-not guidance or reference to any alternative tool.
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.3search_components1 field changedInput schema / requiredRemoved value: -[
- "intent",
- "query"
-]validate_composition2 fields changedInput schema / properties / htmlAdded value: +{
+ "maxLength": 65536,
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "code"
-]v1.0.1get_component_detailssearch_componentsvalidate_compositionScored across 3 tools
The three tools split cleanly along the discovery/inspection/validation axis: search_components finds summaries, get_component_details fetches one full template, and validate_composition checks code statically. search_components (summaries) and get_component_details (full details) are complementary rather than overlapping, though a novice agent might briefly wonder which to use for a known component name.
All three names follow a strict verb_noun snake_case pattern (search_components, validate_composition, get_component_details) with clear, predictable verbs. No mixed conventions or vague verbs appear.
Three tools is on the thin side, but each maps to a distinct stage of the component workflow (find, inspect, validate), so nothing feels redundant. It is slightly minimal for a library surface but well-scoped rather than padded.
The core loop of discovering components, retrieving templates with dependencies and tips, and statically validating composition is covered. Minor gaps exist (no way to list all components/categories or fetch full-page examples or theme tokens), but agents can work around these.
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
