spotlight-mcp

An MCP (Model Context Protocol) server that exposes the Spotlight Design System (@castandcrew/platform-ui) to AI tools like Claude. It allows Claude to look up component props, design tokens, usage guidelines, MUI migration paths, and design rules — without hallucinating APIs that don't exist.

What it does

When connected to Claude Code (or any MCP-compatible client), spotlight-mcp gives Claude access to 10 tools. ask_spotlight is the front door — one call routes across components, guidance, tokens, classes, and migration, so the client doesn't have to orchestrate several lookups. The rest are precise follow-ups.

| Tool | What Claude can ask | |------|---------------------| | ask_spotlight | "How should I label and place buttons?" — one-call answer context | | get_component | "What props does AutocompleteInput have?" | | search_components | "What components exist for date input?" | | get_token | "What is the value of --space-md?" | | search_tokens | "What tokens exist for spacing?" | | search_utility_classes | "What's the CSS class for body text?" | | get_migration_guide | "How do I migrate from MUI Button?" | | get_pattern | "When should I use Modal vs Drawer?" | | validate_usage | "Is this JSX correct per Spotlight rules?" | | list_deprecated | "What components should I avoid?" |

All data comes from a static data/index.json file — no network calls, no AI inside the server. The index has two sources, both merged by the indexer:

• Derived — components, props, tokens, utility classes, and rules parsed automatically from the @castandcrew/platform-ui source repo.
• Hand-authored — selection/decision guidance, code recipes, migration guides, icon and layout references, and motion docs in content/. This is the canonical home for Spotlight design knowledge being migrated off the spotlight-knowledge Claude Code plugin (which the MCP is intended to replace).

Getting it running

Not yet published to npm — run it from source (takes about a minute). Prerequisites: Node 18+ and pnpm.

git clone https://github.com/cast-and-crew/spotlight-mcp.git
cd spotlight-mcp
pnpm install        # installs deps and builds dist/ via the prepare script
pnpm build          # re-compile src/ → dist/ if needed

Connect it to Claude Code (recommended)

Register the built server at user scope (available in every project):

claude mcp add spotlight --scope user -- node "$(pwd)/dist/index.js"

Start a new Claude Code session — the 10 tools appear. They're all read-only lookups, so auto-approve them to avoid per-call prompts: run /permissions and add mcp__spotlight, or choose "don't ask again" on the first prompt.

Then just ask — e.g. "Using spotlight, when should I use a Modal vs a Drawer?" or "what color token for a critical background?". ask_spotlight is the one-call front door; the other tools are precise follow-ups.

Verify it's working:

./scripts/smoke.sh   # boots the server, lists tools, runs a few real calls
pnpm test            # full suite (index integrity, tool calls, content merge)

Other clients

• MCP Inspector (GUI to poke at tools): npx @modelcontextprotocol/inspector node dist/index.js
• HTTP (Claude.ai, custom integrations): pnpm start:http (or PORT=8080 pnpm start:http)
  • POST /mcp — Streamable HTTP (recommended) · GET /sse + POST /messages — SSE legacy · GET /health

Once published to npm

claude mcp add spotlight -- npx -y @castandcrew/spotlight-mcp

(or the equivalent mcpServers entry in settings). Consumers then get updates automatically on each npx invocation — no cloning.

Development

After pnpm install (see Getting it running):

pnpm dev:stdio    # run from source in stdio mode (tsx, no build step)
pnpm dev:http     # run from source in HTTP mode
pnpm build        # compile src/ → dist/
pnpm start        # run the built server (stdio)
pnpm test         # run the vitest suite

Testing

Three layers, fastest first. Build first with pnpm build.

# 1. stdio smoke test — boots the server, lists tools, runs a few real calls
pnpm build && ./scripts/smoke.sh

# 2. automated suite (21 checks: index integrity, end-to-end tool calls, manual-merge)
pnpm test

# 3. MCP Inspector — a GUI to invoke any tool with arbitrary arguments
npx @modelcontextprotocol/inspector node dist/index.js

Live in Claude Code (the real test). Register the built server, then ask design questions and watch Claude call the tools:

claude mcp add spotlight -- node "$(pwd)/dist/index.js"

Then ask things like "should I use a Modal or a Drawer for a confirmation?", "what props does Button take?", "how do I migrate a MUI Select?". To compare against the old spotlight-knowledge plugin fairly, disable that plugin first — otherwise you can't tell which source answered.

See docs/TESTING.md for details.

Updating the index

The data/index.json file is the source of truth for all MCP tools. The indexer parses the @castandcrew/platform-ui source repo and merges the hand-authored content/ folder into a single index.

Run the indexer

# Pass the repo root — the Nx monorepo layout is auto-detected
pnpm index /path/to/common-ui-component-library

The indexer auto-detects the monorepo: it reads component/token source from packages/platform-ui/src (falling back to src/ for older checkouts) and docs from the repo-root docs/. It reads:

| Source | What it extracts | |--------|-----------------| | packages/platform-ui/src/{category}/{Component}/types.ts | Props, types, JSDoc, defaults (MUI re-exports annotated propsSource: "mui") | | …/{Component}/index.tsx (or index.ts) | Component description, deprecation status | | …/{Component}/*.stories.tsx | Story names and Storybook URLs | | …/{Component}/*.module.css | Which design tokens each component uses | | …/Foundations/token-directory/outputs/token-dictionary.json | Design tokens | | …/Foundations/token-directory/outputs/class-dictionary.json | CSS utility classes | | docs/{category}/{Component}.md | whenToUse, whenNotToUse, examples, MUI migration notes | | docs/SPOTLIGHT_RULES.md, docs/rules/ | Rules (forbidden/allowed components, conventions) | | guides/*.md | Long-form usage patterns | | content/** (this repo) | Hand-authored patterns, component overrides, and rules |

After running the indexer, commit the refreshed data/index.json and restart the MCP server.

Current index coverage (last run: 2026-06-15)

| Metric | Count | |--------|-------| | Components | 105 (13 categories) | | Components with props | 53 (+18 annotated as MUI re-exports) | | Components with whenToUse | 41 | | Components with stories | 85 | | Patterns | 75 (selection 23, recipe 12, reference 8, migration 8, guide 8, rules 5, layout 5, icon 4, overview 2) | | Design tokens | 329 (light theme) | | Utility classes | 218 | | Rules | 9 | | MUI migration entries | 25 | | Deprecated entries | 20 |

Historical coverage gaps (pre-monorepo) are tracked in platform-ui-gaps.md.

Architecture

spotlight-mcp/
├── src/
│   ├── index.ts              # Entry point — parses --http / --stdio flag
│   ├── server.ts             # Creates McpServer and registers all tools
│   ├── types.ts              # TypeScript types for index.json schema
│   ├── data/
│   │   └── loader.ts         # Reads and caches data/index.json at runtime
│   ├── tools/                # One file per MCP tool
│   │   ├── ask_spotlight.ts        # single-call front door (routes across all data)
│   │   ├── get_component.ts
│   │   ├── search_components.ts
│   │   ├── get_token.ts
│   │   ├── search_tokens.ts
│   │   ├── search_utility_classes.ts
│   │   ├── get_migration_guide.ts
│   │   ├── get_pattern.ts
│   │   ├── validate_usage.ts
│   │   └── list_deprecated.ts
│   └── transports/
│       ├── stdio.ts          # stdio transport (Claude Code, CLI tools)
│       └── http.ts           # Streamable HTTP + SSE legacy
├── content/                  # Hand-authored knowledge merged into the index
│   ├── patterns/             # selection & decision guides, motion
│   ├── recipes/              # reusable UI code recipes
│   ├── reference/            # critical-rules, token usage, conventions
│   ├── icons/  layout/  migration/  overview/
│   ├── components/           # per-component usage overrides
│   └── rules/                # extra rules (frontmatter)
├── scripts/
│   ├── indexer.ts            # Generates data/index.json (derived + content/)
│   └── smoke.sh              # stdio smoke test
├── test/                     # vitest: index-integrity, tools, manual-merge
├── docs/
│   └── TESTING.md            # How to test (interactive + automated)
├── data/
│   └── index.json            # Generated index — this is what the server reads
└── platform-ui-gaps.md       # Historical (pre-monorepo) coverage gaps

How it connects to Claude

The MCP server does not call any AI. Claude calls it:

User question
     ↓
Claude (Anthropic) — reads tool descriptions, decides which to call
     ↓
spotlight-mcp server — looks up data/index.json
     ↓
Returns structured JSON to Claude
     ↓
Claude answers the user using real Spotlight data

The tool descriptions (the text in each server.tool(name, description, ...) call) are the only "bridge" between natural language and the server. Well-written descriptions = Claude uses the right tool at the right time.

Publishing

# Bump version
npm version patch   # or minor / major

# Publish to npm
pnpm publish

Users receive updates automatically on the next npx invocation.

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | HTTP server port (only in --http mode) | | SPOTLIGHT_INDEX_PATH | data/index.json (bundled) | Path to a custom index file |