From cff7c6508bcdfe763a53b22ea53022fccebe3cab Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 9 Jul 2026 07:25:48 +0100 Subject: [PATCH] chore(readme): flip to single-source .adoc + derived .md (ADR-004 pilot) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit boj-server is one of two estate repos with a genuine Markdown-only consumer (Glama, which renders README.adoc as raw markup). Per ADR-004, flip it from a hand-authored README.md to authored README.adoc + CI-derived README.md: - README.adoc: new canonical source (bootstrapped from the prior README.md via the ADR-004 recipe; sets :idprefix:/:idseparator: - so the TOC anchors resolve on GitHub and re-derive cleanly). - README.md: now a GENERATED artefact (banner stamped; do not hand-edit). Verified faithful: 11/11 TOC anchors resolve, 12/12 badges intact (incl. Glama), blockquote + inline code round-trip clean. - ECOSYSTEM.a2ml: [publishing.readme] declaration (consumer=glama) — the machine-readable opt-in the derive workflow reads. - .github/workflows/readme-derive.yml: caller for the standards reusable; regenerates + freshness-checks README.md on changes. Local verification (pandoc 3.10 + asciidoctor 2.0.26): vocab gate 98.7%, normalised freshness byte-identical, anchor guard satisfied. Co-Authored-By: Claude Opus 4.8 --- .github/workflows/readme-derive.yml | 31 +++ .machine_readable/6a2/ECOSYSTEM.a2ml | 12 ++ README.adoc | 288 +++++++++++++++++++++++++++ README.md | 139 +++++++------ 4 files changed, 406 insertions(+), 64 deletions(-) create mode 100644 .github/workflows/readme-derive.yml create mode 100644 README.adoc diff --git a/.github/workflows/readme-derive.yml b/.github/workflows/readme-derive.yml new file mode 100644 index 00000000..c4d627d6 --- /dev/null +++ b/.github/workflows/readme-derive.yml @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: MPL-2.0 +# README single-source derivation (ADR-004): README.adoc is canonical; +# README.md is derived for the Glama MCP directory (Markdown-only renderer). +# This caller delegates to the standards reusable, which reads the +# [publishing.readme] declaration in .machine_readable/*/ECOSYSTEM.a2ml, +# regenerates README.md behind a vocabulary gate, and fails-and-tells if the +# committed README.md is stale relative to README.adoc. +name: README Derive + +on: + push: + branches: [main, master] + paths: + - README.adoc + - README.md + - .machine_readable/**/ECOSYSTEM.a2ml + pull_request: + paths: + - README.adoc + - README.md + - .machine_readable/**/ECOSYSTEM.a2ml + +permissions: + contents: read + +jobs: + readme-derive: + # Pinned to the standards commit that introduced readme-derive-reusable.yml. + # Repin to include hyperpolymath/standards#476 (anchor-ID convention guard) + # once it lands on main; this repo's README.adoc already satisfies it. + uses: hyperpolymath/standards/.github/workflows/readme-derive-reusable.yml@db12a6ad3ef9076d5f7bdcf98d7d15cf8547555a diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/.machine_readable/6a2/ECOSYSTEM.a2ml index 21dc7d7c..a9d25308 100644 --- a/.machine_readable/6a2/ECOSYSTEM.a2ml +++ b/.machine_readable/6a2/ECOSYSTEM.a2ml @@ -48,3 +48,15 @@ seed-nodes = [ ] dns-status = "hyperpolymath.dev undelegated — registrar action needed (see container/fly/DNS-SETUP.adoc); *.fly.dev hostnames operative" federation-protocol = "Umoja gossip (X25519 + ChaCha20-Poly1305, UDP 9999, IPv6)" + +# ── Publishing (ADR-004: README single-source derivation) ────────────────── +# README.adoc is canonical; README.md is DERIVED (GENERATED banner) for Glama, +# which renders Markdown only. Regenerated + freshness-checked by the +# readme-derive workflow. Never hand-edit README.md. +[publishing.readme] +canonical = "README.adoc" +derive = true +format = "gfm" +path = "README.md" +consumer = "glama" +reason = "Glama MCP directory renders Markdown only; canonical README.adoc renders as raw markup there" diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..f62adf8a --- /dev/null +++ b/README.adoc @@ -0,0 +1,288 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell += BoJ Server +:idprefix: +:idseparator: - + +*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. + +link:LICENSE[image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0]] +https://www.npmjs.com/package/@hyperpolymath/boj-server[image:https://img.shields.io/npm/v/@hyperpolymath/boj-server?logo=npm[npm]] +https://glama.ai/mcp/servers/hyperpolymath/boj-server[image:https://glama.ai/mcp/servers/hyperpolymath/boj-server/badge[Glama MCP Server]] +https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/boj-server[image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices]] +https://scorecard.dev/viewer/?uri=github.com/hyperpolymath/boj-server[image:https://api.scorecard.dev/projects/github.com/hyperpolymath/boj-server/badge[OpenSSF Scorecard]] +https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/boj-server[image:https://archive.softwareheritage.org/badge/origin/https://github.com/hyperpolymath/boj-server/[Software Heritage]] +https://sonarcloud.io/summary/new_code?id=hyperpolymath_boj-server[image:https://sonarcloud.io/api/project_badges/quality_gate?project=hyperpolymath_boj-server[Quality gate]] + +____ +*What it is, honestly:* BoJ exposes *68 MCP tools* today (45 `boj++_*++` {plus} 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 link:#cartridges[Cartridges] for the full story. +____ + +''''' + +== Contents + +* link:#features[Features] +* link:#install[Install] +* link:#quickstart[Quickstart] +* link:#capabilities-overview[Capabilities overview] +* link:#cartridges[Cartridges] +* link:#backend[Backend] +* link:#transports[Transports] +* link:#configuration[Configuration] +* link:#security[Security] +* link:#license[License] +* link:++#contributing--links++[Contributing & links] + +''''' + +== Features + +* *Unified endpoint* — GitHub/GitLab, Cloudflare/Vercel/Verpex, Gmail/Calendar, Firefox browser automation, CodeSeeker code intelligence, Semantic Scholar research, and Hugging Face ML, all behind one MCP server. +* *68 MCP tools* — 45 `boj++_*++` (5 core discovery/dispatch {plus} explicit high-frequency tools) and 23 `coord++_*++` multi-agent coordination tools. +* *125-cartridge catalogue* — a single `boj++_++cartridge++_++invoke` reaches any catalogued cartridge; explicit `boj++_<++domain++>_<++verb++>++` tools exist for the highest-frequency operations. +* *Multi-instance AI coordination* — `local-coord-mcp` lets several Claude / Gemini / Codex sessions on one machine discover each other, claim tasks without collision, and run under a master/journeyman/apprentice supervision model. +* *Zero runtime dependencies* — the bridge runs on Node, Deno, or Bun with no install step. +* *Inspectable offline* — `boj++_++health`, `boj++_++menu`, `boj++_++cartridges`, and `boj++_++cartridge++_++info` answer from an offline manifest so clients can introspect the server without any backend running. +* *MCP resources & prompts* — 7 `boj://` resources and reusable prompts (`audit-repo`, `convene-cluster`, `deploy-with-dns-ssl`, `summarize-channel`, `triage-issues`, `proof-status`). +* *Hardened* — per-call rate limiting, size caps, prompt-injection detection with Unicode-confusable normalisation, and error sanitisation (paths, stack traces, and env vars stripped from responses). +* *Formally verified core* — the coordination ABI is written in Idris2 with discharged proof obligations; remaining axioms are documented, not hidden. + +''''' + +== Install + +BoJ ships as an MCP server over *stdio*. The published npm package (`@hyperpolymath/boj-server`) has *zero runtime dependencies*, so no install step is ever required regardless of runtime. + +____ +Most cartridges call the BoJ REST backend on `http://localhost:7700`. Without it, the server is still fully inspectable; side-effectful tools return `++{++error, hint}`. See link:#backend[Backend]. +____ + +=== Claude Code (CLI) + +[source,bash] +---- +claude mcp add boj-server -- npx -y @hyperpolymath/boj-server@latest +---- + +=== 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` + +[source,json] +---- +{ + "mcpServers": { + "boj-server": { + "command": "npx", + "args": ["-y", "@hyperpolymath/boj-server@latest"], + "env": { "BOJ_URL": "http://localhost:7700" } + } + } +} +---- + +Restart Claude Desktop after saving. + +=== npx (any MCP client) + +The minimum stdio spec is `command: npx`, `args: ++[++"-y", "@hyperpolymath/boj-server@latest"++]++`. Optional env: `BOJ++_++URL` (default `http://localhost:7700`). This works with VS Code / Copilot, Cursor, Cline, Windsurf, Continue.dev, Zed, and the Gemini CLI — point each client's MCP config at that command. This repo's `.mcp.json` is a working reference config. + +[[deno--bun--node-from-a-clone]] +=== Deno / Bun / Node (from a clone) + +The bridge entrypoint is `mcp-bridge/main.js` and runs on any of the three runtimes with no install: + +[source,bash] +---- +# Deno (no install step; the project's documented runtime) +deno run -A /path/to/boj-server/mcp-bridge/main.js + +# Bun (zero-install) +bun /path/to/boj-server/mcp-bridge/main.js + +# Node (>= 18) +node /path/to/boj-server/mcp-bridge/main.js +---- + +''''' + +== Quickstart + +After install, ask your LLM: _"Use the `boj++_++health` tool."_ You get `++{++status:"ok", uptime++_++s, version}` when the backend is up, or a structured hint when it is offline. + +To talk to the bridge directly over stdio, send newline-delimited JSON-RPC. Initialize, then list tools: + +[source,bash] +---- +printf '%s\n%s\n' \ + '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"demo","version":"0"}}}' \ + '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \ + | node mcp-bridge/main.js +---- + +The `initialize` response reports protocol `2024-11-05` and server `boj-server`; `tools/list` returns *68* tool definitions (45 `boj++_*++`, 23 `coord++_*++`), each carrying a full description, JSON-Schema `inputSchema`/`outputSchema`, and MCP behaviour annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). + +Call a tool: + +[source,jsonc] +---- +{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", + "params": { "name": "boj_health", "arguments": {} } } +---- + +The server also implements `resources/list` (7 `boj://` resources) and `prompts/list`. + +''''' + +== Capabilities overview + +The bridge exposes *45 `boj++_*++` tools* and *23 `coord++_*++` tools*. A subset of cartridges have explicit `boj++_<++domain++>_<++verb++>++` tools for high-frequency operations; everything catalogued is reachable through `boj++_++cartridge++_++invoke`. + +[cols=",,",options="header",] +|=== +|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++_<++domain++>_*++` tools remain reachable via `boj++_++cartridge++_++invoke` regardless. A CSV of prefixes (e.g. `core,github,browser`) advertises core plus named groups. +____ + +=== Multi-agent coordination (`coord++_*++`) + +A localhost multi-agent bus (default `127.0.0.1:7745`) lets multiple AI sessions on one machine discover each other, claim tasks without collision, and operate under supervision (master approves; journeyman executes; apprentice stays gated): + +* *Peers* — `coord++_++register`, `coord++_++list++_++peers`, `coord++_++set++_++variant`, `coord++_++set++_++capabilities`, `coord++_++get++_++peer++_++capabilities`. +* *Typed envelopes* — `coord++_++send`, `coord++_++send++_++gated`, `coord++_++receive` (Nickel-contract validation, opt-in strict mode). +* *Task claims* — `coord++_++claim++_++task` with role-based watchdog TTL, `coord++_++progress` heartbeats, `coord++_++sweep++_++watchdog`, optional advisory `paths` for `path++_++overlap` warnings. +* *Track record* — `coord++_++report++_++outcome`, `coord++_++get++_++affinities`, `coord++_++set++_++declared++_++affinities`, `coord++_++scan++_++suggestions` (emits `overclaim`/`drift` advisory envelopes). +* *Supervision* — `coord++_++review`, `coord++_++review++_++entry`, `coord++_++approve`, `coord++_++reject`, `coord++_++promote++_++to++_++master`, `coord++_++transfer++_++master`, plus `coord++_++status` / `coord++_++health`. + +Task-claim collision-freedom is a *task-level* guarantee, not a git-level lock: two journeymen claiming _different_ tasks that touch the same file can still hit a vanilla merge conflict. The supported pattern is branch-per-claim {plus} per-peer worktree, advisory path-claims, and master-gated integration. The companion terminal UI lives in link:coord-tui/[`coord-tui/`] and at https://github.com/hyperpolymath/coord-tui[hyperpolymath/coord-tui]. + +''''' + +== Cartridges + +BoJ catalogues *125 cartridges* across trust tiers (Teranga / Shield / Ayo). Be clear about what that means: + +* *Catalogued ≠ live.* `boj++_++menu` lists the full catalogue, but most cartridges report `available: false`. They are entries describing a capability — its API base URL, auth model (often brokered through `vault-mcp`), and any native FFI path — not a running service. +* *A cartridge becomes available when* (1) its backend process is running and reachable via the BoJ REST API, and (2) you have supplied the credentials it needs. +* *Credentials* are typically environment variables (`GITHUB++_++TOKEN`, `GITLAB++_++TOKEN`, `CF++_++API++_++TOKEN`, OAuth tokens, …) or are brokered by the `vault-mcp` credential cartridge. `boj++_++cartridge++_++info ++<++name++>++` returns the cartridge's manifest, including the exact auth requirement. +* *Without backend or credentials*, side-effectful tools return a structured `++{++error, hint}` telling you what's missing — they never silently fail. + +____ +*Number transparency:* *125* is the single source of truth — it is the number of `cartridge.json` manifests under `cartridges/` and what the live `boj++_++menu` reports. Every packaging file (`package.json`, `jsr.json`, `smithery.yaml`, `ai-plugin.json`, `openapi.yaml`, `CITATION.cff`) is reconciled to it. Of those 125, most are a catalogue entry rather than a live service — see the bullets above. +____ + +Catalogued domains include: git forges & code hosting, cloud platforms (Cloudflare, Vercel, AWS, GCP, DigitalOcean, Hetzner, Fly, Linode, Railway, Render), databases (PostgreSQL, MongoDB, Redis, Neo4j, ClickHouse, DuckDB, Turso, Supabase, Neon, …), containers & Kubernetes, CI/CD & observability (Buildkite, CircleCI, Hypatia, Grafana, Prometheus, Sentry), messaging (Slack, Discord, Telegram, Matrix), productivity (Notion, Linear, Jira, Obsidian, Zotero), ML/AI & coordination, browser & web automation, code intelligence & research, developer tooling (LSP/DAP/BSP, language & package registries), security & secrets, IaC & proof systems, and hyperpolymath-native admin cartridges. + +''''' + +== Backend + +Most cartridges (GitHub/GitLab, cloud, ML, browser, CodeSeeker, etc.) call the BoJ REST API — an *Elixir* service on *`http://localhost:7700`*. Two modes: + +[arabic] +. *Run BoJ locally* — clone this repo and `just run` (see link:docs/quickstarts/USER.adoc[`docs/quickstarts/USER.adoc`]). The REST API serves on port `7700`. +. *Inspectable mode only* — without the backend, `boj++_++health`, `boj++_++menu`, `boj++_++cartridges`, and `boj++_++cartridge++_++info` still respond from the offline manifest, so any MCP client can introspect the server. Side-effectful tools return `++{++error, hint}` until the backend is up. + +____ +*Note on versions:* when the backend is offline, `boj++_++health` may report a placeholder backend version (`0.1.0`) from the bundled offline manifest — this is the manifest's hardcoded value, not the npm package version (`0.4.7`). The MCP bridge itself reports `0.4.7` at `initialize`. +____ + +The coordination bus (`local-coord-mcp`) is a separate localhost service, default `http://127.0.0.1:7745` (`COORD++_++BACKEND++_++URL`). + +''''' + +== Transports + +Selected with `BOJ++_++TRANSPORT` (ADR-0013): + +[cols=",",options="header",] +|=== +|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{plus}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. + +''''' + +== Configuration + +Key environment variables (full schema in link:glama.json[`glama.json`]): + +[cols=",,",options="header",] +|=== +|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 {plus} 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 `++<++endpoint++>++/v1/traces`. +|=== + +''''' + +== Security + +* *Input hardening* — per-call rate limiting (`BOJ++_++RATE++_++LIMIT`), request size caps, and prompt-injection detection with Unicode-confusable normalisation. +* *Error sanitisation* — responses strip filesystem paths, stack traces, and environment variables before they reach the client. +* *HTTP safety* — `BOJ++_++HTTP++_++AUTH=none` is refused on any non-loopback bind; bearer auth is required for remote exposure. +* *Credential isolation* — cartridge credentials are supplied per-cartridge (env vars or the `vault-mcp` broker), never embedded in tool definitions. +* *Formal verification* — the coordination ABI safety layer is written in Idris2 with discharged proof obligations; remaining `believe++_++me` sites are isolated, documented axioms over the compiler's opaque `Char`/`String` primitives, tracked in link:PROOF-NEEDS.md[`PROOF-NEEDS.md`]. +* *Supply chain* — SHA-pinned GitHub Actions; coherence tests assert the advertised tool list matches the cartridge manifest so nothing is advertised-but-undispatched. + +Run the coherence tests: + +[source,bash] +---- +node --test mcp-bridge/tests/ +---- + +Report vulnerabilities per link:SECURITY.md[`SECURITY.md`]. + +''''' + +== License + +* *Code* — link:LICENSE[MPL-2.0] (Mozilla Public License 2.0) — the license published to npm and detected by GitHub. +* *Documentation* — MPL-2.0 today (the repository's REUSE config tags every file MPL-2.0); a *CC-BY-SA-4.0* split for prose is the intended model, with the docs-licence rollout tracked as a follow-up. + +This project *does not* use AGPL; any AGPL string remaining in a build manifest is a packaging regression, not the project's license. + +''''' + +[[contributing--links]] +== Contributing & links + +* *Repository* — https://github.com/hyperpolymath/boj-server[github.com/hyperpolymath/boj-server] +* *npm* — https://www.npmjs.com/package/@hyperpolymath/boj-server[`@hyperpolymath/boj-server`] +* *Glama listing* — https://glama.ai/mcp/servers/hyperpolymath/boj-server[glama.ai/mcp/servers/hyperpolymath/boj-server] +* *Coordination TUI* — https://github.com/hyperpolymath/coord-tui[hyperpolymath/coord-tui] +* *Contributing* — see link:CONTRIBUTING.md[`CONTRIBUTING.md`] and link:CODE_OF_CONDUCT.md[`CODE++_++OF++_++CONDUCT.md`]. +* *Citing* — citation metadata is in link:CITATION.cff[`CITATION.cff`]; GitHub renders a "Cite this repository" button from it. + +Maintained by Jonathan D.A. Jewell. diff --git a/README.md b/README.md index a1e1c3e3..3cb73baf 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,5 @@ - - -# BoJ Server + + **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. @@ -17,59 +13,73 @@ SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell > **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. ---- - -## Contents +# Contents - [Features](#features) + - [Install](#install) + - [Quickstart](#quickstart) + - [Capabilities overview](#capabilities-overview) + - [Cartridges](#cartridges) + - [Backend](#backend) + - [Transports](#transports) + - [Configuration](#configuration) + - [Security](#security) + - [License](#license) -- [Contributing & links](#contributing--links) ---- +- [Contributing & links](#contributing--links) -## Features +# Features - **Unified endpoint** — GitHub/GitLab, Cloudflare/Vercel/Verpex, Gmail/Calendar, Firefox browser automation, CodeSeeker code intelligence, Semantic Scholar research, and Hugging Face ML, all behind one MCP server. + - **68 MCP tools** — 45 `boj_*` (5 core discovery/dispatch + explicit high-frequency tools) and 23 `coord_*` multi-agent coordination tools. + - **125-cartridge catalogue** — a single `boj_cartridge_invoke` reaches any catalogued cartridge; explicit `boj__` tools exist for the highest-frequency operations. + - **Multi-instance AI coordination** — `local-coord-mcp` lets several Claude / Gemini / Codex sessions on one machine discover each other, claim tasks without collision, and run under a master/journeyman/apprentice supervision model. + - **Zero runtime dependencies** — the bridge runs on Node, Deno, or Bun with no install step. + - **Inspectable offline** — `boj_health`, `boj_menu`, `boj_cartridges`, and `boj_cartridge_info` answer from an offline manifest so clients can introspect the server without any backend running. + - **MCP resources & prompts** — 7 `boj://` resources and reusable prompts (`audit-repo`, `convene-cluster`, `deploy-with-dns-ssl`, `summarize-channel`, `triage-issues`, `proof-status`). + - **Hardened** — per-call rate limiting, size caps, prompt-injection detection with Unicode-confusable normalisation, and error sanitisation (paths, stack traces, and env vars stripped from responses). -- **Formally verified core** — the coordination ABI is written in Idris2 with discharged proof obligations; remaining axioms are documented, not hidden. ---- +- **Formally verified core** — the coordination ABI is written in Idris2 with discharged proof obligations; remaining axioms are documented, not hidden. -## Install +# Install BoJ ships as an MCP server over **stdio**. The published npm package (`@hyperpolymath/boj-server`) has **zero runtime dependencies**, so no install step is ever required regardless of runtime. > Most cartridges call the BoJ REST backend on `http://localhost:7700`. Without it, the server is still fully inspectable; side-effectful tools return `{error, hint}`. See [Backend](#backend). -### Claude Code (CLI) +## Claude Code (CLI) -```bash +``` bash claude mcp add boj-server -- npx -y @hyperpolymath/boj-server@latest ``` -### Claude Desktop +## 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 +``` json { "mcpServers": { "boj-server": { @@ -83,15 +93,15 @@ Edit `claude_desktop_config.json`: Restart Claude Desktop after saving. -### npx (any MCP client) +## npx (any MCP client) -The minimum stdio spec is `command: npx`, `args: ["-y", "@hyperpolymath/boj-server@latest"]`. Optional env: `BOJ_URL` (default `http://localhost:7700`). This works with VS Code / Copilot, Cursor, Cline, Windsurf, Continue.dev, Zed, and the Gemini CLI — point each client's MCP config at that command. This repo's `.mcp.json` is a working reference config. +The minimum stdio spec is `command: npx`, `args: ["-y", "@hyperpolymath/boj-server@latest"]`. Optional env: `BOJ_URL` (default `http://localhost:7700`). This works with VS Code / Copilot, Cursor, Cline, Windsurf, Continue.dev, Zed, and the Gemini CLI — point each client’s MCP config at that command. This repo’s `.mcp.json` is a working reference config. -### Deno / Bun / Node (from a clone) +## Deno / Bun / Node (from a clone) The bridge entrypoint is `mcp-bridge/main.js` and runs on any of the three runtimes with no install: -```bash +``` bash # Deno (no install step; the project's documented runtime) deno run -A /path/to/boj-server/mcp-bridge/main.js @@ -102,15 +112,13 @@ bun /path/to/boj-server/mcp-bridge/main.js node /path/to/boj-server/mcp-bridge/main.js ``` ---- - -## Quickstart +# Quickstart After install, ask your LLM: *"Use the `boj_health` tool."* You get `{status:"ok", uptime_s, version}` when the backend is up, or a structured hint when it is offline. To talk to the bridge directly over stdio, send newline-delimited JSON-RPC. Initialize, then list tools: -```bash +``` bash printf '%s\n%s\n' \ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"demo","version":"0"}}}' \ '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \ @@ -121,21 +129,19 @@ The `initialize` response reports protocol `2024-11-05` and server `boj-server`; Call a tool: -```jsonc +``` jsonc { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "boj_health", "arguments": {} } } ``` The server also implements `resources/list` (7 `boj://` resources) and `prompts/list`. ---- - -## Capabilities overview +# Capabilities overview 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` | @@ -147,68 +153,68 @@ The bridge exposes **45 `boj_*` tools** and **23 `coord_*` tools**. A subset of > 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. -### Multi-agent coordination (`coord_*`) +## Multi-agent coordination (`coord_*`) A localhost multi-agent bus (default `127.0.0.1:7745`) lets multiple AI sessions on one machine discover each other, claim tasks without collision, and operate under supervision (master approves; journeyman executes; apprentice stays gated): - **Peers** — `coord_register`, `coord_list_peers`, `coord_set_variant`, `coord_set_capabilities`, `coord_get_peer_capabilities`. + - **Typed envelopes** — `coord_send`, `coord_send_gated`, `coord_receive` (Nickel-contract validation, opt-in strict mode). + - **Task claims** — `coord_claim_task` with role-based watchdog TTL, `coord_progress` heartbeats, `coord_sweep_watchdog`, optional advisory `paths` for `path_overlap` warnings. + - **Track record** — `coord_report_outcome`, `coord_get_affinities`, `coord_set_declared_affinities`, `coord_scan_suggestions` (emits `overclaim`/`drift` advisory envelopes). + - **Supervision** — `coord_review`, `coord_review_entry`, `coord_approve`, `coord_reject`, `coord_promote_to_master`, `coord_transfer_master`, plus `coord_status` / `coord_health`. Task-claim collision-freedom is a **task-level** guarantee, not a git-level lock: two journeymen claiming *different* tasks that touch the same file can still hit a vanilla merge conflict. The supported pattern is branch-per-claim + per-peer worktree, advisory path-claims, and master-gated integration. The companion terminal UI lives in [`coord-tui/`](coord-tui/) and at [hyperpolymath/coord-tui](https://github.com/hyperpolymath/coord-tui). ---- - -## Cartridges +# Cartridges BoJ catalogues **125 cartridges** across trust tiers (Teranga / Shield / Ayo). Be clear about what that means: - **Catalogued ≠ live.** `boj_menu` lists the full catalogue, but most cartridges report `available: false`. They are entries describing a capability — its API base URL, auth model (often brokered through `vault-mcp`), and any native FFI path — not a running service. + - **A cartridge becomes available when** (1) its backend process is running and reachable via the BoJ REST API, and (2) you have supplied the credentials it needs. -- **Credentials** are typically environment variables (`GITHUB_TOKEN`, `GITLAB_TOKEN`, `CF_API_TOKEN`, OAuth tokens, …) or are brokered by the `vault-mcp` credential cartridge. `boj_cartridge_info ` returns the cartridge's manifest, including the exact auth requirement. -- **Without backend or credentials**, side-effectful tools return a structured `{error, hint}` telling you what's missing — they never silently fail. + +- **Credentials** are typically environment variables (`GITHUB_TOKEN`, `GITLAB_TOKEN`, `CF_API_TOKEN`, OAuth tokens, …) or are brokered by the `vault-mcp` credential cartridge. `boj_cartridge_info ` returns the cartridge’s manifest, including the exact auth requirement. + +- **Without backend or credentials**, side-effectful tools return a structured `{error, hint}` telling you what’s missing — they never silently fail. > **Number transparency:** **125** is the single source of truth — it is the number of `cartridge.json` manifests under `cartridges/` and what the live `boj_menu` reports. Every packaging file (`package.json`, `jsr.json`, `smithery.yaml`, `ai-plugin.json`, `openapi.yaml`, `CITATION.cff`) is reconciled to it. Of those 125, most are a catalogue entry rather than a live service — see the bullets above. Catalogued domains include: git forges & code hosting, cloud platforms (Cloudflare, Vercel, AWS, GCP, DigitalOcean, Hetzner, Fly, Linode, Railway, Render), databases (PostgreSQL, MongoDB, Redis, Neo4j, ClickHouse, DuckDB, Turso, Supabase, Neon, …), containers & Kubernetes, CI/CD & observability (Buildkite, CircleCI, Hypatia, Grafana, Prometheus, Sentry), messaging (Slack, Discord, Telegram, Matrix), productivity (Notion, Linear, Jira, Obsidian, Zotero), ML/AI & coordination, browser & web automation, code intelligence & research, developer tooling (LSP/DAP/BSP, language & package registries), security & secrets, IaC & proof systems, and hyperpolymath-native admin cartridges. ---- - -## Backend +# Backend Most cartridges (GitHub/GitLab, cloud, ML, browser, CodeSeeker, etc.) call the BoJ REST API — an **Elixir** service on **`http://localhost:7700`**. Two modes: -1. **Run BoJ locally** — clone this repo and `just run` (see [`docs/quickstarts/USER.adoc`](docs/quickstarts/USER.adoc)). The REST API serves 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, so any MCP client can introspect the server. Side-effectful tools return `{error, hint}` until the backend is up. +1. **Run BoJ locally** — clone this repo and `just run` (see [`docs/quickstarts/USER.adoc`](docs/quickstarts/USER.adoc)). The REST API serves on port `7700`. -> **Note on versions:** when the backend is offline, `boj_health` may report a placeholder backend version (`0.1.0`) from the bundled offline manifest — this is the manifest's hardcoded value, not the npm package version (`0.4.7`). The MCP bridge itself reports `0.4.7` at `initialize`. +2. **Inspectable mode only** — without the backend, `boj_health`, `boj_menu`, `boj_cartridges`, and `boj_cartridge_info` still respond from the offline manifest, so any MCP client can introspect the server. Side-effectful tools return `{error, hint}` until the backend is up. -The coordination bus (`local-coord-mcp`) is a separate localhost service, default `http://127.0.0.1:7745` (`COORD_BACKEND_URL`). +> **Note on versions:** when the backend is offline, `boj_health` may report a placeholder backend version (`0.1.0`) from the bundled offline manifest — this is the manifest’s hardcoded value, not the npm package version (`0.4.7`). The MCP bridge itself reports `0.4.7` at `initialize`. ---- +The coordination bus (`local-coord-mcp`) is a separate localhost service, default `http://127.0.0.1:7745` (`COORD_BACKEND_URL`). -## Transports +# Transports 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. | HTTP auth: `none` (loopback only), or `bearer` against `BOJ_HTTP_AUTH_TOKENS`. `mtls`/`oidc` are planned, not yet implemented. ---- - -## Configuration +# Configuration 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. | @@ -222,43 +228,48 @@ Key environment variables (full schema in [`glama.json`](glama.json)): | `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 +# Security - **Input hardening** — per-call rate limiting (`BOJ_RATE_LIMIT`), request size caps, and prompt-injection detection with Unicode-confusable normalisation. + - **Error sanitisation** — responses strip filesystem paths, stack traces, and environment variables before they reach the client. + - **HTTP safety** — `BOJ_HTTP_AUTH=none` is refused on any non-loopback bind; bearer auth is required for remote exposure. + - **Credential isolation** — cartridge credentials are supplied per-cartridge (env vars or the `vault-mcp` broker), never embedded in tool definitions. -- **Formal verification** — the coordination ABI safety layer is written in Idris2 with discharged proof obligations; remaining `believe_me` sites are isolated, documented axioms over the compiler's opaque `Char`/`String` primitives, tracked in [`PROOF-NEEDS.md`](PROOF-NEEDS.md). + +- **Formal verification** — the coordination ABI safety layer is written in Idris2 with discharged proof obligations; remaining `believe_me` sites are isolated, documented axioms over the compiler’s opaque `Char`/`String` primitives, tracked in [`PROOF-NEEDS.md`](PROOF-NEEDS.md). + - **Supply chain** — SHA-pinned GitHub Actions; coherence tests assert the advertised tool list matches the cartridge manifest so nothing is advertised-but-undispatched. Run the coherence tests: -```bash +``` bash node --test mcp-bridge/tests/ ``` Report vulnerabilities per [`SECURITY.md`](SECURITY.md). ---- - -## License +# License - **Code** — [MPL-2.0](LICENSE) (Mozilla Public License 2.0) — the license published to npm and detected by GitHub. -- **Documentation** — MPL-2.0 today (the repository's REUSE config tags every file MPL-2.0); a **CC-BY-SA-4.0** split for prose is the intended model, with the docs-licence rollout tracked as a follow-up. -This project **does not** use AGPL; any AGPL string remaining in a build manifest is a packaging regression, not the project's license. +- **Documentation** — MPL-2.0 today (the repository’s REUSE config tags every file MPL-2.0); a **CC-BY-SA-4.0** split for prose is the intended model, with the docs-licence rollout tracked as a follow-up. ---- +This project **does not** use AGPL; any AGPL string remaining in a build manifest is a packaging regression, not the project’s license. -## Contributing & links +# Contributing & links - **Repository** — [github.com/hyperpolymath/boj-server](https://github.com/hyperpolymath/boj-server) + - **npm** — [`@hyperpolymath/boj-server`](https://www.npmjs.com/package/@hyperpolymath/boj-server) + - **Glama listing** — [glama.ai/mcp/servers/hyperpolymath/boj-server](https://glama.ai/mcp/servers/hyperpolymath/boj-server) + - **Coordination TUI** — [hyperpolymath/coord-tui](https://github.com/hyperpolymath/coord-tui) + - **Contributing** — see [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). + - **Citing** — citation metadata is in [`CITATION.cff`](CITATION.cff); GitHub renders a "Cite this repository" button from it. Maintained by Jonathan D.A. Jewell.