# Helixir

> MCP server that gives AI coding agents deep knowledge of any web component library — properties, events, slots, CSS parts, design tokens, accessibility, health scoring, and more. Works with Claude, Cursor, Windsurf, and any MCP-compatible tool.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bookedsolidtech-helixir`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bookedsolidtech](https://agentstack.voostack.com/s/bookedsolidtech)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bookedsolidtech](https://github.com/bookedsolidtech)
- **Source:** https://github.com/bookedsolidtech/helixir
- **Website:** https://www.npmjs.com/package/helixir

## Install

```sh
agentstack add mcp-bookedsolidtech-helixir
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.**

```bash
npm install helixir
```

Then generate a starter config in your component library:

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

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

```json
{
  "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):

```json
{
  "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`](https://github.com/webcomponents/custom-elements-manifest) (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.

```bash
npm install @shoelace-style/shoelace
```

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

### Lit

Use the official CEM analyzer with the Lit plugin:

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

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

```json
{
  "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`:

```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:

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

### FAST

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

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

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

```json
{
  "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:

```bash
npm install @spectrum-web-components/bundle
```

```json
{
  "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:

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

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

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

---

## Tools Reference

All tools are exposed over the [Model Context Protocol](https://modelcontextprotocol.io). 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](https://github.com/bookedsolidtech)
- **Source:** [bookedsolidtech/helixir](https://github.com/bookedsolidtech/helixir)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/helixir

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bookedsolidtech-helixir
- Seller: https://agentstack.voostack.com/s/bookedsolidtech
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.