@castandcrew/spotlight-mcp 0.1.3 → 0.1.5

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,23 @@ 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`.
+> **Use `@castandcrew/spotlight-mcp` `0.1.4` or later.** Earlier npm versions (`0.1.0`–`0.1.3`)
+> ship an empty index (0 components, 0 tokens, 0 utility classes), so `search_components`,
+> `get_component`, `search_tokens`, `get_token` and `search_utility_classes` return nothing.
+> Do not use them. `0.1.4` is the first release with a populated `data/index.json`:
+> 169 entries (165 unique component names), 329 tokens, 218 utility classes, 111 patterns and
+> 71 rules. See [Via npm](#via-npm) to connect it without cloning anything.
+>
+> **You can also run it from source.** A fresh clone is fine: `data/index.json` is committed
+> with real data, 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 says so.** It does not answer `[]` 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 +68,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 +83,89 @@ 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**. 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` records Chat's server process. (Claude Desktop merged Cowork into
+> Chat — Cowork capabilities live in the same conversation now, there is no separate Cowork
+> option; the `spotlight-cowork` plugin keeps its name.)
+> (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`
+  - The HTTP server has **no authentication** and accepts requests from any origin (CORS is open so browser clients can connect). Run it only on a trusted network; the network boundary is the protection.
+
+### Via npm
 
-### Once published to npm
+`0.1.4` or later is required. `npx -y @castandcrew/spotlight-mcp` downloads and starts the
+server; it ships the full index, so no clone or build is needed. Pin a version range so a
+future release cannot change your setup unannounced, for example
+`@castandcrew/spotlight-mcp@0.1.4` (exact) or `@castandcrew/spotlight-mcp@~0.1.4` (patch
+updates only).
+
+Versions `0.1.0`–`0.1.3` (including the `0.1.3` pipeline smoke test) have an empty index and
+predate the empty-index guard described below. Do not use them.
+
+The plugins in `claude-plugins` (`spotlight-cowork`, `spotlight-remediation`,
+`spotlight-advisor`, `spotlight-patterns`, `repo-spec` and `spotlight-design`) start the server
+through `npx -y @castandcrew/spotlight-mcp` in their `.mcp.json`.
+
+**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 +246,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).
 
@@ -217,7 +331,8 @@ spotlight-mcp/
 │   └── smoke.sh              # stdio smoke test
 ├── test/                     # vitest: index-integrity, tools, manual-merge
 ├── docs/
-│   └── TESTING.md            # How to test (interactive + automated)
+│   ├── TESTING.md            # How to test (interactive + automated)
+│   └── RELEASING.md          # Branching, versioning, release runbook
 ├── data/
 │   └── index.json            # Generated index — this is what the server reads
 └── platform-ui-gaps.md       # Historical (pre-monorepo) coverage gaps
@@ -245,15 +360,15 @@ The tool descriptions (the text in each `server.tool(name, description, ...)` ca
 
 ## Publishing
 
-```bash
-# Bump version
-npm version patch   # or minor / major
+Releases are tagged on `main` and staged on npm by the **Release** GitHub workflow; a maintainer
+approves the staged version in npm. **Do not run `npm publish` / `pnpm publish` from a laptop:** it
+skips the checks that stop an empty index from shipping (that is how `0.1.3` went out).
 
-# Publish to npm
-pnpm publish
-```
+Branching, versioning rules, the step-by-step release runbook and rollback are in
+[`docs/RELEASING.md`](./docs/RELEASING.md).
 
-Users receive updates automatically on the next `npx` invocation.
+Clients that run `npx -y @castandcrew/spotlight-mcp` (without a pinned version) get the latest
+release on the next start; pin a range (see [Via npm](#via-npm)) to avoid that.
 
 ---