@ikatec/nebula-mcp

MCP (Model Context Protocol) server for the Nebula Design System (@ikatec/nebula-react).

Lets AI coding agents (Claude Code, Cursor, Windsurf, Continue, etc.) discover Nebula's components, props, examples, and design tokens — so generated code stays aligned with the real library API instead of hallucinated props.

What it exposes

The server bundles a frozen snapshot of the design system (built from packages/react, packages/tokens, and packages/docs at release time) and exposes it through these MCP tools:

| Tool | Purpose | | ----------------------- | -------------------------------------------------------------------------- | | nebula_overview | Snapshot metadata + project README. | | list_components | Every component with slug, exports and example count. | | get_component | Full reference for one component: source, MDX docs, stories, examples. | | get_component_examples | Just the curated Storybook example snippets for a component. | | get_component_props | Extracted interface / type / enum declarations from the source. | | list_design_tokens | Token categories (colors, space, radii, fonts, …) — optionally filtered. | | get_design_token | Raw source for one token category (e.g. colors, space, radii). | | list_hooks / get_hook | Custom React hooks shipped by Nebula. | | search_nebula | Free-text search across component source, MDX, stories and tokens. |

It also publishes one MCP resource per component (nebula://components/<slug>) plus a top-level nebula://overview resource, so clients that browse resources can render the design system as a navigable doc tree.

Install

npm install -D @ikatec/nebula-mcp
# or run on-demand without installing:
npx @ikatec/nebula-mcp

The server speaks MCP over stdio, which is the transport every major MCP-aware editor supports.

Configure your editor

Claude Code

Add an entry to ~/.claude.json (global) or .claude/settings.json (per-project):

{
  "mcpServers": {
    "nebula": {
      "command": "npx",
      "args": ["-y", "@ikatec/nebula-mcp"]
    }
  }
}

Or via the CLI:

claude mcp add nebula -- npx -y @ikatec/nebula-mcp

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "nebula": {
      "command": "npx",
      "args": ["-y", "@ikatec/nebula-mcp"]
    }
  }
}

Windsurf / Continue / Zed

Most editors share the same shape: command + args. Point them at npx -y @ikatec/nebula-mcp (or node node_modules/@ikatec/nebula-mcp/dist/server.js if you prefer a pinned install).

Suggested agent workflow

Tell your agent (or add to your project's CLAUDE.md / .cursorrules):

When writing UI code in this project, use the nebula MCP server:

1. Call list_components to see what's available.
2. Before importing a Nebula component, call get_component (or get_component_examples) to read its real props and usage examples.
3. For colors, spacing, radii, etc. call list_design_tokens and then get_design_token instead of guessing token names.

Development (inside this monorepo)

# regenerate the docs snapshot from packages/react + packages/tokens + packages/docs
npm run -w @ikatec/nebula-mcp build:data

# rebuild the server bundle
npm run -w @ikatec/nebula-mcp build

# run it locally to test
node packages/mcp/dist/server.js

The snapshot lives at packages/mcp/data/components.json and is committed-friendly: regenerated on every npm run build so consumers always get the docs that match the version of the library they installed.

How the snapshot is produced

scripts/build-data.ts walks the sibling packages and emits one JSON document containing, for each component:

• raw .tsx source
• the matching MDX page (if any)
• the matching *.stories.tsx file (if any)
• example code blocks extracted from parameters.docs.source.code in stories
• the list of exported symbols

…plus all token files (raw .ts source) and all custom hooks.

The server loads that JSON once on startup and answers tool calls from memory.

License

MIT