impact-nova-mcp

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

What it does

• Use Impact Nova components only — When using impact-nova, use the components in this design system; it has everything you need. No need to create new custom components—use list_components / get_component to find and use what's available.
• List components — Browse all Impact Nova components by category (Forms, Navigation, Feedback, Data).
• Get component specs — Import path, variants, sizes, subcomponents, and 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 usage — Check snippets for correct imports, token-based styling, i18n, and (for grid/chart) AG Grid / Highcharts guidance.
• 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, imports, patterns); use with impact-ui-mcp-server 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):

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

{
  "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.

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:

{
  "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

| Tool | Description | |------|-------------| | list_components | List all components with categories and descriptions. | | get_component | Full spec for one component (import, variants, subcomponents, usage). | | get_design_tokens | Design tokens (colors, radius, spacing, typography); optional filter by type. | | 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. | | search_best_practices | Search best practices and do's/don'ts (e.g. classNames, i18n, tokens). | | validate_usage | Validate a snippet (imports, tokens, compound components, i18n, unnecessary classNames). | | export_tokens | Export tokens for design tools (e.g. Figma). | | get_component_spec_for_design | Design-oriented spec: variants, visual props, token mapping. | | get_installation_and_config | Step-by-step install and config (npm, CSS, font, i18n, Tailwind). | | analyze_project_for_impact_nova | Pass the project's package.json content; get what to install (impact-nova, react, react-dom, optional ag-grid/highcharts), recommended versions, and exact npm install commands. Use when the user says "install impact-nova" or "configure impact-nova". | | suggest_components_for_ui | Suggest Impact Nova components from a UI/screenshot description (e.g. "dashboard with sidebar, table, filters"); includes real-world compound patterns. | | get_real_world_patterns | Subpath imports, type imports, compound patterns (FilterPanel+Strip, DataTable+AG Grid, Sheet, EmptyContainer), Vite dedupe, workarounds. |

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://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 | |--------|-------------| | 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, 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 ImpactNovaI18nProvider, 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 list_components / get_component 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 — Design system repo and docs.
• Figma library — Official Figma library.

Publishing (maintainers)

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

1. From repo root or packages/mcp: run npm run build (or it runs automatically on prepublishOnly).
2. Bump version in packages/mcp/package.json if needed.
3. From packages/mcp: npm publish (ensure you’re logged in: npm login).
   With a scope: npm publish --access public if needed.

package.json includes repository, homepage, bugs, publishConfig.access: "public", and prepublishOnly: "npm run build" so npm publish builds and publishes the right files.

License

MIT.