chore: release 0.4.7 — multi-client install docs + npm-publish AAA descriptions (#84)

## Summary

- **README install section** expanded to cover every major MCP client:
Claude Code, Claude Desktop, Gemini CLI, GitHub Copilot (VS Code),
Cursor, Cline, Windsurf, Continue.dev, Zed, plus a generic stdio
template.
- **Runtime docs corrected** — clone-and-configure path lists Deno
(preferred per CLAUDE.md policy), Bun, and Node as valid runtimes.
Dropped the spurious `npm install` step (zero-dep package).
- **Version bump** 0.4.6 → 0.4.7 in `package.json`,
`gemini-extension.json`, `jsr.json`, `stapeln.toml`.

## Why this release matters for Glama

The AAA-tier tool-description rewrite landed in `25887157` / `ad837abe`
after **0.4.1**, but was never `npm publish`'d. Glama runs the npm
package, so it scored the v0.4.1 stub descriptions ("Check BoJ server
health status") and graded Quality C.

Publishing 0.4.7 ships the rich Purpose / Behavior / Returns / Errors /
Usage text and per-parameter `description` fields with patterns/enums.
After Glama's next scan, Quality should land A.

## Test plan

- [ ] CI green (dogfood-gate, hypatia-scan, codeql, etc.)
- [ ] Tag `v0.4.7` after merge → triggers
`.github/workflows/publish.yml` (npm + JSR)
- [ ] Verify `npm view @hyperpolymath/boj-server@latest version` returns
`0.4.7`
- [ ] Trigger Glama re-scan via dashboard
- [ ] Confirm Quality grade moves C → A on Glama

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

CHANGELOG.md

@@ -3,6 +3,28 @@
 
 All notable changes to Bundle of Joy Server are documented here.
 
+## [0.4.7] — 2026-05-20
+
+### Changed
+
+- **README install section expanded** to cover every major MCP client: Claude Code,
+  Claude Desktop, Gemini CLI, GitHub Copilot (VS Code), Cursor, Cline, Windsurf,
+  Continue.dev, Zed, plus a generic stdio template. Copy-paste-ready snippets
+  for each client's config-file path.
+- **Runtime documentation corrected**: clone-and-configure path now lists Deno
+  (preferred per CLAUDE.md policy), Bun, and Node as equally valid runtimes for
+  `mcp-bridge/main.js`. Spurious `npm install` step removed — `package.json`
+  declares zero runtime dependencies, so no install is ever required.
+
+### Notes
+
+- This is the release that publishes the **AAA-tier tool descriptions** to npm.
+  The description rewrite landed in `25887157` / `ad837abe` after 0.4.1 but was
+  never npm-published; downstream MCP clients (and Glama's quality scoring)
+  were running 0.4.1 with the older one-liner descriptions. Republishing as
+  0.4.7 ships the rich Purpose / Behavior / Returns / Errors / Usage text on
+  every tool and the per-parameter `description` fields with patterns/enums.
+
 ## [Unreleased]
 
 ### Added

README.md

@@ -8,21 +8,190 @@ BoJ (Bundle of Joy) is a unified MCP server that consolidates all hyperpolymath
 
 ## Install
 
-Add to Claude Code:
+BoJ ships as an MCP server over stdio. Every snippet below uses the published npm package; replace `npx -y @hyperpolymath/boj-server@latest` with one of the following from a local clone:
+
+```bash
+# Preferred — Deno (no install step; fetches imports on first run)
+deno run -A /path/to/boj-server/mcp-bridge/main.js
+
+# Bun (also zero-install)
+bun /path/to/boj-server/mcp-bridge/main.js
+
+# Node — works, but Deno is the project's documented runtime
+node /path/to/boj-server/mcp-bridge/main.js
+```
+
+The bridge has **zero runtime dependencies** (see `package.json`) so no install step is ever required, regardless of runtime.
+
+Most cartridges require the BoJ REST backend running on `http://localhost:7700` — see [Backend](#backend) below.
+
+### Claude Code (CLI)
 
 ```bash
 claude mcp add boj-server -- npx -y @hyperpolymath/boj-server@latest
 ```
 
-Or clone and configure:
+### Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "boj-server": {
+      "command": "npx",
+      "args": ["-y", "@hyperpolymath/boj-server@latest"],
+      "env": { "BOJ_URL": "http://localhost:7700" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+### Gemini CLI
+
+This repo ships a `gemini-extension.json` — install it directly:
 
 ```bash
-git clone https://github.com/hyperpolymath/boj-server
-cd boj-server/mcp-bridge && npm install
-# Start the BoJ REST API first (port 7700), then:
-claude mcp add boj-server -- deno run -A mcp-bridge/main.js
+gemini extensions install https://github.com/hyperpolymath/boj-server
+```
+
+Or add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "boj-server": {
+      "command": "npx",
+      "args": ["-y", "@hyperpolymath/boj-server@latest"],
+      "env": { "BOJ_URL": "http://localhost:7700" }
+    }
+  }
+}
+```
+
+### GitHub Copilot (VS Code)
+
+VS Code 1.99+ supports MCP servers natively. Add to **workspace** `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "boj-server": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@hyperpolymath/boj-server@latest"],
+      "env": { "BOJ_URL": "http://localhost:7700" }
+    }
+  }
+}
+```
+
+For **user-level** (all workspaces): Command Palette → `MCP: Add Server` → `Command (stdio)` → paste `npx -y @hyperpolymath/boj-server@latest`. Toggle BoJ on in the Copilot Chat agent picker.
+
+### Cursor
+
+Workspace: `.cursor/mcp.json`. User-global: `~/.cursor/mcp.json`.
+
+```json
+{
+  "mcpServers": {
+    "boj-server": {
+      "command": "npx",
+      "args": ["-y", "@hyperpolymath/boj-server@latest"],
+      "env": { "BOJ_URL": "http://localhost:7700" }
+    }
+  }
+}
 ```
 
+Or use Settings → MCP → **Add new MCP server**.
+
+### Cline (VS Code extension)
+
+Settings → Cline → MCP Servers → **Edit MCP Settings**:
+
+```json
+{
+  "mcpServers": {
+    "boj-server": {
+      "command": "npx",
+      "args": ["-y", "@hyperpolymath/boj-server@latest"],
+      "env": { "BOJ_URL": "http://localhost:7700" }
+    }
+  }
+}
+```
+
+### Windsurf (Codeium Cascade)
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "boj-server": {
+      "command": "npx",
+      "args": ["-y", "@hyperpolymath/boj-server@latest"],
+      "env": { "BOJ_URL": "http://localhost:7700" }
+    }
+  }
+}
+```
+
+### Continue.dev
+
+In `~/.continue/config.yaml`:
+
+```yaml
+mcpServers:
+  - name: boj-server
+    command: npx
+    args: ["-y", "@hyperpolymath/boj-server@latest"]
+    env:
+      BOJ_URL: http://localhost:7700
+```
+
+### Zed
+
+Settings (`~/.config/zed/settings.json`):
+
+```json
+{
+  "context_servers": {
+    "boj-server": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "@hyperpolymath/boj-server@latest"],
+        "env": { "BOJ_URL": "http://localhost:7700" }
+      }
+    }
+  }
+}
+```
+
+### Generic stdio (any MCP client)
+
+The minimum spec is `command: npx`, `args: ["-y", "@hyperpolymath/boj-server@latest"]`, transport `stdio`. Optional env: `BOJ_URL` (default `http://localhost:7700`).
+
+This repo's `.mcp.json` is a working reference config.
+
+### Backend
+
+Most cartridges (GitHub/GitLab/Cloud/ML/Browser/CodeSeeker/etc.) call the BoJ REST API. Two options:
+
+1. **Run BoJ locally** — clone this repo and `just run` (see [QUICKSTART-USER.adoc](./QUICKSTART-USER.adoc)). REST API on port 7700.
+2. **Inspectable mode only** — without the backend, `boj_health`, `boj_menu`, `boj_cartridges`, and `boj_cartridge_info` still respond from the offline manifest fallback, so MCP clients can introspect the server without running anything else. Side-effectful tools will return `{error, hint}` until the backend is up.
+
+### Verify
+
+After install, ask the LLM: *"Use the `boj_health` tool."* You should get `{status: "ok", uptime_s, version}` when the backend is up, or a structured hint when it's offline.
+
 Glama listing: <https://glama.ai/mcp/servers/hyperpolymath/boj-server>
 
 ## Features

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "boj-server",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Unified Gemini extension for the BoJ (Bundle of Joy) Server infrastructure.",
   "author": "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
   "mcpServers": {

jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperpolymath/boj-server",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Bundle of Joy — cartridge-based MCP server with 100 domain cartridges, formally verified (Idris2) coord core",
   "license": "MPL-2.0",
   "exports": "./mcp-bridge/main.js",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperpolymath/boj-server",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Bundle of Joy (BoJ) MCP Server — cartridge-based DevOps + multi-agent coordination toolkit with 100 domain cartridges (database, container, git, k8s, observability, secrets, IaC, multi-instance AI coord, and more). Formally verified (Idris2) core; MPL-2.0.",
   "license": "MPL-2.0",
   "author": "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",

stapeln.toml

@@ -6,7 +6,7 @@
 
 [metadata]
 name = "boj-server"
-version = "0.4.6"
+version = "0.4.7"
 description = "Bundle of Joy Server — unified MCP capability catalogue with formally verified Zig/Idris2 cartridges"
 author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
 license = "PMPL-1.0-or-later"