@castandcrew/spotlight-mcp 0.1.4 → 0.1.5

package/README.md

@@ -35,27 +35,21 @@ server. The index has two sources, both merged by the [indexer](#updating-the-in
 
 ## Getting it running
 
-> **Run it from source. The npm package is not usable yet.**
+> **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.
 >
-> `@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
+> **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 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).
+> **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`.
 
@@ -121,11 +115,12 @@ tail -f ~/Library/Logs/Claude/mcp-server-spotlight.log   # confirms the handshak
 
 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
+> **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` only records Chat's server process; Cowork calls show up as
-> permission requests in `~/Library/Logs/Claude/main.log` and in the session transcript.
+> `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.)
 
@@ -134,24 +129,22 @@ Look for `"Server started and connected successfully"` with no error after it.
 - **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 — ⚠️ 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.
+### Via npm
 
-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.
+`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).
 
-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.
+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 commands below are kept for when the package is genuinely released.
+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:**
 
@@ -338,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
@@ -366,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.
 
 ---