{"id":46870833,"url":"https://github.com/bookedsolidtech/helixir","last_synced_at":"2026-04-01T18:26:25.935Z","repository":{"id":343532820,"uuid":"1169005011","full_name":"bookedsolidtech/helixir","owner":"bookedsolidtech","description":"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.","archived":false,"fork":false,"pushed_at":"2026-03-26T09:49:46.000Z","size":2382,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T10:32:26.532Z","etag":null,"topics":["accessibility","ai-coding","ai-tools","claude","component-library","cursor","custom-elements","custom-elements-manifest","design-system","design-tokens","developer-tools","lit","mcp","mcp-server","model-context-protocol","shoelace","stencil","typescript","web-components","windsurf"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/helixir","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bookedsolidtech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-28T03:41:59.000Z","updated_at":"2026-03-26T00:34:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bookedsolidtech/helixir","commit_stats":null,"previous_names":["bookedsolidtech/helixir"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/bookedsolidtech/helixir","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fhelixir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fhelixir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fhelixir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fhelixir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bookedsolidtech","download_url":"https://codeload.github.com/bookedsolidtech/helixir/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fhelixir/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","ai-coding","ai-tools","claude","component-library","cursor","custom-elements","custom-elements-manifest","design-system","design-tokens","developer-tools","lit","mcp","mcp-server","model-context-protocol","shoelace","stencil","typescript","web-components","windsurf"],"created_at":"2026-03-10T20:00:39.415Z","updated_at":"2026-04-01T18:26:25.926Z","avatar_url":"https://github.com/bookedsolidtech.png","language":"TypeScript","funding_links":[],"categories":["Medical MCP Servers"],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD041 --\u003e\n\u003cdiv align=\"center\"\u003e\n\n# HELiXiR\n\n**Give AI agents full situational awareness of any web component library.**\n\nStop AI hallucinations. Ground every component suggestion in your actual Custom Elements Manifest.\n\n[![npm version](https://img.shields.io/npm/v/helixir)](https://www.npmjs.com/package/helixir)\n[![npm downloads](https://img.shields.io/npm/dw/helixir)](https://www.npmjs.com/package/helixir)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node 20+](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)\n[![Build](https://img.shields.io/github/actions/workflow/status/bookedsolidtech/helixir/build.yml?branch=main\u0026label=build)](https://github.com/bookedsolidtech/helixir/actions/workflows/build.yml)\n[![Tests](https://img.shields.io/github/actions/workflow/status/bookedsolidtech/helixir/test.yml?branch=main\u0026label=tests)](https://github.com/bookedsolidtech/helixir/actions/workflows/test.yml)\n\n[Quick Start](#quick-start) · [Why HELiXiR](#why-helixir) · [Tools Reference](#tools-reference) · [Configuration](#configuration) · [AI Tool Configs](#ai-tool-configs)\n\n\u003c/div\u003e\n\n---\n\n## Why HELiXiR\n\n- **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.\n- **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.\n- **Works with any web component framework** — Shoelace, Lit, Stencil, FAST, Spectrum, Vaadin, and any library that produces a `custom-elements.json` CEM file.\n- **Any AI editor, zero lock-in** — Claude Code, Claude Desktop, Cursor, VS Code (Cline/Continue), Zed — one config, any tool.\n\n---\n\n## Quick Start\n\n**Under 60 seconds from zero to a component-aware AI agent.**\n\n```bash\nnpm install helixir\n```\n\nThen generate a starter config in your component library:\n\n```bash\nnpx helixir init\n# → writes mcpwc.config.json to the current directory\n```\n\nEdit `mcpwc.config.json` to point at your library:\n\n```json\n{\n  \"cemPath\": \"custom-elements.json\",\n  \"projectRoot\": \"/absolute/path/to/your/component-library\",\n  \"componentPrefix\": \"sl-\",\n  \"tokensPath\": \"dist/tokens/tokens.json\"\n}\n```\n\nAdd HELiXiR to your Claude Desktop config (see [AI Tool Configs](#ai-tool-configs) for other editors):\n\n```json\n{\n  \"mcpServers\": {\n    \"helixir\": {\n      \"command\": \"npx\",\n      \"args\": [\"helixir\"],\n      \"env\": {\n        \"MCP_WC_PROJECT_ROOT\": \"/absolute/path/to/your/component-library\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Done — your AI agent now knows every property, event, slot, CSS part, and design token in your library.\n\n---\n\n## What You Get\n\n### Without HELiXiR\n\n\u003e **You:** How do I use sl-button?\n\u003e\n\u003e **Claude:** You can use `\u003csl-button\u003e` like this:\n\u003e\n\u003e ```html\n\u003e \u003csl-button type=\"primary\" color=\"blue\" rounded\u003eClick me\u003c/sl-button\u003e\n\u003e ```\n\u003e\n\u003e It supports `type`, `color`, `rounded`, `icon`, and `label` attributes.\n\n**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.\n\n---\n\n### With HELiXiR\n\n\u003e **You:** How do I use sl-button?\n\u003e\n\u003e **Claude:** _(calls `get_component` → `sl-button`)_ Here's the accurate API for `\u003csl-button\u003e`:\n\u003e\n\u003e **Attributes:**\n\u003e\n\u003e - `variant` — `'default' | 'primary' | 'success' | 'neutral' | 'warning' | 'danger' | 'text'` (default: `'default'`)\n\u003e - `size` — `'small' | 'medium' | 'large'` (default: `'medium'`)\n\u003e - `disabled` — `boolean` (default: `false`)\n\u003e - `loading` — `boolean` — Draws the button in a loading state\n\u003e - `outline` — `boolean` — Draws an outlined button\n\u003e - `pill` — `boolean` — Draws a pill-style button with rounded edges\n\u003e - `href` — `string | undefined` — Renders as `\u003ca\u003e` when set\n\u003e\n\u003e **Slots:** default (button label), `prefix` (before label), `suffix` (after label)\n\u003e\n\u003e **Events:** `sl-blur`, `sl-focus`, `sl-invalid`\n\u003e\n\u003e **Example:**\n\u003e\n\u003e ```html\n\u003e \u003csl-button variant=\"primary\" size=\"medium\"\u003eSave changes\u003c/sl-button\u003e\n\u003e ```\n\n**Every property, event, slot, CSS part, and design token — sourced directly from your Custom Elements Manifest. No hallucinations.**\n\n---\n\n## Framework Setup\n\nHELiXiR 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.\n\n### Shoelace\n\nShoelace ships `custom-elements.json` inside its npm package. No build step needed.\n\n```bash\nnpm install @shoelace-style/shoelace\n```\n\n```json\n{\n  \"cemPath\": \"node_modules/@shoelace-style/shoelace/dist/custom-elements.json\",\n  \"componentPrefix\": \"sl-\"\n}\n```\n\n### Lit\n\nUse the official CEM analyzer with the Lit plugin:\n\n```bash\nnpm install -D @custom-elements-manifest/analyzer\n```\n\n```json\n// package.json scripts\n\"analyze\": \"cem analyze --litelement --globs 'src/**/*.ts'\"\n```\n\n```json\n{\n  \"cemPath\": \"custom-elements.json\",\n  \"componentPrefix\": \"my-\"\n}\n```\n\nRun `npm run analyze` after each build to keep the CEM current.\n\n### Stencil\n\nEnable CEM output in `stencil.config.ts`:\n\n```ts\n// stencil.config.ts\nimport { Config } from '@stencil/core';\n\nexport const config: Config = {\n  outputTargets: [{ type: 'docs-custom' }, { type: 'dist-custom-elements' }],\n};\n```\n\nStencil emits `custom-elements.json` to your `dist/` folder:\n\n```json\n{\n  \"cemPath\": \"dist/custom-elements/custom-elements.json\",\n  \"componentPrefix\": \"my-\"\n}\n```\n\n### FAST\n\nFAST components ship with CEM support via the `@custom-elements-manifest/analyzer`:\n\n```bash\nnpm install -D @custom-elements-manifest/analyzer\n```\n\n```json\n// package.json scripts\n\"analyze\": \"cem analyze --globs 'src/**/*.ts'\"\n```\n\n```json\n{\n  \"cemPath\": \"custom-elements.json\",\n  \"componentPrefix\": \"fluent-\"\n}\n```\n\n### Adobe Spectrum Web Components\n\nSpectrum Web Components use Stencil under the hood and ship their CEM in the package:\n\n```bash\nnpm install @spectrum-web-components/bundle\n```\n\n```json\n{\n  \"cemPath\": \"node_modules/@spectrum-web-components/bundle/custom-elements.json\",\n  \"componentPrefix\": \"sp-\"\n}\n```\n\n### Polymer / Generic Web Components\n\nAny project can add CEM generation with the analyzer:\n\n```bash\nnpm install -D @custom-elements-manifest/analyzer\n```\n\n```json\n// package.json scripts\n\"analyze\": \"cem analyze --globs 'src/**/*.js'\"\n```\n\n```json\n{\n  \"cemPath\": \"custom-elements.json\"\n}\n```\n\n---\n\n## Tools Reference\n\nAll tools are exposed over the [Model Context Protocol](https://modelcontextprotocol.io). Your AI agent can call any of these tools by name.\n\n### Discovery\n\n| Tool                          | Description                                                                          | Required Args          |\n| ----------------------------- | ------------------------------------------------------------------------------------ | ---------------------- |\n| `list_components`             | List all custom elements registered in the CEM                                       | —                      |\n| `find_component`              | Semantic search for components by name, description, or member names (top 3 matches) | `query`                |\n| `get_library_summary`         | Overview of the library: component count, average health score, grade distribution   | —                      |\n| `list_events`                 | List all events across the library, optionally filtered by component                 | `tagName` _(optional)_ |\n| `list_slots`                  | List all slots across the library, optionally filtered by component                  | `tagName` _(optional)_ |\n| `list_css_parts`              | List all CSS `::part()` targets across the library, optionally filtered by component | `tagName` _(optional)_ |\n| `list_components_by_category` | Group components by functional category (form, navigation, feedback, layout, etc.)   | —                      |\n\n### Component\n\n| Tool                          | Description                                                                                           | Required Args              |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------- |\n| `get_component`               | Full metadata for a component: members, events, slots, CSS parts, CSS properties                      | `tagName`                  |\n| `validate_cem`                | Validate CEM documentation completeness; returns score (0–100) and issues list                        | `tagName`                  |\n| `suggest_usage`               | Generate an HTML snippet showing key attributes with their defaults and variant options               | `tagName`                  |\n| `generate_import`             | Generate side-effect and named import statements from CEM exports                                     | `tagName`                  |\n| `get_component_narrative`     | 3–5 paragraph markdown prose description of a component optimized for LLM comprehension               | `tagName`                  |\n| `get_prop_constraints`        | Structured constraint table for an attribute: union values with descriptions, or simple type info     | `tagName`, `attributeName` |\n| `find_components_by_token`    | Find all components that expose a given CSS custom property token                                     | `tokenName`                |\n| `find_components_using_token` | Find all components referencing a token in their `cssProperties` (works without `tokensPath`)         | `tokenName`                |\n| `get_component_dependencies`  | Dependency graph for a component: direct and transitive dependencies from CEM reference data          | `tagName`                  |\n| `validate_usage`              | Validate a proposed HTML snippet against the CEM spec: unknown attrs, bad slot names, enum mismatches | `tagName`, `html`          |\n\n### Composition\n\n| Tool                      | Description                                                                                      | Required Args |\n| ------------------------- | ------------------------------------------------------------------------------------------------ | ------------- |\n| `get_composition_example` | Realistic HTML snippet showing how to compose 1–4 components together using their slot structure | `tagNames`    |\n\n### Health\n\n| Tool                    | Description                                                                         | Required Args          |\n| ----------------------- | ----------------------------------------------------------------------------------- | ---------------------- |\n| `score_component`       | Latest health score for a component: grade (A–F), dimension scores, and issues      | `tagName`              |\n| `score_all_components`  | Health scores for every component in the library                                    | —                      |\n| `get_health_trend`      | Health trend for a component over the last N days with trend direction              | `tagName`              |\n| `get_health_diff`       | Before/after health comparison between current branch and a base branch             | `tagName`              |\n| `get_health_summary`    | Aggregate health stats for all components: average score, grade distribution        | —                      |\n| `analyze_accessibility` | Accessibility profile: ARIA roles, keyboard events, focus management, label support | `tagName` _(optional)_ |\n\n### Library\n\n| Tool             | Description                                                              | Required Args |\n| ---------------- | ------------------------------------------------------------------------ | ------------- |\n| `load_library`   | Load an additional web component library by npm package name or CEM path | `libraryId`   |\n| `list_libraries` | List all currently loaded web component libraries                        | —             |\n| `unload_library` | Remove a loaded library from memory                                      | `libraryId`   |\n\n### Safety\n\n| Tool                     | Description                                                                        | Required Args           |\n| ------------------------ | ---------------------------------------------------------------------------------- | ----------------------- |\n| `diff_cem`               | Per-component CEM diff between branches; highlights breaking changes and additions | `tagName`, `baseBranch` |\n| `check_breaking_changes` | Breaking-change scan across all components vs. a base branch with summary report   | `baseBranch`            |\n\n### Framework\n\n| Tool               | Description                                                                               | Required Args |\n| ------------------ | ----------------------------------------------------------------------------------------- | ------------- |\n| `detect_framework` | Identifies the web component framework in use from package.json, CEM metadata, and config | —             |\n\n### TypeScript\n\n| Tool                      | Description                                               | Required Args |\n| ------------------------- | --------------------------------------------------------- | ------------- |\n| `get_file_diagnostics`    | TypeScript diagnostics for a single file                  | `filePath`    |\n| `get_project_diagnostics` | Full TypeScript diagnostic pass across the entire project | —             |\n\n### Story\n\n| Tool             | Description                                                                        | Required Args |\n| ---------------- | ---------------------------------------------------------------------------------- | ------------- |\n| `generate_story` | Generates a Storybook CSF3 story file for a component based on its CEM declaration | `tagName`     |\n\n### Bundle\n\n| Tool                   | Description                                                                                 | Required Args |\n| ---------------------- | ------------------------------------------------------------------------------------------- | ------------- |\n| `estimate_bundle_size` | Estimates minified + gzipped bundle size for a component's npm package via bundlephobia/npm | `tagName`     |\n\n**`package` parameter derivation:**\n\nThe `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:\n\n| Prefix    | npm Package                |\n| --------- | -------------------------- |\n| `sl`      | `@shoelace-style/shoelace` |\n| `fluent-` | `@fluentui/web-components` |\n| `mwc-`    | `@material/web`            |\n| `ion-`    | `@ionic/core`              |\n| `vaadin-` | `@vaadin/components`       |\n| `lion-`   | `@lion/ui`                 |\n| `pf-`     | `@patternfly/elements`     |\n| `carbon-` | `@carbon/web-components`   |\n\nIf 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.\n\n### Benchmark\n\n| Tool                  | Description                                                                                                                  | Required Args |\n| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------- |\n| `benchmark_libraries` | Compare 2–10 web component libraries by health score, documentation quality, and API surface; returns a weighted score table | `libraries`   |\n\n### CDN\n\n| Tool              | Description                                                                                           | Required Args |\n| ----------------- | ----------------------------------------------------------------------------------------------------- | ------------- |\n| `resolve_cdn_cem` | Fetch and cache a library's CEM from jsDelivr or UNPKG by npm package name (for CDN-loaded libraries) | `package`     |\n\n### Tokens\n\n_(Requires `tokensPath` to be configured)_\n\n| Tool                | Description                                                                           | Required Args |\n| ------------------- | ------------------------------------------------------------------------------------- | ------------- |\n| `get_design_tokens` | List all design tokens, optionally filtered by category (e.g. `\"color\"`, `\"spacing\"`) | —             |\n| `find_token`        | Search for a design token by name or value (case-insensitive substring match)         | `query`       |\n\n---\n\n## Configuration\n\nConfiguration is resolved in priority order: **environment variables \u003e `mcpwc.config.json` \u003e defaults**.\n\n### `mcpwc.config.json`\n\nPlace this file at the root of your component library project (or wherever `MCP_WC_PROJECT_ROOT` points).\n\n| Key                | Type             | Default                  | Description                                                                                                                                                                                                                                                           |\n| ------------------ | ---------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `cemPath`          | `string`         | `\"custom-elements.json\"` | Path to the Custom Elements Manifest, relative to `projectRoot`. Auto-discovered if omitted.                                                                                                                                                                          |\n| `projectRoot`      | `string`         | `process.cwd()`          | Absolute path to the component library project root.                                                                                                                                                                                                                  |\n| `componentPrefix`  | `string`         | `\"\"`                     | Optional tag-name prefix (e.g. `\"sl-\"`) to scope component discovery.                                                                                                                                                                                                 |\n| `healthHistoryDir` | `string`         | `\".mcp-wc/health\"`       | Directory where health snapshots are stored, relative to `projectRoot`.                                                                                                                                                                                               |\n| `tsconfigPath`     | `string`         | `\"tsconfig.json\"`        | Path to the project's `tsconfig.json`, relative to `projectRoot`.                                                                                                                                                                                                     |\n| `tokensPath`       | `string \\| null` | `null`                   | Path to a design tokens JSON file. Set to `null` to disable token tools.                                                                                                                                                                                              |\n| `cdnBase`          | `string \\| null` | `null`                   | Base URL prepended to component paths when generating CDN `\u003cscript\u003e` and `\u003clink\u003e` tags in `suggest_usage` output (e.g. `\"https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2/cdn\"`). Does not affect `resolve_cdn_cem`. Set to `null` to disable CDN suggestions. |\n| `watch`            | `boolean`        | `false`                  | When `true`, HELiXiR automatically reloads the CEM on file changes.                                                                                                                                                                                                   |\n\n**Full example:**\n\n```json\n{\n  \"cemPath\": \"dist/custom-elements.json\",\n  \"projectRoot\": \"/home/user/my-design-system\",\n  \"componentPrefix\": \"ds-\",\n  \"healthHistoryDir\": \".mcp-wc/health\",\n  \"tsconfigPath\": \"tsconfig.build.json\",\n  \"tokensPath\": \"dist/tokens/tokens.json\",\n  \"cdnBase\": \"https://cdn.jsdelivr.net/npm\"\n}\n```\n\n### Environment Variables\n\nEnvironment variables override all config file values. Useful for CI or when pointing the same server at different libraries.\n\n| Variable                    | Overrides          |\n| --------------------------- | ------------------ |\n| `MCP_WC_PROJECT_ROOT`       | `projectRoot`      |\n| `MCP_WC_CEM_PATH`           | `cemPath`          |\n| `MCP_WC_COMPONENT_PREFIX`   | `componentPrefix`  |\n| `MCP_WC_HEALTH_HISTORY_DIR` | `healthHistoryDir` |\n| `MCP_WC_TSCONFIG_PATH`      | `tsconfigPath`     |\n| `MCP_WC_TOKENS_PATH`        | `tokensPath`       |\n| `MCP_WC_CDN_BASE`           | `cdnBase`          |\n\nSet `MCP_WC_TOKENS_PATH=null` (the string `\"null\"`) to explicitly disable token tools via env var.\n\nSee [`mcpwc.config.json.example`](./mcpwc.config.json.example) for a ready-to-copy template.\n\n---\n\n## AI Tool Configs\n\n### Claude Code (CLI)\n\nAdd to `.mcp.json` in your project root (project-scoped) or `~/.claude.json` (global):\n\n**Option 1 — Install from npm (recommended)**\n\n```bash\nnpx helixir init  # generates mcpwc.config.json in your project root\n```\n\nThen add to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"helixir\": {\n      \"command\": \"npx\",\n      \"args\": [\"helixir\"],\n      \"env\": {\n        \"MCP_WC_PROJECT_ROOT\": \"/absolute/path/to/your/component-library\"\n      }\n    }\n  }\n}\n```\n\n**Option 2 — Install from local clone (development)**\n\n```bash\ngit clone https://github.com/bookedsolidtech/helixir.git\ncd helixir\npnpm install\npnpm build\n```\n\nThen add to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"helixir\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/helixir/build/index.js\"],\n      \"env\": {\n        \"MCP_WC_PROJECT_ROOT\": \"/absolute/path/to/your/component-library\"\n      }\n    }\n  }\n}\n```\n\nReload Claude Code after saving (`:mcp` to verify the server appears).\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"helixir\": {\n      \"command\": \"npx\",\n      \"args\": [\"helixir\"],\n      \"env\": {\n        \"MCP_WC_PROJECT_ROOT\": \"/absolute/path/to/your/component-library\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):\n\n```json\n{\n  \"mcpServers\": {\n    \"helixir\": {\n      \"command\": \"npx\",\n      \"args\": [\"helixir\"],\n      \"env\": {\n        \"MCP_WC_PROJECT_ROOT\": \"${workspaceFolder}\"\n      }\n    }\n  }\n}\n```\n\n### VS Code (Cline / Continue)\n\n**Cline** — add to `.vscode/cline_mcp_settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"helixir\": {\n      \"command\": \"npx\",\n      \"args\": [\"helixir\"],\n      \"env\": {\n        \"MCP_WC_PROJECT_ROOT\": \"${workspaceFolder}\"\n      }\n    }\n  }\n}\n```\n\n**Continue** — add to `~/.continue/config.json` under `mcpServers`:\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"helixir\",\n      \"command\": \"npx helixir\",\n      \"env\": {\n        \"MCP_WC_PROJECT_ROOT\": \"/absolute/path/to/your/component-library\"\n      }\n    }\n  ]\n}\n```\n\n### Zed\n\nAdd to your Zed settings (`~/.config/zed/settings.json`):\n\n```json\n{\n  \"context_servers\": {\n    \"helixir\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"helixir\"],\n        \"env\": {\n          \"MCP_WC_PROJECT_ROOT\": \"/absolute/path/to/your/component-library\"\n        }\n      }\n    }\n  }\n}\n```\n\n---\n\n## Security\n\nHELiXiR applies defense-in-depth on all inputs that touch the file system or network:\n\n- **Path containment** — all file paths are resolved and verified to stay within `projectRoot`; `..` traversals and absolute paths outside the root are rejected.\n- **Input validation** — every tool argument is validated with [Zod](https://zod.dev) schemas before reaching handler code; unknown properties are rejected via `additionalProperties: false`.\n- **CDN safety** — `resolve_cdn_cem` only fetches from allowlisted CDN origins (jsDelivr, UNPKG); arbitrary URLs are not accepted.\n- **No shell execution** — the server never spawns subprocesses based on user input; TypeScript diagnostics use the TS compiler API in-process.\n\nSee [`SECURITY.md`](./SECURITY.md) for the vulnerability disclosure policy.\n\n---\n\n## Quality Gates\n\nEvery pull request must pass all five CI checks before merge:\n\n| Workflow     | What it checks                                      |\n| ------------ | --------------------------------------------------- |\n| **build**    | TypeScript type-check + `tsc` compile on Node 20/22 |\n| **test**     | Full vitest suite with coverage on Node 20/22       |\n| **lint**     | ESLint (TypeScript + Prettier compatibility rules)  |\n| **format**   | Prettier formatting check                           |\n| **security** | `pnpm audit --audit-level=high`                     |\n\n**Pre-commit hooks** (via [husky](https://typicode.github.io/husky/) + [lint-staged](https://github.com/lint-staged/lint-staged)):\n\n- TypeScript/JavaScript files: ESLint auto-fix → Prettier format\n- JSON/CSS/Markdown/YAML files: Prettier format\n- Commit messages: validated by [commitlint](https://commitlint.js.org) against conventional-commits format\n\n**Allowed commit types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`, `audit`\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`LOCAL.md`](./LOCAL.md) for full setup details.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\nQuick steps:\n\n1. Fork the repo and create a feature branch.\n2. Run `pnpm install` to install dependencies.\n3. Make your changes in `src/`.\n4. Run `pnpm test` to ensure all tests pass.\n5. Run `pnpm run lint \u0026\u0026 pnpm run format:check` before submitting.\n6. Open a pull request with a clear description of the change.\n\nIssues and feature requests are welcome on GitHub.\n\n---\n\n## License\n\nMIT © 2025-2026 Clarity House LLC d/b/a Booked Solid Technology\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbookedsolidtech%2Fhelixir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbookedsolidtech%2Fhelixir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbookedsolidtech%2Fhelixir/lists"}