@castandcrew/spotlight-mcp 0.1.3 → 0.1.4

package/README.md

@@ -6,7 +6,7 @@ An MCP (Model Context Protocol) server that exposes the **Spotlight Design Syste
 
 ## 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.
+When connected to Claude Code (or any MCP-compatible client), `spotlight-mcp` gives Claude access to 12 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 |
 |------|---------------------|
@@ -35,8 +35,29 @@ server. The index has two sources, both merged by the [indexer](#updating-the-in
 
 ## Getting it running
 
-> **Not yet published to npm — run it from source** (takes about a minute).
-> **Prerequisites:** Node 18+ and `pnpm`.
+> **Run it from source. The npm package is not usable yet.**
+>
+> `@castandcrew/spotlight-mcp` does exist on npm (`npm view @castandcrew/spotlight-mcp version`
+> → `0.1.3`), but that publication is a **smoke test of the release pipeline, not a release**.
+> The tool is still in preliminary testing and nothing else has been published.
+>
+> Concretely, the published tarball ships a `data/index.json` containing **0 components,
+> 0 tokens and 0 utility classes** (only 103 patterns and 71 rules), so `search_components`,
+> `search_tokens`, `get_component`, `get_token` and `search_utility_classes` return nothing.
+> Verified 2026-09-08 by running `npx -y @castandcrew/spotlight-mcp` in an empty directory:
+> the server starts and lists all 12 tools, but has no component or token data behind them.
+>
+> **A fresh clone of this repo is fine.** `data/index.json` is committed with real data
+> (84 components, 329 tokens, 218 utility classes, 111 patterns, 71 rules; `generated:
+> 2026-09-01`), so `pnpm install && pnpm build` is enough to get a working server. Regenerate
+> it only when the upstream library changes — see [Updating the index](#updating-the-index).
+>
+> **If the index is ever empty, the server now says so.** It no longer answers `[]` as if the
+> design system were empty: each tool returns an explicit error naming the index path, the
+> counts it found and the command to fix it, and a status banner is written to stderr at
+> startup. See [When the index is empty](#when-the-index-is-empty).
+>
+> **Prerequisites (source):** Node 18+ and `pnpm`.
 
 ```bash
 git clone https://github.com/cast-and-crew/spotlight-mcp.git
@@ -53,7 +74,7 @@ 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
+Start a new Claude Code session — the **12 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.
 
@@ -68,20 +89,90 @@ other tools are precise follow-ups.
 pnpm test            # full suite (index integrity, tool calls, content merge)
 ```
 
+### Connect it to Claude Desktop
+
+Claude Desktop doesn't use the `claude mcp add` CLI — it reads local MCP servers from its own
+config file. Point it at the built server:
+
+**Via the UI:** Settings → Developer → Local MCP servers → **Edit config**.
+
+**Or edit the file directly** (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "spotlight": {
+      "command": "node",
+      "args": ["/absolute/path/to/spotlight-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Settings → Developer → Local MCP servers should show `spotlight` as
+**running**.
+
+**Verify it's working:**
+
+```bash
+ps aux | grep spotlight-mcp                             # confirms the process is alive
+tail -f ~/Library/Logs/Claude/mcp-server-spotlight.log   # confirms the handshake succeeded
+```
+
+Look for `"Server started and connected successfully"` with no error after it.
+
+> **Scope:** this config covers Claude Desktop's **Chat** and **Cowork**. The **Code Tab** is
+> Claude Code and reads Claude Code's own config (`~/.claude.json`) — register the server there
+> with `claude mcp add` (section above) or install the `spotlight-cowork` plugin, which bundles it.
+> `mcp-server-spotlight.log` only records Chat's server process; Cowork calls show up as
+> permission requests in `~/Library/Logs/Claude/main.log` and in the session transcript.
+> (An earlier draft of this README claimed the Code Tab could not reach the server; that was a
+> misconfigured path in `~/.claude.json`, not a limitation — verified in SPT-1526 v2, 2026-09-08.)
+
 ### 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
+### Via npm — ⚠️ not usable yet
+
+**Do not point a client at the npm package expecting it to work.** `npx -y @castandcrew/spotlight-mcp`
+resolves and starts (0.1.3 is on npm), but it serves an index with **0 components and 0 tokens** —
+that publication was a pipeline smoke test while the tool is still in preliminary testing.
+
+This matters beyond this repo: **six** plugins declare `npx -y @castandcrew/spotlight-mcp` in
+their `.mcp.json` — `spotlight-cowork`, `spotlight-remediation`, `spotlight-advisor`,
+`spotlight-patterns`, `repo-spec` and `spotlight-design` — and around a dozen guides in
+`claude-plugins` tell users to run `claude mcp add … npx -y @castandcrew/spotlight-mcp`
+(`spotlight-remediation/skills/project-setup` runs it automatically). Until a real release ships,
+use the from-source setup above.
+
+Note that 0.1.3 predates the guard described below, so it still answers `[]` silently rather than
+erroring — the guard only protects setups running a build from this repo.
+
+The commands below are kept for when the package is genuinely released.
+
+**Claude Code:**
 
 ```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.
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "spotlight": {
+      "command": "npx",
+      "args": ["-y", "@castandcrew/spotlight-mcp"]
+    }
+  }
+}
+```
+
+Same config works on any machine — no absolute path, no local checkout required.
 
 ---
 
@@ -162,20 +253,50 @@ repo-root `docs/`. It reads:
 
 After running the indexer, commit the refreshed `data/index.json` and restart the MCP server.
 
-### Current index coverage (last run: 2026-06-15)
+**The indexer refuses to write an index that is missing derived data.** If `components`, `tokens`,
+`utilityClasses`, `patterns` or `rules` would come out empty, it prints what it resolved and why
+each collection is empty, and leaves the existing `data/index.json` untouched. Override with
+`--allow-empty` if you really need the file written — but do not commit the result.
+
+This matters because `patterns` and `rules` are mostly merged from this repo's own `content/`,
+so they stay populated even when the source path is wrong. An index generated against a bad path
+looks plausible (`patterns: 95, rules: 63`) while being useless. That is how the empty 0.1.3
+index shipped.
+
+### When the index is empty
+
+The server never answers `[]` as if the design system had no such component. Two failure classes:
+
+- **Unusable** — the index file is missing, unreadable, not JSON, or not shaped like an index.
+  `loadIndex()` throws, so every tool returns an error.
+- **Degraded** — the index parses but some collections are empty. Only the tools that need the
+  missing data error; the rest keep working. With the 0.1.3 index, for example, `get_pattern`,
+  `get_recipe` and `identify_pattern` still answer correctly from the 103 patterns it did have.
+
+Either way a status banner goes to **stderr** at startup (visible in
+`~/Library/Logs/Claude/mcp-server-spotlight.log` for Claude Desktop), `GET /health` reports
+per-collection counts in HTTP mode, and each failing tool returns a JSON error naming the resolved
+index path, the counts found, the `generated` date and the command to fix it. The server does not
+exit — a dead server tells the model nothing.
+
+Tools guard only on what they read: `validate_usage`, for instance, requires both `rules` **and**
+`components`, because its deprecated-component check reads `deprecated`, which the indexer derives
+from `components`. With 0 components it would otherwise report `valid: true` for any snippet.
+
+### Current index coverage (`generated: 2026-09-01`)
 
 | 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) |
+| Components | 84 (11 categories) |
+| Components with props | 52 (all parsed locally — no MUI re-exports in the current index) |
+| Components with `usage.whenToUse` | 39 (`whenNotToUse` 42, `examples` 19) |
+| Components with stories | 70 |
+| Patterns | 111 (selection 41, recipe 26, guide 11, reference 9, migration 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 |
+| Rules | 71 |
+| MUI migration entries | 24 |
+| Deprecated entries | 0 (nothing is deprecated upstream today) |
 
 Historical coverage gaps (pre-monorepo) are tracked in [`platform-ui-gaps.md`](./platform-ui-gaps.md).