# impact-nova-mcp

MCP (Model Context Protocol) server for **Impact Nova**, the enterprise React design system. Use it in **Cursor**, **Windsurf**, **Claude** (Desktop and Claude Code), **Antigravity**, or any MCP client to get component specs, design tokens, best practices, and generated code that follows Impact Nova conventions.

## What it does

- **Registry-backed discovery** — `query_components`, `get_component_props`, `get_deprecations` from generated component registry (65 components).
- **Get component specs** — Import path, variants, sizes, subcomponents, SSR/RSC placement, usage snippets.
- **Design tokens** — Colors, radius, spacing, typography (for codegen and design handoff).
- **Generate code** — Component usage and full pages/sections with correct imports and conventions.
- **Best practices** — Do's and don'ts (composition, tokens, a11y, i18n, **no unnecessary classNames**).
- **Accessibility (optional)** — Optional resource for labels, keyboard, focus, screen readers (`impact-nova://accessibility`). Not required.
- **Troubleshooting** — Common issues: dual React/AG Grid, styles, font, Chart path, AG Grid license (`impact-nova://troubleshooting`).
- **Charts** — Chart/Highcharts patterns via `get_real_world_patterns` topic `chart`; use Highcharts docs for series/options.
- **Validate snippets** — `validate_snippet` checks imports, AST charter rules, and design-system compliance before shipping UI code.
- **Install & configure** — Step-by-step instructions to add Impact Nova to a project (npm install, CSS, font, i18n, Tailwind).
- **Migration from Impact UI** — Full migration guide (phases, component mapping, subpath imports, patterns); impact-ui-mcp-server optional during migration.
- **Designer/Figma** — Export tokens and component specs for design tools.
- **Match a screenshot to components** — Describe a UI (or share a screenshot); get suggested Impact Nova components to build it.
- **AG Grid / DataTable** — For grids and data tables: mandatory rules (AG Grid docs and API only; no deviation). When **ag-mcp** is installed, this MCP collaborates with it: use ag-mcp for AG Grid API/docs, impact-nova-mcp for DataTable wrappers and cell renderers. See resource `impact-nova://ag-grid-rules` and `impact-nova://tool-guide`.
- **Command Palette & keyboard shortcuts** — ⌘K palette and shortcut system; implementation is more involved. Dedicated step-by-step guide: resource `impact-nova://command-palette` (provider, useShortcut/useGlobalShortcut, scopes, multi-table, ShortcutSettings, Kbd). Use `get_real_world_patterns` with `topic: "command-palette"` for the pattern summary.
- **Keyboard shortcuts best practices** — Critical implementation patterns learned from production use:
  - **Scope hierarchy**: `global` (0) < `module` (1) < `page` (2) < `modal` (3) — page scope beats global scope
  - **Avoid browser conflicts**: Never use `Ctrl+Tab`, `Cmd+T`, `Cmd+W` — they're reserved by browsers
  - **Use page-scoped shortcuts**: For tab navigation, use `Option+Arrow` keys instead of browser shortcuts
  - **State synchronization**: Ensure shortcuts and UI share the same state instance (avoid duplicate state)
  - **Defensive programming**: Add null checks for tabs/data that may not be loaded yet
  - **Debug logging**: Use console.log during development to verify shortcut registration and state updates

## Install

No separate install is needed. You add the MCP server in your IDE config (below) using `npx`; the first time the IDE starts the server, it will run `impact-nova-mcp` from npm automatically.

## Configure your IDE

Use the config below for your editor. The server runs over **stdio** (subprocess). You only need to add one JSON block; if you already have other MCP servers, add the `"impact-nova"` entry inside the existing `mcpServers` object.

### Cursor

1. **Open MCP settings**
   - **Mac:** `Cmd + Shift + P` → type **MCP** → choose **"Cursor Settings: Open MCP"** (or **"View: Open MCP Settings"**).
   - **Windows/Linux:** `Ctrl + Shift + P` → same steps.
   - This opens your MCP config file. If it doesn't exist, Cursor will create it when you save.

2. **Config file location**
   - **Global (all projects):** `~/.cursor/mcp.json`
   - **This project only:** `.cursor/mcp.json` in your project root (commit this to share with the team).

3. **Paste this config** (use exactly this; no need to run `npm install` first):

```json
{
  "mcpServers": {
    "impact-nova": {
      "command": "npx",
      "args": ["-y", "impact-nova-mcp"]
    }
  }
}
```

If you already have other servers, the file might look like `{ "mcpServers": { "other-server": { ... } } }`. Add a comma after the last server and add the `"impact-nova": { ... }` block above.

4. **Save the file** (e.g. `Cmd + S` / `Ctrl + S`).

5. **Restart Cursor** (or reload the window: Command Palette → "Developer: Reload Window") so the new MCP server is loaded.

6. **Check it works** — In the chat, the Impact Nova tools/resources should appear when the AI uses MCP.

### Windsurf

1. **Open MCP config**
   - In Windsurf, click the **MCPs** icon in the top-right of the **Cascade** panel (the AI panel), then click **Configure**.
   - Or open the config file directly (see path below).

2. **Config file location**
   - **macOS / Linux:** `~/.codeium/windsurf/mcp_config.json`
   - **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
     If the file or folder doesn't exist, create the folder (e.g. `.codeium/windsurf` in your user home) and create `mcp_config.json` there.

3. **Paste this config** (use exactly this; no install needed):

```json
{
  "mcpServers": {
    "impact-nova": {
      "command": "npx",
      "args": ["-y", "impact-nova-mcp"]
    }
  }
}
```

If you already have other servers, add a comma after the last one and add the `"impact-nova": { ... }` block. Ensure the file is valid JSON (commas between entries, no trailing comma after the last one).

4. **Save the file.**

5. **Restart Windsurf** so it picks up the new server.

6. **Check it works** — The Impact Nova MCP tools/resources should be available when the AI runs.

### Claude (Desktop & Claude Code)

#### Claude Desktop

1. **Open the MCP config**
   - **macOS:** **Claude** menu → **Settings** → **Developer** → **Edit Config**, or edit `~/Library/Application Support/Claude/claude_desktop_config.json`.
   - **Windows:** **File** → **Settings** → **Developer** → **Edit Config**, or edit `%APPDATA%\Claude\claude_desktop_config.json`.
   - **Linux:** Edit `~/.config/Claude/claude_desktop_config.json` (create the `Claude` folder if needed).

2. **Paste this config** (merge into the existing `mcpServers` object if you already have other servers):

```json
{
  "mcpServers": {
    "impact-nova": {
      "command": "npx",
      "args": ["-y", "impact-nova-mcp"]
    }
  }
}
```

3. **Save the file** and **fully quit and restart Claude Desktop** (MCP changes are not hot-reloaded).

4. **Check it works** — In a new chat, the Impact Nova tools/resources should be available when the model uses MCP.

#### Claude Code

Claude Code reads MCP from a JSON file with the same `mcpServers` shape. Typical locations:

- **User (all projects):** `~/.claude/mcp.json`
- **Project only:** `.mcp.json` in the repository root (good for sharing with the team)

Add the same `"impact-nova": { "command": "npx", "args": ["-y", "impact-nova-mcp"] }` entry under `mcpServers`. You can also use `claude mcp add` for stdio servers; see Anthropic’s [Connect Claude Code to tools via MCP](https://docs.anthropic.com/en/docs/claude-code/mcp) for the latest options and paths.

### Antigravity (Google)

1. Open **Antigravity** and open the **Agent Panel** (where you chat with the AI).
2. Click the **three-dot menu (⋯)** in the top right of the Agent Panel.
3. Choose **Manage MCP Servers** (or open the MCP Store).
4. Click **View raw config** to open your MCP config file (`mcp_config.json`).
5. Add the `impact-nova` server to the `mcpServers` object. Your config should look like this:

```json
{
  "mcpServers": {
    "impact-nova": {
      "command": "npx",
      "args": ["-y", "impact-nova-mcp"]
    }
  }
}
```

If you already have other servers, only add the `"impact-nova": { ... }` entry inside `mcpServers`. Save the file.

6. Restart or refresh the MCP connection (e.g. refresh in Manage MCP Servers) so Antigravity picks up the new server.

**Config file location:** The raw config is opened from the UI (View raw config). Project-level config may use `.vscode/mcp.json`. See your Antigravity or IDE docs for the exact path.

## Tools

### Registry & discovery

| Tool | Description |
|------|-------------|
| `query_components` | Filter components by capability, `ssrSupport`, `rscCompatibility`, `bundleTier`, category. |
| `get_component_props` | Lightweight props + runtime lookup — prefer over full `get_component`. |
| `get_component` | Full spec for one component (import, variants, subcomponents, usage). |
| `list_components` | Legacy flat list — prefer `query_components`. |
| `get_capabilities` | Capability → component id index from registry. |
| `get_deprecations` | Global and per-component deprecated prop aliases (`isError` → `error`). |
| `query_patterns` | Search composite UI patterns (dashboard, filter+table, wizard). |
| `query_recipes` | Scaffold recipe-linked patterns (6 create-impact-nova recipes). |
| `suggest_components_for_ui` | Match UI/screenshot description to Impact Nova components. |

### Code generation & validation

| Tool | Description |
|------|-------------|
| `validate_snippet` | **Canonical** — validate imports, AST charter checks, design-system compliance. |
| `validate_usage` | Legacy alias for `validate_snippet`. |
| `generate_component` | Generate React/TSX usage for a component with variant/size props. |
| `generate_page` | Generate a page/section with layout, components, i18n, and a11y notes. |
| `create_cursor_rules` | Emit AGENTS.md-style Cursor rules from registry. |

### Project setup & patterns

| Tool | Description |
|------|-------------|
| `scaffold_impact_nova_app` | Scaffold Vite + Impact Nova app (Layout, recipes, DataTable). Prefer over manual setup. |
| `interpret_user_request` | Detect persona (product/designer/frontend/…) and return recommended tool order. |
| `analyze_project_for_impact_nova` | Pass `package.json` content; get install commands and version recommendations. |
| `get_installation_and_config` | Step-by-step install and config (npm, CSS, providers, Tailwind). |
| `get_real_world_patterns` | Subpath imports, compound patterns (FilterPanel, DataTable, Sheet, Chart). |
| `get_design_tokens` | Design tokens (colors, radius, spacing, typography). |
| `search_best_practices` | Search best practices and do's/don'ts. |
| `export_tokens` | Export tokens for design tools (e.g. Figma). |
| `get_component_spec_for_design` | Design-oriented spec: variants, visual props, token mapping. |

### Consumer CI

Run **`npx impact-nova-doctor`** (bundled with this package) to scan consumer repos for mandate violations. Use `--diff origin/main` in CI.

## Resources

| URI                                 | Description                                                                                                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `impact-nova://catalog`             | Component catalog (JSON).                                                                                                                                                                  |
| `impact-nova://tokens`              | Design tokens (JSON).                                                                                                                                                                      |
| `impact-nova://best-practices`      | Best practices & do's/don'ts (Markdown).                                                                                                                                                   |
| `impact-nova://accessibility`       | Optional a11y guidance: labels, keyboard, focus (Markdown). Not required.                                                                                                                  |
| `impact-nova://troubleshooting`     | Common issues: dual React/AG Grid, styles, font, Chart path, license, i18n (Markdown).                                                                                                     |
| `impact-nova://i18n`                | i18n message keys and components (Markdown).                                                                                                                                               |
| `impact-nova://install`             | Installation & configuration steps (Markdown).                                                                                                                                             |
| `impact-nova://migration`           | Migration guide from Impact UI to Impact Nova: phases, component mapping, imports, compound patterns, verification. Use with impact-ui-mcp-server during migration.                        |
| `impact-nova://examples`            | Example snippets (Markdown).                                                                                                                                                               |
| `impact-nova://real-world-patterns` | Real-world patterns: subpath imports, types, compound patterns, Vite (Markdown).                                                                                                           |
| `impact-nova://ag-grid-rules`       | **Mandatory** AG Grid rules: use only AG Grid docs, only recommended patterns, only AG Grid API; collaborate with ag-mcp when installed (Markdown).                                        |
| `impact-nova://tool-guide`          | When to use which tool: quick reference for components, patterns, AG Grid/DataTable, installation, validation (Markdown).                                                                  |
| `impact-nova://layout`     | **Dashboard layout** — Vite scaffold with Layout, Sidebar, Header, Breadcrumb, FilterStrip (Markdown). |
| `impact-nova://command-palette`     | Command Palette & keyboard shortcuts: step-by-step implementation guide (⌘K, useShortcut, scopes, ShortcutSettings, Kbd). Use when implementing command palette or shortcuts.              |
| `impact-nova://keyboard-shortcuts`  | **NEW** Critical production best practices: scope hierarchy, browser conflicts, state synchronization, defensive programming, debugging. Real-world examples and implementation checklist. |

## Prompts

| Prompt                                           | Description                                                                             |
| ------------------------------------------------ | --------------------------------------------------------------------------------------- |
| **Scaffold Impact Nova app** | Calls `scaffold_impact_nova_app` — full runnable Vite project. |
| **Generate a page**                              | Template for generating a full page with Impact Nova layout and conventions.            |
| **Generate a form**                              | Template for forms (inputs, validation, i18n).                                          |
| **Generate a dashboard section**                 | Template for data tables, filters, charts.                                              |
| **Suggest components for this UI or screenshot** | Describe (or paste) a UI; get component suggestions.                                    |
| **Implement keyboard shortcuts**                 | Generate shortcuts with proper scope hierarchy, state sync, browser conflict avoidance. |

## Matching a screenshot to components

When you share a **screenshot** or describe a UI (e.g. "settings page with form and save button", "dashboard with sidebar, header, data table and filters"), the AI can:

1. **See the image** (in Cursor, Windsurf, Claude, or Antigravity the model can see attached screenshots when supported).
2. **Call `suggest_components_for_ui`** with a short description of what’s in the UI (and optionally key elements like `["sidebar", "table", "filters"]`).
3. **Get suggested components** — the tool matches your description to Impact Nova components using visual hints and "use when" keywords (e.g. modal → Dialog, data grid → DataTable, sidebar nav → Sidebar).

Then use `get_component` for any suggested component to get the full spec and code. This makes the MCP powerful enough to **match a screenshot and decide which components to use**.

## Example: "Install Impact Nova and configure it"

When the user says _"Install impact-nova"_ or _"Configure impact-nova for this project"_:

1. **Read the project's `package.json`** (the AI has access to the workspace).
2. **Call `analyze_project_for_impact_nova`** with the file content. The tool returns what's already installed, what to install (impact-nova, react ^19, react-dom ^19, optional ag-grid/highcharts), **recommended versions**, and exact `npm install` commands. It also flags if React needs upgrading to 19.
3. **Call `get_installation_and_config`** (or read `impact-nova://install`) for CSS import, Manrope font, i18n provider, and optional Tailwind preset.
4. The AI can then run the suggested `npm install` and apply the config steps (add CSS import, wrap with `ImpactNovaProviders` from `impact-nova/form`, etc.).

So the MCP can **see the user's package.json and suggest exactly what versions they need and what to install** before guiding them through configuration.

## Conventions (summary)

- **Use Impact Nova components only** — When using impact-nova, use the components provided by the design system; it has everything you need. Don't create new custom components for standard UI—use `query_components` / `get_component_props` to find and use what's available.
- **No unnecessary classNames** — Components are pre-styled; use `variant` and `size` props for appearance. Use `className` only for layout (e.g. `mt-4`, `gap-2`) or overrides.
- Use **compound components** (e.g. `Dialog.Content`, `Card.Header`).
- Use **design tokens** (Tailwind theme classes), not arbitrary values.
- Use **i18n** for user-facing strings (`useImpactNovaI18n` / `t()` or prop overrides).

## Links

- [Impact Nova](https://github.com/insideinsight/impact-nova#readme) — Design system repo and docs.

## Publishing (maintainers)

The package is published to npm as **`impact-nova-mcp`**.

### Alpha release (recommended first)

Publish **both** packages on the `alpha` dist-tag:

```bash
# From repo root — design system
npm run build:registry
npm run validate:mcp-sync
npm run build
npm run publish:alpha

# MCP server (aligned version)
cd packages/mcp
npm run build
npm run publish:alpha
```

Consumers pin alpha:

```bash
npm install impact-nova@alpha impact-nova-mcp@alpha
```

MCP config:

```json
{
  "mcpServers": {
    "impact-nova": {
      "command": "npx",
      "args": ["-y", "impact-nova-mcp@alpha"]
    }
  }
}
```

**Pre-publish checklist:**

1. `npm run build:registry` from repo root (syncs `packages/mcp/data`)
2. `npm run validate:mcp-sync` passes
3. `cd packages/mcp && npm run build && npm run typecheck`
4. `create-impact-nova@^1.4.9` is on npm (scaffold tool dependency; pins `impact-nova@^2.5.10` + AG Grid `36.0.1`)

### Stable release

```bash
cd packages/mcp
npm run build
npm publish --access public
```

`package.json` includes `prepublishOnly: "npm run build"` so publish always rebuilds `dist/` and copies `data/`.

## License

MIT.