What is HELiXiR?
HELiXiR is an MCP server for web component libraries. It reads your Custom Elements Manifest so an AI coding agent sees the real attributes, events, slots, CSS parts and design tokens of each component, with health scoring, validators and theme scaffolding on top.
HELiXiR answers questions such as how to use sl-button with the real API: variant, size, disabled, loading, outline, pill and href, the slots prefix and suffix, and the events sl-blur, sl-focus and sl-invalid.
The server reads the custom-elements.json file your library produces. Every attribute, event, slot and CSS part comes from that Custom Elements Manifest rather than from training data.
What the agent can look up
- Discovery. List components, search by name or description, and list events, slots and CSS
::part()targets across the library. - Component detail. Full metadata, a usage snippet, import statements, prop constraints and a dependency graph.
- Design tokens. List tokens by category or search them by name or value, once a tokens file is configured.
- Health and accessibility. A grade from A to F per component, plus ARIA roles, keyboard events and focus management.
Validators for generated code
validate_component_code runs 19 anti-hallucination sub-validators across HTML, CSS, JS, accessibility, events, methods and composition in one call. Separate check tools cover Shadow DOM styling, token fallbacks, dark mode and color contrast.
Where it fits
Best for
- Libraries built with Shoelace, Lit, Stencil, FAST, Spectrum, Vaadin or any library that produces a
custom-elements.jsonfile. - Styling Shadow DOM components with real
::part()names and CSS custom properties resolved against the manifest. - Scanning components for breaking changes against a base branch and generating Storybook CSF3 stories.
Not for
- Composition patterns, five styling approaches and component API rules for React, Vue and Svelte, which the web component design skill covers.
- Running a 12 category UI and UX audit on static HTML and CSS with three separate grades for design, AI slop and accessibility, which the design auditor skill covers.
- Checking HTML and CSS against W3C validators and capturing responsive screenshots, which the mcp-web-validator MCP server covers.
- Returning real colors, typography, spacing and W3C design tokens from a live URL with Dembrandt, which the extract design skill covers.
Connect HELiXiR MCP: Web Component Knowledge for AI Coding Agents to your AI client
npm install helixirInstall the package
Run the command above to add the package.
Generate a starter config
Run
npx helixir initin your component library. It writesmcpwc.config.jsonto the current directory.Point it at your library
Edit
mcpwc.config.jsonsocemPathnames yourcustom-elements.jsonfile andprojectRootis the absolute path to the library. AddtokensPathto enable the design token tools.Add it to your client
In the Claude Desktop config, add a
helixirentry undermcpServerswith commandnpx, args["helixir"]andMCP_WC_PROJECT_ROOTin env, then restart Claude Desktop.
Endpoints and ports
mcpwc.config.jsonCreated by npx helixir init; environment variables override its valuesMCP_WC_PROJECT_ROOTAbsolute path to the component library projectNode 22 or newerMinimum supported Node.js versionWhat you can do with it
- Real component APIsAttributes, events, slots and CSS parts are read from your Custom Elements Manifest, so an agent works from your library and not from training data.
- Framework coverageSetup notes cover Shoelace, Lit, Stencil, FAST, Adobe Spectrum Web Components and generic web components that produce a
custom-elements.jsonfile. - Design token lookupToken tools list tokens by category and search them by name or value. Setting
tokensPathto null disables them. - Health scoringEach component receives a grade from A to F with dimension scores, and
audit_librarywrites a JSONL report across 11 dimensions. - Shadow DOM validatorsCheck tools catch
!importanton tokens, misused::slotted(), invalid::part()chaining and styles that cannot reach shadow internals. - Theme scaffolding
create_themebuilds a CSS theme from the library's tokens with light and dark mode variables and color-scheme support. - Breaking-change scans
diff_cemandcheck_breaking_changescompare components against a base branch and highlight breaking changes and additions. - Story and type generationGenerate a Storybook CSF3 story with
generate_storyor TypeScript definitions for all custom elements withgenerate_types.
Tools it exposes
list_components
List all custom elements registered in the Custom Elements Manifest.
find_component
Semantic search for components by name, description or member names, returning the top 3 matches.
get_component
Full metadata for a component: members, events, slots, CSS parts and CSS properties.
suggest_usage
Generate an HTML snippet showing key attributes with their defaults and variant options.
get_design_tokens
List all design tokens, optionally filtered by category such as color or spacing.
find_token
Search for a design token by name or value with a case-insensitive substring match.
score_component
Latest health score for a component: grade from A to F, dimension scores and issues.
analyze_accessibility
Accessibility profile: ARIA roles, keyboard events, focus management and label support.
validate_component_code
All-in-one validator that runs 19 anti-hallucination sub-validators across HTML, CSS, JS, accessibility, events, methods and composition.
check_shadow_dom_usage
Scan CSS for Shadow DOM anti-patterns such as selectors piercing shadow boundaries and invalid ::part() chaining.
check_color_contrast
Detect low-contrast hardcoded color pairs, mixed color sources and low opacity on text.
create_theme
Scaffold a complete CSS theme from the library's design tokens with light and dark mode variables.
check_breaking_changes
Scan all components for breaking changes against a base branch, with a summary report.
generate_story
Generate a Storybook CSF3 story file for a component from its Custom Elements Manifest declaration.
Frequently asked questions
What is HELiXiR?
HELiXiR is an MCP server that gives an AI coding agent knowledge of a web component library. It reads the Custom Elements Manifest and exposes properties, events, slots, CSS parts, design tokens, accessibility data and health scores, so suggestions match the real component API.
How do I install the HELiXiR MCP server?
Run npm install helixir in your component library, then npx helixir init to write mcpwc.config.json. Edit the file to point at your manifest and project root, add a helixir entry to your client's MCP config with command npx and args helixir, and restart the client.
Which web component libraries does it support?
Setup notes cover Shoelace, Lit, Stencil, FAST, Adobe Spectrum Web Components and generic web components. Any library that produces a custom-elements.json Custom Elements Manifest works, and the load_library tool adds a further library by npm package name or manifest path.
How does it help with design tokens?
Set tokensPath in mcpwc.config.json to a design tokens JSON file. The agent can then call get_design_tokens to list tokens by category such as color or spacing, and find_token to search by name or value. Setting the path to null disables the token tools.
What does the health score measure?
Each component gets a grade from A to F with dimension scores. Dimensions include CEM completeness, accessibility, type coverage, API surface quality, test coverage, CSS architecture, event architecture, slot architecture and bundle size. You can customize the dimension weights in the scoring configuration.
How does it check code the agent generates?
validate_component_code runs 19 sub-validators in a single call, covering HTML, CSS, JS, accessibility, events, methods and composition. Other tools check Shadow DOM usage, token fallbacks, dark mode patterns and color contrast. The suggest_fix tool returns copy-pasteable fixes for issues found.
Which editors can connect to it?
HELiXiR has setup entries for Claude Code, Claude Desktop, Cursor, VS Code with Cline or Continue, and Zed. Most use command npx with args helixir and the MCP_WC_PROJECT_ROOT environment variable pointing at your component library project. Cursor and Cline can set it to the workspace folder. Claude Code and Claude Desktop need a reload or restart after saving.