diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ac086fe..5790a6c1 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 1d20fee9..0ec540e1 100644 --- a/README.md +++ b/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: ## Features diff --git a/gemini-extension.json b/gemini-extension.json index 0d74f46d..f9b20537 100644 --- a/gemini-extension.json +++ b/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 ", "mcpServers": { diff --git a/jsr.json b/jsr.json index 9e881536..56e8b904 100644 --- a/jsr.json +++ b/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", diff --git a/package.json b/package.json index 2c74d4be..6a497c83 100644 --- a/package.json +++ b/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 ", diff --git a/stapeln.toml b/stapeln.toml index 83f45e66..6f8c63e0 100644 --- a/stapeln.toml +++ b/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 " license = "PMPL-1.0-or-later"