Helixir

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.

[](https://www.npmjs.com/package/helixir) [](https://www.npmjs.com/package/helixir) [](https://opensource.org/licenses/MIT) [](https://nodejs.org) [](https://github.com/bookedsolidtech/helixir/actions/workflows/build.yml) [](https://github.com/bookedsolidtech/helixir/actions/workflows/test.yml) [](https://modelcontextprotocol.io) [](https://www.typescriptlang.org) [](https://www.npmjs.com/package/helixir)

[Quick Start](#quick-start) · [Why HELiXiR](#why-helixir) · [Tools Reference](#tools-reference) · [Configuration](#configuration) · [AI Tool Configs](#ai-tool-configs)

---

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.
• 87+ MCP tools out of the box — Component discovery, health scoring, design token lookup, TypeScript diagnostics, breaking-change detection, Storybook story generation, Shadow DOM styling validators, theme scaffolding, and scaffold/extend tools — 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](#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 ` like this: > > `html > Click me > ` > > 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 `: > > **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 when set > > **Slots:** default (button label), prefix (before label), suffix (after label) > > **Events:** sl-blur, sl-focus, sl-invalid > > **Example:** > > `html > Save changes > ``

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 | Validate a proposed HTML snippet against the CEM spec: unknown attrs, bad slot names, enum mismatches | tagName, html |

Composition

| Tool | Description | Required Args | | ------------------------- | ------------------------------------------------------------------------------------------------ | ------------- | | get_composition_example | Realistic HTML snippet showing how to compose 1–4 components together using their slot structure | tagNames |

Health

| Tool | Description | Required Args | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | score_component | Latest health score for a component: grade (A–F), dimension scores, and issues | tagName | | score_all_components | Health scores for every component in the library | — | | get_health_trend | Health trend for a component over the last N days with trend direction | tagName | | get_health_diff | Before/after health comparison between current branch and a base branch | tagName | | get_health_summary | Aggregate health stats for all components: average score, grade distribution | — | | analyze_accessibility | Accessibility profile: ARIA roles, keyboard events, focus management, label support | tagName (optional) | | audit_library | Generates a JSONL audit report scoring every component across 11 dimensions; returns file path (if outputPath given) and summary stats | — |

Library

| Tool | Description | Required Args | | ---------------- | ------------------------------------------------------------------------ | ------------- | | load_library | Load an additional web component library by npm package name or CEM path | libraryId | | list_libraries | List all currently loaded web component libraries | — | | unload_library | Remove a loaded library from memory | libraryId |

Safety

| Tool | Description | Required Args | | ------------------------ | ---------------------------------------------------------------------------------- | ----------------------- | | diff_cem | Per-component CEM diff between branches; highlights breaking changes and additions | tagName, baseBranch | | check_breaking_changes | Breaking-change scan across all components vs. a base branch with summary report | baseBranch |

Framework

| Tool | Description | Required Args | | ------------------ | ----------------------------------------------------------------------------------------- | ------------- | | detect_framework | Identifies the web component framework in use from package.json, CEM metadata, and config | — |

TypeScript

| Tool | Description | Required Args | | ------------------------- | --------------------------------------------------------- | ------------- | | get_file_diagnostics | TypeScript diagnostics for a single file | filePath | | get_project_diagnostics | Full TypeScript diagnostic pass across the entire project | — |

Story

| Tool | Description | Required Args | | ---------------- | ---------------------------------------------------------------------------------- | ------------- | | generate_story | Generates a Storybook CSF3 story file for a component based on its CEM declaration | tagName |

Bundle

| Tool | Description | Required Args | | ---------------------- | ------------------------------------------------------------------------------------------- | ------------- | | estimate_bundle_size | Estimates minified + gzipped bundle size for a component's npm package via bundlephobia/npm | tagName |

package parameter derivation:

The estimate_bundle_size tool accepts an optional package argument — the npm package name to look up (e.g. "@shoelace-style/shoelace"). When omitted, the tool derives the package name from your componentPrefix config value using a built-in prefix-to-package map:

| Prefix | npm Package | | --------- | -------------------------- | | sl | @shoelace-style/shoelace | | fluent- | @fluentui/web-components | | mwc- | @material/web | | ion- | @ionic/core | | vaadin- | @vaadin/components | | lion- | @lion/ui | | pf- | @patternfly/elements | | carbon- | @carbon/web-components |

If your prefix is not in the list above and you omit package, the tool returns a VALIDATION error. In that case, pass the package argument explicitly.

Benchmark

| Tool | Description | Required Args | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------- | | benchmark_libraries | Compare 2–10 web component libraries by health score, documentation quality, and API surface; return

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bookedsolidtech
• Source: bookedsolidtech/helixir
• License: MIT
• Homepage: https://www.npmjs.com/package/helixir

Install and usage instructions live in the source repository linked above.