@castandcrew/spotlight-mcp 0.1.0

package/README.md

@@ -0,0 +1,265 @@
+# 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](#updating-the-index):
+
+- **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/`](./content/README.md). 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`.
+
+```bash
+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):
+
+```bash
+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:**
+
+```bash
+./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
+
+```bash
+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](#getting-it-running)):
+
+```bash
+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`.
+
+```bash
+# 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:
+
+```bash
+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`](./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/`](./content/README.md)
+folder into a single index.
+
+### Run the indexer
+
+```bash
+# 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`](./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
+
+```bash
+# 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 |