diff --git a/README.adoc b/README.adoc index 604a891a..87ba5d44 100644 --- a/README.adoc +++ b/README.adoc @@ -63,10 +63,15 @@ ____ === Claude Code (CLI) -[source,bash] ----- +```bash claude mcp add boj-server -- npx -y @hyperpolymath/boj-server@latest ----- +``` + +Or run the server directly with npx (any MCP client that launches a stdio command): + +```bash +npx -y @hyperpolymath/boj-server +``` === Claude Desktop @@ -76,8 +81,7 @@ Edit `claude++_++desktop++_++config.json`: * *Windows* — `%APPDATA%++\++Claude++\++claude++_++desktop++_++config.json` * *Linux* — `~/.config/Claude/claude++_++desktop++_++config.json` -[source,json] ----- +```json { "mcpServers": { "boj-server": { @@ -87,7 +91,7 @@ Edit `claude++_++desktop++_++config.json`: } } } ----- +``` Restart Claude Desktop after saving. @@ -100,8 +104,7 @@ The minimum stdio spec is `command: npx`, `args: ++[++"-y", "@hyperpolymath/boj- The bridge entrypoint is `mcp-bridge/main.js` and runs on any of the three runtimes with no install: -[source,bash] ----- +```bash # Deno (no install step; the project's documented runtime) deno run -A /path/to/boj-server/mcp-bridge/main.js @@ -110,7 +113,7 @@ bun /path/to/boj-server/mcp-bridge/main.js # Node (>= 18) node /path/to/boj-server/mcp-bridge/main.js ----- +``` ''''' diff --git a/README.md b/README.md index 9c7e7bf5..3d407ae4 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,11 @@ **One MCP endpoint for the WHOLE toolchain** — GitHub, GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, ML, multi-agent coordination, and a large catalogue of pluggable domain cartridges, all reachable through a single zero-dependency stdio bridge. -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](LICENSE) -[![npm](https://img.shields.io/npm/v/@hyperpolymath/boj-server?logo=npm)](https://www.npmjs.com/package/@hyperpolymath/boj-server) -[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/boj-server) -[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hyperpolymath/boj-server/badge)](https://scorecard.dev/viewer/?uri=github.com/hyperpolymath/boj-server) -[![Software Heritage](https://archive.softwareheritage.org/badge/origin/https://github.com/hyperpolymath/boj-server/)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/boj-server) -[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=hyperpolymath_boj-server)](https://sonarcloud.io/summary/new_code?id=hyperpolymath_boj-server) +| Published | [![npm](https://img.shields.io/npm/v/@hyperpolymath/boj-server?logo=npm)](https://www.npmjs.com/package/@hyperpolymath/boj-server) [![Software Heritage](https://img.shields.io/badge/SWH-Archived-blue?logo=softwareheritage)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/boj-server) [![Boj Server MCP score](https://aiagentslisting.com/boj-server/badge.svg?variant=score)](https://aiagentslisting.com/mcp/boj-server) | +|----|----| +| **Runtimes** | [![Bun](https://img.shields.io/badge/bun-%3E%3D1.0-black?logo=bun)](https://bun.sh) [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js)](https://nodejs.org) [![Deno](https://img.shields.io/badge/deno-compatible-blue?logo=deno)](https://deno.land) | +| **Security & Health** | [![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/boj-server) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hyperpolymath/boj-server/badge)](https://scorecard.dev/viewer/?uri=github.com/hyperpolymath/boj-server) [![Quality Gate](https://img.shields.io/sonar/quality_gate/hyperpolymath_boj-server?server=https%3A%2F%2Fsonarcloud.io&logo=sonarcloud)](https://sonarcloud.io/summary/new_code?id=hyperpolymath_boj-server) | +| **Compliance** | [![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](LICENSE) [![REUSE Compliance](https://api.reuse.software/badge/github.com/hyperpolymath/boj-server)](https://api.reuse.software/info/github.com/hyperpolymath/boj-server) [![Green Web Hosted](https://img.shields.io/greenweb/boj-server.net?logo=thegreenwebfoundation)](https://www.thegreenwebfoundation.org/green-web-check/?url=boj-server.net) | > **What it is, honestly:** BoJ exposes **68 MCP tools** today (45 `boj_*` + 23 `coord_*`) over stdio with **zero runtime dependencies**. It *catalogues* 125 domain cartridges, but most of those are an inspectable catalogue, not live services — a cartridge only performs real actions when its backend process is running and you supply the right credentials. The bridge is fully inspectable offline; side-effectful tools return a structured `{error, hint}` until their backend is up. See [Cartridges](#cartridges) for the full story. @@ -68,6 +67,12 @@ BoJ ships as an MCP server over **stdio**. The published npm package (`@hyperpol claude mcp add boj-server -- npx -y @hyperpolymath/boj-server@latest ``` +Or run the server directly with npx (any MCP client that launches a stdio command): + +``` bash +npx -y @hyperpolymath/boj-server +``` + ## Claude Desktop Edit `claude_desktop_config.json`: @@ -139,16 +144,16 @@ The server also implements `resources/list` (7 `boj://` resources) and `prompts/ The bridge exposes **45 `boj_*` tools** and **23 `coord_*` tools**. A subset of cartridges have explicit `boj__` tools for high-frequency operations; everything catalogued is reachable through `boj_cartridge_invoke`. -| Group | Tools | Examples | -|-----------------------------------------|-------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Core discovery / dispatch** | 5 | `boj_health`, `boj_menu`, `boj_cartridges`, `boj_cartridge_info`, `boj_cartridge_invoke` | -| **GitHub** | 14 | `boj_github_list_repos`, `boj_github_create_issue`, `boj_github_create_pr`, `boj_github_merge_pr`, `boj_github_search_code`, `boj_github_graphql` | -| **GitLab** | 8 | `boj_gitlab_list_projects`, `boj_gitlab_create_mr`, `boj_gitlab_list_pipelines`, `boj_gitlab_setup_mirror` | -| **Browser (Firefox)** | 7 | `boj_browser_navigate`, `boj_browser_click`, `boj_browser_type`, `boj_browser_read_page`, `boj_browser_screenshot`, `boj_browser_tabs`, `boj_browser_execute_js` | -| **Cloud** | 3 | `boj_cloud_cloudflare`, `boj_cloud_vercel`, `boj_cloud_verpex` | -| **Communications** | 2 | `boj_comms_gmail`, `boj_comms_calendar` | -| **Research / code intel / ML / search** | 4 | `boj_research`, `boj_codeseeker`, `boj_ml_huggingface`, `boj_search` | -| **Coordination (`local-coord-mcp`)** | 23 | `coord_register`, `coord_claim_task`, `coord_send`, `coord_review`, `coord_approve`, `coord_health` | +| Group | Tools | Examples | +|----|----|----| +| **Core discovery / dispatch** | 5 | `boj_health`, `boj_menu`, `boj_cartridges`, `boj_cartridge_info`, `boj_cartridge_invoke` | +| **GitHub** | 14 | `boj_github_list_repos`, `boj_github_create_issue`, `boj_github_create_pr`, `boj_github_merge_pr`, `boj_github_search_code`, `boj_github_graphql` | +| **GitLab** | 8 | `boj_gitlab_list_projects`, `boj_gitlab_create_mr`, `boj_gitlab_list_pipelines`, `boj_gitlab_setup_mirror` | +| **Browser (Firefox)** | 7 | `boj_browser_navigate`, `boj_browser_click`, `boj_browser_type`, `boj_browser_read_page`, `boj_browser_screenshot`, `boj_browser_tabs`, `boj_browser_execute_js` | +| **Cloud** | 3 | `boj_cloud_cloudflare`, `boj_cloud_vercel`, `boj_cloud_verpex` | +| **Communications** | 2 | `boj_comms_gmail`, `boj_comms_calendar` | +| **Research / code intel / ML / search** | 4 | `boj_research`, `boj_codeseeker`, `boj_ml_huggingface`, `boj_search` | +| **Coordination (`local-coord-mcp`)** | 23 | `coord_register`, `coord_claim_task`, `coord_send`, `coord_review`, `coord_approve`, `coord_health` | > Set `BOJ_TOOL_SCOPE=core` to advertise only the discovery surface; explicit `boj__*` tools remain reachable via `boj_cartridge_invoke` regardless. A CSV of prefixes (e.g. `core,github,browser`) advertises core plus named groups. @@ -200,11 +205,11 @@ The coordination bus (`local-coord-mcp`) is a separate localhost service, defaul Selected with `BOJ_TRANSPORT` (ADR-0013): -| Value | Behaviour | -|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `stdio` *(default)* | Reads JSON-RPC from stdin, writes to stdout — how Claude Code / Desktop launch the bridge as a subprocess. | -| `http` | Starts an HTTP+SSE listener on `BOJ_HTTP_PORT` (default `7780`) for remote / Workers / browser deployments. Binds `127.0.0.1` by default; `BOJ_HTTP_AUTH=none` is **refused** on a non-loopback bind. | -| `both` | Runs stdio and HTTP simultaneously. | +| Value | Behaviour | +|----|----| +| `stdio` *(default)* | Reads JSON-RPC from stdin, writes to stdout — how Claude Code / Desktop launch the bridge as a subprocess. | +| `http` | Starts an HTTP+SSE listener on `BOJ_HTTP_PORT` (default `7780`) for remote / Workers / browser deployments. Binds `127.0.0.1` by default; `BOJ_HTTP_AUTH=none` is **refused** on a non-loopback bind. | +| `both` | Runs stdio and HTTP simultaneously. | HTTP auth: `none` (loopback only), or `bearer` against `BOJ_HTTP_AUTH_TOKENS`. `mtls`/`oidc` are planned, not yet implemented. @@ -212,20 +217,20 @@ HTTP auth: `none` (loopback only), or `bearer` against `BOJ_HTTP_AUTH_TOKENS`. ` Key environment variables (full schema in [`glama.json`](glama.json)): -| Variable | Default | Purpose | -|------------------------------------------|--------------------------|---------------------------------------------------------------------------------| -| `BOJ_URL` | `http://localhost:7700` | Base URL for the BoJ REST backend. | -| `GITHUB_TOKEN` | — | PAT for `boj_github_*` tools. | -| `GITLAB_TOKEN` / `GITLAB_URL` | — / `https://gitlab.com` | Token + base URL for `boj_gitlab_*` tools. | -| `BOJ_TOOL_SCOPE` | `full` | `full`, `core`, or a CSV of domain prefixes (e.g. `core,github,browser`). | -| `BOJ_RATE_LIMIT` | `60` | Max tool calls per minute. | -| `BOJ_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` / `silent`. | -| `BOJ_TRANSPORT` | `stdio` | `stdio` / `http` / `both`. | -| `BOJ_HTTP_PORT` / `BOJ_HTTP_BIND` | `7780` / `127.0.0.1` | HTTP transport port and bind address. | -| `BOJ_HTTP_AUTH` / `BOJ_HTTP_AUTH_TOKENS` | `none` / — | HTTP auth mode and accepted bearer tokens. | -| `COORD_BACKEND_URL` | `http://127.0.0.1:7745` | Coordination bus backend. | -| `COORD_REQUIRE_NICKEL` | `0` | `1` enables strict Nickel-contract validation on gated envelopes. | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | When set, every `tools/call` emits an OTLP/JSON span to `/v1/traces`. | +| Variable | Default | Purpose | +|----|----|----| +| `BOJ_URL` | `http://localhost:7700` | Base URL for the BoJ REST backend. | +| `GITHUB_TOKEN` | — | PAT for `boj_github_*` tools. | +| `GITLAB_TOKEN` / `GITLAB_URL` | — / `https://gitlab.com` | Token + base URL for `boj_gitlab_*` tools. | +| `BOJ_TOOL_SCOPE` | `full` | `full`, `core`, or a CSV of domain prefixes (e.g. `core,github,browser`). | +| `BOJ_RATE_LIMIT` | `60` | Max tool calls per minute. | +| `BOJ_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` / `silent`. | +| `BOJ_TRANSPORT` | `stdio` | `stdio` / `http` / `both`. | +| `BOJ_HTTP_PORT` / `BOJ_HTTP_BIND` | `7780` / `127.0.0.1` | HTTP transport port and bind address. | +| `BOJ_HTTP_AUTH` / `BOJ_HTTP_AUTH_TOKENS` | `none` / — | HTTP auth mode and accepted bearer tokens. | +| `COORD_BACKEND_URL` | `http://127.0.0.1:7745` | Coordination bus backend. | +| `COORD_REQUIRE_NICKEL` | `0` | `1` enables strict Nickel-contract validation on gated envelopes. | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | When set, every `tools/call` emits an OTLP/JSON span to `/v1/traces`. | # Security