# 🔌 @viasat/beam-react-mcp

MCP server for the Beam React design system. It gives AI coding tools (Claude Code, Cursor, VS Code, etc.) accurate, structured access to Beam component APIs, props, usage examples, and concept docs — so they stop guessing prop names and produce correct Beam usage.

## 🧰 What it provides

Seven tools, served over **stdio** from a static manifest bundled inside the package. No network calls.

| Tool                                  | What it returns                                                              |
| ------------------------------------- | ---------------------------------------------------------------------------- |
| `listComponents(query?, category?)`   | The component catalog — name, slug, category, description                    |
| `getComponent(name)`                  | Props, subcomponent props, paired hooks/providers (with signatures), and the list of available story names |
| `getComponentStory(component, story)` | The JSX source for one named story                                           |
| `listConcepts()`                      | Concept docs (theming, accessibility, getting started, …)                    |
| `getConcept(name)`                    | Full content for one concept doc                                             |
| `listIconGroups()`                    | The icon groups — import path and icon count, no names                       |
| `searchIcons(query, group?, limit?)`  | Matching icon names, grouped by import path                                  |

Icons are a two-step lookup: `listIconGroups()` to see what families exist (main, illustrative, logos by group), then `searchIcons()` to find one. The catalog is a few thousand names, so there is no tool that dumps it.

The main group (`@viasat/beam-icons/icons`, 2,714 of the 3,777 icons) uses **Material Symbols names, PascalCased** — `access_alarm` → `AccessAlarm`, `wb_incandescent` → `WbIncandescent`, plus Material's filled/outlined pairs (`Delete` / `DeleteOutlined`). Search the Material name rather than guessing an industry nickname. The casing conversion is imperfect in places (Material's `AccountCircle` is `Accountcircle` here, `ArrowDropDown` is `ArrowDropdown`), so type the name as words and let the case- and separator-insensitive matching sort it out. `illustrative-icons` and `logos/*` are Beam-authored rather than Material — search those by subject or brand.

Matching is literal substring, not semantic, so nicknames miss (`hamburger` → nothing; it's `Menu`) or mislead (`mute` ranks `Commute` above `VolumeMute`). A zero-result nickname search doesn't mean the icon is missing — retry with the Material name.

## ✅ Requirements

- Node.js >= 20.11

## 🛠️ Usage

Add the server to your MCP client config. For Claude Code (`.mcp.json` in your project root):

```json
{
  "mcpServers": {
    "beam": {
      "command": "npx",
      "args": ["-y", "@viasat/beam-react-mcp"]
    }
  }
}
```

Restart your editor, then ask something like _"What props does the Beam Button accept?"_ — the model will call the tools and return real data from the manifest instead of guessing.

## 📝 Notes

- **Offline:** all data ships inside the package; the server makes no network requests.
- **Restart on failure:** this is a stdio server, which does not auto-restart. If the Beam tools disappear from your session, restart your editor.
- The component data reflects the version of `@viasat/beam-react` the server was built from — see `beamVersion` in the bundled `beam-manifest.json`.