<div align="center">

HELiXiR

Give AI agents full situational awareness of any web component library.

Stop AI hallucinations. Ground every component suggestion in your actual Custom Elements Manifest.

Quick Start · Why HELiXiR · Tools Reference · Configuration · AI Tool Configs

</div>

Why HELiXiR

No more hallucinations — AI reads your real component API from the Custom Elements Manifest, not from training data. Every attribute, event, slot, and CSS part is sourced directly from your library.
30+ MCP tools out of the box — Component discovery, health scoring, design token lookup, TypeScript diagnostics, breaking-change detection, and Storybook story generation — all callable by any MCP-compatible AI agent.
Works with any web component framework — Shoelace, Lit, Stencil, FAST, Spectrum, Vaadin, and any library that produces a custom-elements.json CEM file.
Any AI editor, zero lock-in — Claude Code, Claude Desktop, Cursor, VS Code (Cline/Continue), Zed — one config, any tool.

Quick Start

Under 60 seconds from zero to a component-aware AI agent.

npm install helixir

Then generate a starter config in your component library:

npx helixir init
# → writes mcpwc.config.json to the current directory

Edit mcpwc.config.json to point at your library:

{
  "cemPath": "custom-elements.json",
  "projectRoot": "/absolute/path/to/your/component-library",
  "componentPrefix": "sl-",
  "tokensPath": "dist/tokens/tokens.json"
}

Add HELiXiR to your Claude Desktop config (see AI Tool Configs for other editors):

{
  "mcpServers": {
    "helixir": {
      "command": "npx",
      "args": ["helixir"],
      "env": {
        "MCP_WC_PROJECT_ROOT": "/absolute/path/to/your/component-library"
      }
    }
  }
}

Restart Claude Desktop. Done — your AI agent now knows every property, event, slot, CSS part, and design token in your library.

What You Get

Without HELiXiR

You: How do I use sl-button?

Claude: You can use <sl-button> like this:
<sl-button type="primary" color="blue" rounded>Click me</sl-button>
It supports type, color, rounded, icon, and label attributes.

All of that is hallucinated. type, color, rounded, icon, and label are not real attributes on sl-button. The correct attribute for the visual style is variant, and rounded doesn't exist at all.

With HELiXiR

You: How do I use sl-button?

Claude: (calls get_component → sl-button) Here's the accurate API for <sl-button>:

Attributes:

variant — 'default' | 'primary' | 'success' | 'neutral' | 'warning' | 'danger' | 'text' (default: 'default')

size — 'small' | 'medium' | 'large' (default: 'medium')

disabled — boolean (default: false)

loading — boolean — Draws the button in a loading state

outline — boolean — Draws an outlined button

pill — boolean — Draws a pill-style button with rounded edges

href — string | undefined — Renders as <a> when set

Slots: default (button label), prefix (before label), suffix (after label)

Events: sl-blur, sl-focus, sl-invalid

Example:
<sl-button variant="primary" size="medium">Save changes</sl-button>

Every property, event, slot, CSS part, and design token — sourced directly from your Custom Elements Manifest. No hallucinations.

Framework Setup

HELiXiR works with any toolchain that produces a custom-elements.json (CEM). Below are quick-start setups for the most common frameworks.

Shoelace

Shoelace ships custom-elements.json inside its npm package. No build step needed.

npm install @shoelace-style/shoelace

{
  "cemPath": "node_modules/@shoelace-style/shoelace/dist/custom-elements.json",
  "componentPrefix": "sl-"
}

Lit

Use the official CEM analyzer with the Lit plugin:

npm install -D @custom-elements-manifest/analyzer

// package.json scripts
"analyze": "cem analyze --litelement --globs 'src/**/*.ts'"

{
  "cemPath": "custom-elements.json",
  "componentPrefix": "my-"
}

Run npm run analyze after each build to keep the CEM current.

Stencil

Enable CEM output in stencil.config.ts:

// stencil.config.ts
import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [{ type: 'docs-custom' }, { type: 'dist-custom-elements' }],
};

Stencil emits custom-elements.json to your dist/ folder:

{
  "cemPath": "dist/custom-elements/custom-elements.json",
  "componentPrefix": "my-"
}

FAST

FAST components ship with CEM support via the @custom-elements-manifest/analyzer:

npm install -D @custom-elements-manifest/analyzer

// package.json scripts
"analyze": "cem analyze --globs 'src/**/*.ts'"

{
  "cemPath": "custom-elements.json",
  "componentPrefix": "fluent-"
}

Adobe Spectrum Web Components

Spectrum Web Components use Stencil under the hood and ship their CEM in the package:

npm install @spectrum-web-components/bundle

{
  "cemPath": "node_modules/@spectrum-web-components/bundle/custom-elements.json",
  "componentPrefix": "sp-"
}

Polymer / Generic Web Components

Any project can add CEM generation with the analyzer:

npm install -D @custom-elements-manifest/analyzer

// package.json scripts
"analyze": "cem analyze --globs 'src/**/*.js'"

{
  "cemPath": "custom-elements.json"
}

Tools Reference

All tools are exposed over the Model Context Protocol. Your AI agent can call any of these tools by name.

Discovery

| Tool | Description | Required Args | | ----------------------------- | ------------------------------------------------------------------------------------ | ---------------------- | | list_components | List all custom elements registered in the CEM | — | | find_component | Semantic search for components by name, description, or member names (top 3 matches) | query | | get_library_summary | Overview of the library: component count, average health score, grade distribution | — | | list_events | List all events across the library, optionally filtered by component | tagName (optional) | | list_slots | List all slots across the library, optionally filtered by component | tagName (optional) | | list_css_parts | List all CSS ::part() targets across the library, optionally filtered by component | tagName (optional) | | list_components_by_category | Group components by functional category (form, navigation, feedback, layout, etc.) | — |

Component

| Tool | Description | Required Args | | ----------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------- | | get_component | Full metadata for a component: members, events, slots, CSS parts, CSS properties | tagName | | validate_cem | Validate CEM documentation completeness; returns score (0–100) and issues list | tagName | | suggest_usage | Generate an HTML snippet showing key attributes with their defaults and variant options | tagName | | generate_import | Generate side-effect and named import statements from CEM exports | tagName | | get_component_narrative | 3–5 paragraph markdown prose description of a component optimized for LLM comprehension | tagName | | get_prop_constraints | Structured constraint table for an attribute: union values with descriptions, or simple type info | tagName, attributeName | | find_components_by_token | Find all components that expose a given CSS custom property token | tokenName | | find_components_using_token | Find all components referencing a token in their cssProperties (works without tokensPath) | tokenName | | get_component_dependencies | Dependency graph for a component: direct and transitive dependencies from CEM reference data | tagName | | validate_usage

Helixir

Install / Use

README