From daf8129ae7ea25a518322bed37b2f108ed22db19 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 09:21:43 +0100 Subject: [PATCH 1/5] fix(abi): remove duplicate allTake definition in SafetyLemmas `allTake` was defined twice in src/abi/Boj/SafetyLemmas.idr (a merge artifact); both clauses prove the identical proposition `allRec p xs = True -> allRec p (take n xs) = True`, differing only in implicit-argument order. The duplicate made the core `boj.ipkg` fail to type-check ("Boj.SafetyLemmas.allTake is already defined"), so scripts/typecheck-proofs.sh reported PASS=104 FAIL=1. Removed the redundant second copy; callers use `allTake prf` with inferred implicits, so argument order is irrelevant. The full proof gate is now PASS=105 FAIL=0, the trusted base is unchanged (5 sanctioned class-(J) axioms in SafetyLemmas), JS tests pass 52/52, and boot_smoke passes on node, bun, and deno. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/abi/Boj/SafetyLemmas.idr | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/src/abi/Boj/SafetyLemmas.idr b/src/abi/Boj/SafetyLemmas.idr index bbce315f..7629f90d 100644 --- a/src/abi/Boj/SafetyLemmas.idr +++ b/src/abi/Boj/SafetyLemmas.idr @@ -210,16 +210,6 @@ allNotImpliesAnyFalse {p} {xs = x :: xs'} prf with (p x) proof pEq allNotImpliesAnyFalse {p} {xs = x :: xs'} prf | False = allNotImpliesAnyFalse {xs = xs'} prf -||| If `allRec p xs = True`, then `allRec p (take n xs) = True`. -export -allTake : {p : a -> Bool} -> {xs : List a} -> {n : Nat} -> - allRec p xs = True -> allRec p (take n xs) = True -allTake {n = Z} _ = Refl -allTake {xs = []} {n = S _} _ = Refl -allTake {p} {xs = x :: xs'} {n = S n'} prf with (p x) proof eq - allTake {p} {xs = x :: xs'} {n = S n'} prf | True = allTake {xs = xs'} {n = n'} prf - allTake {p} {xs = x :: xs'} {n = S n'} prf | False = absurd prf - ||| Convert a Bool lte witness to LTE. export fromLteTrue : (a, b : Nat) -> (a <= b) = True -> LTE a b From 04cdf2fa769935c807e28c12cf74db2ebc7709d8 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 09:25:12 +0100 Subject: [PATCH 2/5] chore(license,packaging): MPL-2.0 not AGPL; real Markdown README; npm hygiene - License: restore MPL-2.0 in package.json (the published 0.4.7 is already MPL-2.0; the AGPL-3.0-or-later in the working tree was a regression) and switch the sub-component manifests from AGPL to MPL-2.0: elixir/mix.exs, coord-tui/Cargo.toml, tray/Cargo.toml, and the three tools/* packages. (cartridges/idaptik-admin-mcp is intentionally left AGPL.) - README.md: rewrite as true GitHub-Flavored Markdown. It was AsciiDoc markup saved in a .md file, which renders garbled on GitHub/npm/Glama. Marked CC-BY-SA-4.0 (docs). README.adoc is retained as the AsciiDoc source. - package.json: add a `files` whitelist (mcp-bridge/, README.md, LICENSE, NOTICE) so the npm tarball drops from ~10.5 MB to ~0.9 MB. - mcp-bridge/main.js: shebang `deno run ...` -> `node` so the documented `npx` install actually runs under Node. - .gitattributes: linguist overrides (vendor cartridges/ and ffi/, mark docs) so GitHub stops detecting the repo as "Zig". Co-Authored-By: Claude Opus 4.8 (1M context) --- .gitattributes | 9 + README.md | 715 ++++++---------------- coord-tui/Cargo.toml | 2 +- elixir/mix.exs | 2 +- mcp-bridge/main.js | 2 +- package.json | 10 +- tools/cartridge-configurator/package.json | 2 +- tools/cartridge-provisioner/package.json | 2 +- tools/panel-harness/package.json | 2 +- tray/Cargo.toml | 2 +- 10 files changed, 216 insertions(+), 532 deletions(-) diff --git a/.gitattributes b/.gitattributes index f8b85360..f8b77f79 100644 --- a/.gitattributes +++ b/.gitattributes @@ -58,3 +58,12 @@ Containerfile text eol=lf # Lock files Cargo.lock text eol=lf -diff flake.lock text eol=lf -diff + +# GitHub Linguist — surface the JS/Deno MCP bridge (mcp-bridge/) as the +# primary language instead of the bulky Zig FFI / generated cartridge code. +cartridges/** linguist-vendored +ffi/** linguist-vendored +generated/** linguist-generated +*.adoc linguist-documentation +docs/** linguist-documentation +proofs/** linguist-documentation diff --git a/README.md b/README.md index aa1f0750..12225fc1 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,74 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) + -// SPDX-License-Identifier: MPL-2.0 -// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell +# BoJ Server (Bundle of Joy) -= boj-server -:toc: preamble -:icons: font +**One MCP endpoint for the whole hyperpolymath 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. -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/boj-server"] -image:https://api.scorecard.dev/projects/github.com/hyperpolymath/boj-server/badge[OpenSSF Scorecard,link="https://scorecard.dev/viewer/?uri=github.com/hyperpolymath/boj-server"] -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: MPL-2.0,link="LICENSE"] -image:https://glama.ai/mcp/servers/hyperpolymath/boj-server/badge[Glama MCP Server,link="https://glama.ai/mcp/servers/hyperpolymath/boj-server"] -image:https://api.thegreenwebfoundation.org/greencheckimage/boj-server.net[Green Hosting,link="https://www.thegreenwebfoundation.org/green-web-check/?url=boj-server.net"] -image:https://archive.softwareheritage.org/badge/origin/https://github.com/hyperpolymath/boj-server/[Software Heritage,link="https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/boj-server"] +[![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) +[![Glama MCP Server](https://glama.ai/mcp/servers/hyperpolymath/boj-server/badge)](https://glama.ai/mcp/servers/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) -BoJ (Bundle of Joy) is a unified MCP server that consolidates all hyperpolymath tooling into a single endpoint — GitHub, GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, ML, and 115 open-source cartridges. +> **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. -== Install +--- -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: +## Contents -[source,bash] ----- -# Preferred — Deno (no install step; fetches imports on first run) -deno run -A /path/to/boj-server/mcp-bridge/main.js +- [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) -# 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 ----- +## 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. + +--- -The bridge has *zero runtime dependencies* (see `package.json`) so no install step is ever required, regardless of runtime. +## Install -Most cartridges require the BoJ REST backend running on `http://localhost:7700` — see <> below. +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. -=== Claude Code (CLI) +> 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). -[source,bash] ----- +### Claude Code (CLI) + +```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` +- **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] ----- +```json { "mcpServers": { "boj-server": { @@ -62,533 +78,186 @@ Edit `claude_desktop_config.json`: } } } ----- +``` Restart Claude Desktop after saving. -=== Gemini CLI +### npx (any MCP client) -This repo ships a `gemini-extension.json` — install it directly: +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. -[source,bash] ----- -gemini extensions install https://github.com/hyperpolymath/boj-server ----- +### Deno / Bun / Node (from a clone) -Or add to `~/.gemini/settings.json`: +The bridge entrypoint is `mcp-bridge/main.js` and runs on any of the three runtimes with no install: -[source,json] ----- -{ - "mcpServers": { - "boj-server": { - "command": "npx", - "args": ["-y", "@hyperpolymath/boj-server@latest"], - "env": { "BOJ_URL": "http://localhost:7700" } - } - } -} ----- +```bash +# Deno (no install step; the project's documented runtime) +deno run -A /path/to/boj-server/mcp-bridge/main.js -=== GitHub Copilot (VS Code) +# Bun (zero-install) +bun /path/to/boj-server/mcp-bridge/main.js -VS Code 1.99+ supports MCP servers natively. Add to *workspace* `.vscode/mcp.json`: +# Node (>= 18) +node /path/to/boj-server/mcp-bridge/main.js +``` -[source,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. +## Quickstart -=== Cursor +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. -Workspace: `.cursor/mcp.json`. User-global: `~/.cursor/mcp.json`. +To talk to the bridge directly over stdio, send newline-delimited JSON-RPC. Initialize, then list tools: -[source,json] ----- -{ - "mcpServers": { - "boj-server": { - "command": "npx", - "args": ["-y", "@hyperpolymath/boj-server@latest"], - "env": { "BOJ_URL": "http://localhost:7700" } - } - } -} ----- +```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 +``` -Or use Settings → MCP → *Add new MCP server*. +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`). -=== Cline (VS Code extension) +Call a tool: -Settings → Cline → MCP Servers → *Edit MCP Settings*: +```jsonc +{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", + "params": { "name": "boj_health", "arguments": {} } } +``` -[source,json] ----- -{ - "mcpServers": { - "boj-server": { - "command": "npx", - "args": ["-y", "@hyperpolymath/boj-server@latest"], - "env": { "BOJ_URL": "http://localhost:7700" } - } - } -} ----- +The server also implements `resources/list` (7 `boj://` resources) and `prompts/list`. -=== Windsurf (Codeium Cascade) +--- -Edit `~/.codeium/windsurf/mcp_config.json`: +## Capabilities overview -[source,json] ----- -{ - "mcpServers": { - "boj-server": { - "command": "npx", - "args": ["-y", "@hyperpolymath/boj-server@latest"], - "env": { "BOJ_URL": "http://localhost:7700" } - } - } -} ----- +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`. -=== Continue.dev +| 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` | -In `~/.continue/config.yaml`: +> 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. -[source,yaml] ----- -mcpServers: - - name: boj-server - command: npx - args: ["-y", "@hyperpolymath/boj-server@latest"] - env: - BOJ_URL: http://localhost:7700 ----- +### Multi-agent coordination (`coord_*`) -=== Zed +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): -Settings (`~/.config/zed/settings.json`): +- **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`. -[source,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: - -. *Run BoJ locally* — clone this repo and `just run` (see link:docs/quickstarts/USER.adoc[QUICKSTART-USER]). REST API 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 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 at a glance - -* *GitHub/GitLab* — repos, issues, PRs, code search, mirroring (22 tools) -* *Cloud* — Cloudflare (DNS, Workers, KV, R2, D1), Vercel (deployments, projects), Verpex (cPanel) -* *Communication* — Gmail, Google Calendar -* *Browser* — Firefox automation: navigate, click, type, screenshot, arbitrary JS (7 tools) -* *Code Intelligence* — CodeSeeker hybrid search + graph RAG -* *Research* — Semantic Scholar papers, citations, authors -* *ML* — Hugging Face model / dataset / inference -* *Local coordination* — `local-coord-mcp` (24 tools): multi-instance AI peer discovery, typed envelopes, claim/heartbeat/watchdog, quarantine + master/journeyman/apprentice supervision, track-record affinity, capability advertisement -* *Cartridges* — 115 pluggable cartridges across Teranga / Shield / Ayo trust tiers - -== Scope - -*115 cartridges*, organised across the domains below. Each cartridge is a formally verified Idris2 ABI + Zig FFI + Deno/JS adapter triple, reachable through a single MCP endpoint. - -[%collapsible] -.🔧 Git forges & code hosting — 4 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `github-api-mcp` | GitHub REST API — repos, issues, PRs, search -| `gitlab-api-mcp` | GitLab REST API — projects, issues, MRs -| `github-actions-mcp` | GitHub Actions — workflows, runs, jobs, artifacts, secret rotation -| `git-mcp` | Multi-forge git operations (GitHub, GitLab, Gitea, Bitbucket) -|=== - -Bridge-level tools: `boj_github_*` (14), `boj_gitlab_*` (8) — 22 explicit tools. Auth via `GITHUB_TOKEN` / `GITLAB_TOKEN` env vars. -==== - -[%collapsible] -.☁️ Cloud platforms — 10 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `cloud-mcp` | Multi-cloud session manager (AWS / GCP / Azure / DO / Vercel) -| `aws-mcp` | AWS gateway — session-based auth, per-region slots, throttle management -| `gcp-mcp` | GCP gateway — project-scoped auth, quota tracking, multi-service routing -| `cloudflare-mcp` | Cloudflare v4 — Workers, D1, KV, R2, DNS, zone settings, SSL/TLS -| `digitalocean-mcp` | DigitalOcean — droplets, volumes, domains, SSH keys, snapshots, databases -| `hetzner-mcp` | Hetzner Cloud — servers, volumes, firewalls, networks, snapshots, floating IPs -| `fly-mcp` | Fly.io Machines v1 — apps, machines, volumes, secrets, regions, IPs, certs -| `linode-mcp` | Linode/Akamai — instances, volumes, domains, NodeBalancers, StackScripts -| `railway-mcp` | Railway GraphQL v2 — projects, services, deployments, env, domains, logs -| `render-mcp` | Render REST v1 — services, deploys, env groups, custom domains, jobs -|=== - -Bridge-level tools: `boj_cloud_cloudflare`, `boj_cloud_vercel`, `boj_cloud_verpex`. Other providers reachable via `boj_cartridge_invoke`. -==== - -[%collapsible] -.🗄 Databases — 12 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `database-mcp` | Universal SQL/NoSQL gateway across multiple engines -| `postgresql-mcp` | PostgreSQL — full transaction support, connection pooling, query lifecycle -| `mongodb-mcp` | MongoDB — collection-level CRUD, aggregation pipelines, sessions -| `redis-mcp` | Redis — KV, sorted sets, pub/sub, streams, Lua scripting -| `neo4j-mcp` | Neo4j — graph database query and write -| `clickhouse-mcp` | ClickHouse — columnar queries, bulk inserts, real-time analytics -| `duckdb-mcp` | DuckDB — in-process analytics over Parquet/CSV/JSON/Arrow -| `arango-mcp` | ArangoDB — AQL queries, multi-model documents, graph traversals -| `turso-mcp` | Turso libSQL — edge SQLite, multi-DB, embedded replica sync -| `supabase-mcp` | Supabase — Postgres, Auth, Storage, Edge Functions -| `neon-mcp` | Neon — serverless Postgres, branch management, query execution -| `verisimdb-mcp` | *VeriSimDB* — verified simulation database with formal drift detection -|=== -==== - -[%collapsible] -.📦 Containers, deploy & integrity — 5 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `container-mcp` | Build / create / start / stop / remove via Podman or Docker -| `docker-hub-mcp` | Docker Hub — image search, repos, tag listing, manifests -| `k8s-mcp` | Kubernetes — namespace-scoped CRUD with lifecycle management -| `stapeln-mcp` | Stapeln stack manager — Chainguard-base composable container layers -| `vordr-mcp` | Vordr integrity monitor — BLAKE3 tamper-detection on container images -|=== -==== - -[%collapsible] -.🔁 CI/CD & observability — 8 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `buildkite-mcp` | Buildkite — pipelines, builds, jobs, artifacts -| `circleci-mcp` | CircleCI — pipelines, workflows, jobs, artifacts -| `laminar-mcp` | Laminar — minimalist CI/CD pipeline management -| `hypatia-mcp` | *Hypatia* — neurosymbolic CI security/quality/compliance scanner -| `observe-mcp` | Unified observability — metrics, logs, traces -| `grafana-mcp` | Grafana — dashboards, panel queries, alert rules, annotations -| `prometheus-mcp` | Prometheus — PromQL instant + range queries, alerts, targets -| `sentry-mcp` | Sentry — issues, events, projects, releases, deployments -|=== -==== - -[%collapsible] -.💬 Communications & messaging — 6 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `comms-mcp` | *Gmail + Google Calendar* — send, read, search, labels, events, free/busy -| `slack-mcp` | Slack — messages, channels, threads, search, users -| `discord-mcp` | Discord — messages, channel history, guilds, reactions -| `telegram-mcp` | Telegram Bot API — messages, chats, inline queries, updates -| `matrix-mcp` | Matrix — messages, room join/leave, history, membership -| `notifyhub-mcp` | Unified notify — Email, SMS, WhatsApp, Slack, Telegram, Discord -|=== - -Bridge-level tools: `boj_comms_gmail`, `boj_comms_calendar`. -==== - -[%collapsible] -.📚 Productivity & knowledge — 10 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `google-docs-mcp` | Docs — document retrieval, content, search, headings, comments -| `google-sheets-mcp` | Sheets — metadata, cell ranges, named ranges, sheet listing -| `notion-mcp` | Notion — pages, databases, blocks -| `obsidian-mcp` | Obsidian vault — note search, content, backlinks, tags, graph -| `linear-mcp` | Linear — issues, projects, cycles, labels -| `jira-mcp` | Jira — projects, issues, sprints, workflows -| `todoist-mcp` | Todoist — tasks, projects, completion, labels -| `airtable-mcp` | Airtable — bases, table schemas, record CRUD -| `zotero-mcp` | Zotero — library search, items, collections, tags -| `academic-workflow-mcp` | Academic workflow — Zotero integration, citations, paper review -|=== -==== - -[%collapsible] -.🤖 ML, AI & coordination — 8 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `ml-mcp` | *Hugging Face* + others — search, model info, inference, spaces, datasets -| `claude-ai-mcp` | Anthropic Messages API — Claude models, token counting, multi-turn -| `claude-agents-power-mcp` | Specialised AI-agent management for dev teams -| `model-router-mcp` | Task classifier — recommends opus/sonnet/haiku per task -| `echidna-llm-mcp` | LLM advisor for the ECHIDNA formal-verification engine -| `agent-mcp` | OODA-loop agent session enforcer -| `local-coord-mcp` | *Multi-instance peer discovery + typed envelopes + supervision* (21 tools) -| `local-memory-mcp` | Persistent local memory for Claude, Cursor, Codex (13 tools, no cloud) -|=== - -Bridge-level tool: `boj_ml_huggingface`. `coord_*` tools (21) wire through `local-coord-mcp` — see the dedicated section below. -==== - -[%collapsible] -.🌐 Browser & web automation — 2 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `browser-mcp` | Firefox automation via Marionette — navigate, click, type, screenshot, exec JS -| `gossamer-mcp` | Native desktop windows — panel loading, JS bridge -|=== - -Bridge-level tools: `boj_browser_*` (7) — navigate, click, type, read_page, screenshot, tabs, execute_js. -==== - -[%collapsible] -.🔍 Code intelligence & research — 5 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `codeseeker-mcp` | *CodeSeeker* — vector + BM25 + path-tier fused via RRF; KG traversal; Graph-RAG -| `coderag-mcp` | Enterprise code intelligence — graph-based analysis for AI-assisted dev -| `research-mcp` | *Semantic Scholar / OpenAlex* — papers, citations, references, authors -| `opendatamcp` | Public dataset access for LLM apps -| `origenemcp` | Biomedical platform — 600+ tools/databases (ChEMBL, PubChem, FDA, OpenTargets) -|=== - -Bridge-level tools: `boj_codeseeker`, `boj_research`. -==== - -[%collapsible] -.🛠 Developer tooling (LSP/DAP/BSP, languages, registries) — 14 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `lsp-mcp` | Generic Language Server Protocol 3.17 gateway — spawn any LSP server -| `dap-mcp` | Generic Debug Adapter Protocol gateway -| `bsp-mcp` | Generic Build Server Protocol 2.x gateway -| `lang-mcp` | Multi-language session manager — Eclexia, AffineScript, BetLang, Ephapax -| `toolchain-mcp` | Toolchain orchestrator — mint/provision/configure language toolchains -| `orchestrator-lsp-mcp` | Cross-domain LSP router across all 12 poly-*-lsp servers -| `affinescript-mcp` | *AffineScript* — type check, parse, format, lint, compile, hover, definition -| `typed-wasm-mcp` | *AffineScript → typed-wasm* at Level 7/10 ownership soundness -| `npm-registry-mcp` | npm — search, metadata, versions, downloads, dependency analysis -| `pypi-mcp` | PyPI — Python packages, search, metadata, versions, downloads -| `crates-mcp` | crates.io — Rust crates, search, metadata, versions, downloads -| `hackage-mcp` | Hackage — Haskell packages -| `hex-mcp` | Hex.pm — Elixir/Erlang packages -| `opam-mcp` | opam — OCaml packages -|=== - -Plus `opsm-mcp` (Odds-and-Sods Package Manager) routes search/install/dep-resolution across all of the above. -==== - -[%collapsible] -.🔒 Security & secrets — 7 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `secrets-mcp` | Secrets management — Vault, SOPS, env-vault -| `vault-mcp` | Vault CLI credential broker — execute, list, verify, rotate -| `sanctify-mcp` | Sanctify — PHP lint + deviation detection -| `panic-attack-mcp` | panic-attacker static analysis — dangerous patterns, banned constructs, drift -| `vext-mcp` | Vext — signed-message verification, attestation chains -| `rokur-mcp` | Rokur — Svalinn secrets GUI authorisation layer -| `dns-shield-mcp` | DNS security — DoQ, DoH, DNSSEC, CAA -|=== -==== - -[%collapsible] -.🏗 Infrastructure-as-code, config & proof — 7 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `iac-mcp` | Terraform / OpenTofu lifecycle — plan → apply → destroy with state lifecycle -| `conflow-mcp` | Conflow — configuration management -| `bofig-mcp` | Bofig — evidence graph query for investigative workflows -| `proof-mcp` | Proof verification — Lean, Coq, Agda, Isabelle, Idris2, Z3, more -| `nesy-mcp` | *Neural-symbolic* harmonisation — symbolic truth overrides neural probability -| `ephapax-mcp` | Ephapax — proof-compiler query tools for formal verification -| `pmpl-mcp` | PMPL licence chain verification + artefact hashing -|=== -==== - -[%collapsible] -.🌱 Hyperpolymath-native admin & ecosystem — 13 cartridges -==== -[cols="1,4",options="header"] -|=== -| Cartridge | Description -| `boj-health` | Self-health — status, ping, uptime -| `fleet-mcp` | gitbot-fleet gate compliance tracker -| `reposystem-mcp` | Reposystem — managed repos, health, mirrors, RSR compliance -| `007-mcp` | oo7 agent meta-language — parse/run/trace/build/test/lint -| `k9iser-mcp` | K9 contract regeneration (k9iser generate/validate/apply) -| `idaptik-admin-mcp` | IDApTIK game server administration -| `burble-admin-mcp` | Burble WebRTC server administration -| `game-admin-mcp` | Game server admin + configuration drift -| `aerie-mcp` | Aerie environment lifecycle manager -| `hesiod-mcp` | DNS lookup cartridge -| `fireflag-mcp` | Fireflag — extension-to-MCP mapping and discovery -| `kategoria-mcp` | Type-theory learning system — classification + learner evaluation -| `civic-connect-mcp` | CivicConnect community engagement platform -|=== - -Plus `feedback-mcp` (feedback collection + sentiment), `ssg-mcp` (Hugo/Zola/Astro/Casket), `ums-mcp` (Universal Map Specification level editor). -==== - -=== Bridge-level tools (41 exposed) - -A subset of cartridges have explicit `boj__` tools at the bridge for highest-frequency operations. Everything else is reachable via `boj_cartridge_invoke`: - -* *5 core*: `boj_health`, `boj_menu`, `boj_cartridges`, `boj_cartridge_info`, `boj_cartridge_invoke` -* *3 cloud*: `boj_cloud_verpex`, `boj_cloud_cloudflare`, `boj_cloud_vercel` -* *2 comms*: `boj_comms_gmail`, `boj_comms_calendar` -* *1 ML*: `boj_ml_huggingface` -* *7 browser*: `boj_browser_navigate`, `boj_browser_click`, `boj_browser_type`, `boj_browser_read_page`, `boj_browser_screenshot`, `boj_browser_tabs`, `boj_browser_execute_js` -* *14 GitHub* + *8 GitLab* -* *1 CodeSeeker*, *1 research* -* *21 coord* (see below) - -Set `BOJ_TOOL_SCOPE=core` to advertise only the discovery surface; explicit tools remain reachable via `boj_cartridge_invoke` regardless. - -== Local-coord-mcp at a glance - -Localhost multi-agent bus on `127.0.0.1:7745`. Lets multiple Claude / Gemini / Codex / Vibe sessions on the same machine discover each other, claim tasks without collision, and operate under a supervision model (master approves; journeyman executes; apprentice stays gated). - -Highlights: - -* *Peer registration* with `client_kind`, `variant` (model id — `opus-4.7`, `flash-2.5`, `leanstral`), capability class/tier/prover-strengths — `coord_register`, `coord_set_variant`, `coord_set_capabilities`, `coord_get_peer_capabilities`. -* *Typed envelopes* validated at the bridge via Nickel contracts (`coord-messages.ncl`) — `coord_send`, `coord_send_gated`. -* *Task claims* with role-based watchdog TTL (apprentice 30s / journeyman 5m / master none), heartbeats via `coord_progress`, auto-release + explicit `coord_sweep_watchdog`. -* *Track-record + reassignment* — `coord_report_outcome`, `coord_get_affinities`, `coord_scan_suggestions` (emits `overclaim` fyi + `drift` warn envelopes on confidence/affinity divergence). -* *Supervision* — `coord_review`, `coord_approve`, `coord_reject`, `coord_promote_to_master`, `coord_transfer_master`. -* *Observability* — `coord_health` snapshot of peer/quarantine/claim/reject state. - -Formally verified core in Idris2 (`cartridges/local-coord-mcp/abi/LocalCoord/`); Zig FFI; Deno/Node MCP bridge with input hardening (rate limiting, prompt-injection detection with unicode-normalisation, error sanitisation). - -=== Parallel agents and git - -"Claim tasks without collision" is a *task-level* guarantee, not a git-level one. `coord_claim` ensures two peers never own the same task-id at the same time; it does not lock files, branches, or the working tree. If two journeymen claim _different_ tasks that happen to touch the same file, vanilla git merge conflicts can still occur. - -The supported pattern for parallel work is: - -* *Branch-per-claim + per-peer worktree.* `just coord-worktree ` claims the task and provisions an isolated `git worktree` at `../-worktrees/` on branch `agent//`, so two journeymen on the same checkout never share a working tree. The recipe is a thin wrapper over `coord-tui`'s shell helper of the same name — both refuse to provision when the claim is refused by the backend. -* *Advisory path-claims.* `coord_claim_task` accepts an optional `paths` array declaring the working-tree files the claim expects to touch. The bridge keeps an in-memory map of active path-claims and annotates the response with `path_overlap` warnings (segment-aware prefix match) when another active claim covers any of those paths. *Advisory by design*: warnings never block the claim — the Idris2-verified backend remains the source of truth for task ownership, and this layer is the early-warning signal that lets the holder split the task, hand off, or accept the merge cost knowingly. -* *Master-gated integration.* `coord_approve` is the serialisation point: the master peer reviews, rebases or asks the journeyman to rebase, and merges in a defined order. Two approved branches that conflict are resolved at this step, not in the cartridge. -* *Drift signal, not lock.* `coord_scan_suggestions` emits `drift` warn envelopes when affinities or confidence diverge — that's an _advisory_ signal to re-route or split a task, not a hard lock against file overlap. - -What `local-coord-mcp` _does not_ do today: hard file-range locks, automatic rebase, or conflict resolution. The path-overlap layer is a hint, not a mutex — two journeymen can still both proceed against overlapping files and conflict at merge. Those final steps stay with the master peer (or human integrator), in line with the supervision model. If you need stricter isolation than path-claims + worktrees, partition tasks by directory before issuing them. - -=== coord-tui — human interface for local-coord-mcp - -`coord-tui` is the companion terminal UI for `local-coord-mcp`. It lives here in `coord-tui/` and also has its own dedicated repository: - -https://github.com/hyperpolymath/coord-tui - -What it provides beyond the MCP tools themselves: - -* *Live dashboard* — Peers and Claims panels in a ratatui TUI, auto-refreshed every 5 s. -* *Commands sidebar* — always-visible key reference, shell helpers, and `just coord-*` recipes (toggle with `\``). -* *Window titling* — every terminal tab shows its peer ID automatically. -* *Shell helpers* — `coord-peers`, `coord-claims`, `coord-claim`, `coord-status`, `coord-whoami` — coordination without opening the TUI. -* *One-command install* — `bash coord-tui/install.sh` sets up everything on a new machine. - -[source,bash] ----- -# New machine setup -bash coord-tui/install.sh - -# Then open your tools normally — registration and titling are automatic -claude -gemini -vibe ----- +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 + +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. + +> **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: + +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. + +> **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): + +| 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 + +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`. | -== Glama AAA posture +--- -This server targets Glama's AAA tier. Posture: +## Security -* *Inspectable* — `.mcp.json` + root `package.json` `bin` entry + shebang; offline manifest fallback so cloud inspection works without the REST backend (see `mcp-bridge/lib/offline-menu.js`). -* *Tool Definition Quality* — every tool carries purpose, usage guidance, behavioural transparency (side effects, returns, errors), and parameter semantics with enums, ranges, and patterns. A coherence test enforces a minimum description floor so the server-level score (60% mean + 40% _min_) cannot regress — see `mcp-bridge/tests/dispatch_test.js`. -* *Server Coherence* — one tool ↔ one verb; consistent `boj__` and `coord_` naming; the same test asserts the bridge tool list matches the cartridge manifest so nothing advertised is un-dispatched (or vice versa). -* *Security* — PR #27 hardening: rate limiting, size caps, prompt-injection detection with unicode-confusable normalisation, error sanitisation (strips paths, stack traces, env vars). SHA-pinned workflow actions. -* *Formal* — `cartridges/local-coord-mcp/abi/LocalCoord/*.idr` Idris2 ABI + proof obligations (P-01..P-07). +- **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). +- **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] ----- +```bash node --test mcp-bridge/tests/ ----- +``` -== Formal verification +Report vulnerabilities per [`SECURITY.md`](SECURITY.md). -BoJ's ABI safety layer is written in Idris2 with the proof obligations audited in `PROOF-NEEDS.md`. Headline posture (as of the 2026-05-18 audit): +--- -* *All P1/P2 obligations closed.* `SafePromptInjection`, `SafeCORS`, `SafeAPIKey`, `SafeWebSocket`, `SafeHTTP`, `Federation`, `Catalogue`, `CartridgeDispatch` (BJ1), `CredentialIsolation` (BJ2), `APIContractCoverage` (BJ3) — all carry constructive proofs. -* *Five remaining `believe_me` invocations*, all isolated in `src/abi/Boj/SafetyLemmas.idr`, all class (J) — _principled assumptions_, not unproven debt. They axiomatise the soundness of Idris2 0.8.0's opaque `Char`/`String` primitives (`prim__eqChar`, `prim__strToCharList`, `prim__strAppend`, `prim__strSubstr`) which have no in-language induction principle. The only reduction path is external backend-assurance evidence (Chez/BEAM extraction or property-test harness), not constructive in-language proof. -* *No unproven obligations remain in the audited surface.* The full per-site rationale and the in-progress cross-cartridge composition question are tracked in `PROOF-NEEDS.md` and `docs/decisions/`. +## License -== Citing +- **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. -If you use BoJ Server in academic work, citation metadata is in link:CITATION.cff[`CITATION.cff`]. GitHub renders a "Cite this repository" button in the sidebar from this file. +This project **does not** use AGPL; any AGPL string remaining in a build manifest is a packaging regression, not the project's license. -Per-release DOIs are available via Zenodo. To enable them: +--- -. Log in to https://zenodo.org/[zenodo.org] with your GitHub account. -. Account → GitHub → flip the *boj-server* repository toggle to on. -. Cut a new GitHub release; Zenodo auto-archives it and mints a DOI. -. Add the DOI badge to this README. -. Update the `doi:` field in `CITATION.cff` to match. +## Contributing & links -== License +- **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. -MPL-2.0 — see link:LICENSE[LICENSE]. +Maintained by Jonathan D.A. Jewell. diff --git a/coord-tui/Cargo.toml b/coord-tui/Cargo.toml index 9e7639ba..ba5e6447 100644 --- a/coord-tui/Cargo.toml +++ b/coord-tui/Cargo.toml @@ -6,7 +6,7 @@ version = "0.1.0" edition = "2021" authors = ["Jonathan D.A. Jewell "] description = "Rapid-setup TUI for BoJ local-coord-mcp (AI multi-instance coordination)" -license = "AGPL-3.0-or-later" +license = "MPL-2.0" # Architecture note: pure functions (state transitions, key dispatch) are # deliberately isolated so SPARK/Ada formal modules can replace them later diff --git a/elixir/mix.exs b/elixir/mix.exs index 3de92915..c3925b5b 100644 --- a/elixir/mix.exs +++ b/elixir/mix.exs @@ -43,7 +43,7 @@ defmodule BojRest.MixProject do defp package do [ - licenses: ["AGPL-3.0-or-later"], + licenses: ["MPL-2.0"], links: %{"GitHub" => "https://github.com/hyperpolymath/boj-server"} ] end diff --git a/mcp-bridge/main.js b/mcp-bridge/main.js index dbaec208..7e8c260c 100755 --- a/mcp-bridge/main.js +++ b/mcp-bridge/main.js @@ -1,4 +1,4 @@ -#!/usr/bin/env -S deno run --allow-net --allow-env --allow-read +#!/usr/bin/env node // SPDX-License-Identifier: MPL-2.0 // Copyright (c) Jonathan D.A. Jewell // diff --git a/package.json b/package.json index 396ed9d0..7c4502b6 100644 --- a/package.json +++ b/package.json @@ -1,9 +1,15 @@ { "name": "@hyperpolymath/boj-server", "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": "AGPL-3.0-or-later", + "description": "Bundle of Joy (BoJ) MCP Server — cartridge-based DevOps + multi-agent coordination toolkit with 125 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 ", + "files": [ + "mcp-bridge/", + "README.md", + "LICENSE", + "NOTICE" + ], "repository": { "type": "git", "url": "https://github.com/hyperpolymath/boj-server.git" diff --git a/tools/cartridge-configurator/package.json b/tools/cartridge-configurator/package.json index f3f64fdd..22c9db34 100644 --- a/tools/cartridge-configurator/package.json +++ b/tools/cartridge-configurator/package.json @@ -8,6 +8,6 @@ }, "keywords": ["boj-server", "cartridge", "configurator"], "author": "Jonathan D.A. Jewell (hyperpolymath) ", - "license": "AGPL-3.0-or-later", + "license": "MPL-2.0", "type": "module" } diff --git a/tools/cartridge-provisioner/package.json b/tools/cartridge-provisioner/package.json index 2f693189..201cab4a 100644 --- a/tools/cartridge-provisioner/package.json +++ b/tools/cartridge-provisioner/package.json @@ -8,6 +8,6 @@ }, "keywords": ["boj-server", "cartridge", "provisioner"], "author": "Jonathan D.A. Jewell (hyperpolymath) ", - "license": "AGPL-3.0-or-later", + "license": "MPL-2.0", "type": "module" } diff --git a/tools/panel-harness/package.json b/tools/panel-harness/package.json index 87cc3e4a..1920db58 100644 --- a/tools/panel-harness/package.json +++ b/tools/panel-harness/package.json @@ -8,6 +8,6 @@ }, "keywords": ["boj-server", "cartridge", "panel-harness"], "author": "Jonathan D.A. Jewell (hyperpolymath) ", - "license": "AGPL-3.0-or-later", + "license": "MPL-2.0", "type": "module" } diff --git a/tray/Cargo.toml b/tray/Cargo.toml index 9607152d..126da6ac 100644 --- a/tray/Cargo.toml +++ b/tray/Cargo.toml @@ -10,7 +10,7 @@ version = "0.2.0" edition = "2021" description = "System tray app for BoJ server — Gossamer webview shell" authors = ["Jonathan D.A. Jewell "] -license = "AGPL-3.0-or-later" +license = "MPL-2.0" [[bin]] name = "boj-tray" From 14a43ee60efd790e3af3c327d2895e24dd827d5a Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 09:25:12 +0100 Subject: [PATCH 3/5] docs(metadata): reconcile cartridge/tool/version counts to one source of truth Single source of truth: 125 cartridges (= the cartridge.json count and what the live boj_menu reports), 68 MCP tools (45 boj_* + 23 coord_*), v0.4.7. - Cartridge count -> 125 across: jsr.json, smithery.yaml, ai-plugin.json, openapi.yaml, CITATION.cff, site/index.md, .github/settings.yml, Intentfile.a2ml, README.adoc, mcp-bridge/lib/offline-menu.js, and docs/{glama/CAPABILITIES,glama/RESOURCES,EXPLAINME,quickstarts/USER, developer/llm-warmup-dev,developer/llm-warmup-user,index.html}. - smithery.yaml: complete the static `tools:` table from 18 entries to all 68 (generated from the live tools/list). - docs/glama/CAPABILITIES.md: replace the inflated "1041 Tools" with the honest "68 MCP Tools" framing. - Version -> 0.4.7: smithery.yaml, mcp-bridge/lib/version.js, CITATION.cff, openapi.yaml, docs/specification/openapi.yaml. Dated 2026-04-30 measurement snapshots (ROADMAP/architecture/TEST-NEEDS), ADR records, and the "115 lines" code line-counts are intentionally left untouched (they need re-measurement, not a number swap). Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/settings.yml | 2 +- .../contractiles/intend/Intentfile.a2ml | 2 +- CITATION.cff | 4 +- README.adoc | 6 +- ai-plugin.json | 4 +- docs/EXPLAINME.adoc | 8 +- docs/developer/llm-warmup-dev.adoc | 6 +- docs/developer/llm-warmup-user.adoc | 2 +- docs/glama/CAPABILITIES.md | 4 +- docs/glama/RESOURCES.md | 2 +- docs/index.html | 2 +- docs/quickstarts/USER.adoc | 4 +- docs/specification/openapi.yaml | 2 +- jsr.json | 2 +- mcp-bridge/lib/offline-menu.js | 4 +- mcp-bridge/lib/version.js | 2 +- openapi.yaml | 4 +- site/index.md | 2 +- smithery.yaml | 152 +++++++++++++++--- 19 files changed, 157 insertions(+), 57 deletions(-) diff --git a/.github/settings.yml b/.github/settings.yml index 8e56b10b..d7119250 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -11,7 +11,7 @@ repository: name: "boj-server" - description: "BoJ (Bundle of Joy) — unified MCP server consolidating GitHub, GitLab, Cloudflare, browser automation, and 50+ open-source cartridges" + description: "BoJ (Bundle of Joy) — unified MCP server consolidating GitHub, GitLab, Cloudflare, browser automation, and 125 open-source cartridges" homepage: "https://github.com/hyperpolymath/boj-server" private: false has_issues: true diff --git a/.machine_readable/contractiles/intend/Intentfile.a2ml b/.machine_readable/contractiles/intend/Intentfile.a2ml index 9f23388e..fc1e7374 100644 --- a/.machine_readable/contractiles/intend/Intentfile.a2ml +++ b/.machine_readable/contractiles/intend/Intentfile.a2ml @@ -18,7 +18,7 @@ LLM/SLM agents: understand what this repo IS and IS NOT before acting. BoJ (Bundle of Joy) is a unified MCP server that consolidates all hyperpolymath tooling into a single endpoint. It provides Claude Code integration for GitHub, GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, -ML, and 50+ open-source cartridges. It implements a three-class architecture: +ML, and 125 open-source cartridges. It implements a three-class architecture: - Class 1 (Simple Track): zero-infrastructure CLI/curl workflows - Class 2 (Orchestrator Track): HMAC-SHA256 webhooks and real-time MQTT/WS - Class 3 (Multiplier Track): Elixir/BEAM mass concurrency diff --git a/CITATION.cff b/CITATION.cff index 5490c6d1..c6efca35 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -18,7 +18,7 @@ abstract: >- gateway. Each cartridge — covering databases, container runtimes, git forges, Kubernetes, observability, secrets, IaC, cloud providers, and multi-instance AI coordination — is a formally verified Idris2 ABI + Zig FFI + Deno/JS - adapter triple. The server exposes 115 cartridges through a unified stdio + adapter triple. The server exposes 125 cartridges through a unified stdio MCP surface plus a local REST API on port 7700. A local-coord-mcp cartridge provides loopback peer discovery, typed envelopes, claim/heartbeat/watchdog, and master/journeyman/apprentice supervision for multi-agent AI workflows. @@ -34,5 +34,5 @@ keywords: - multi-agent - ai-coordination license: MPL-2.0 -version: 0.4.6 +version: 0.4.7 date-released: "2026-04-27" diff --git a/README.adoc b/README.adoc index e10ae78c..1d484b9a 100644 --- a/README.adoc +++ b/README.adoc @@ -13,7 +13,7 @@ image:https://glama.ai/mcp/servers/hyperpolymath/boj-server/badge[Glama MCP Serv image:https://api.thegreenwebfoundation.org/greencheckimage/boj-server.net[Green Hosting,link="https://www.thegreenwebfoundation.org/green-web-check/?url=boj-server.net"] image:https://archive.softwareheritage.org/badge/origin/https://github.com/hyperpolymath/boj-server/[Software Heritage,link="https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/boj-server"] -BoJ (Bundle of Joy) is a unified MCP server that consolidates all hyperpolymath tooling into a single endpoint — GitHub, GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, ML, and 115 open-source cartridges. +BoJ (Bundle of Joy) is a unified MCP server that consolidates all hyperpolymath tooling into a single endpoint — GitHub, GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, ML, and 125 open-source cartridges. == Install @@ -224,11 +224,11 @@ Glama listing: https://glama.ai/mcp/servers/hyperpolymath/boj-server * *Research* — Semantic Scholar papers, citations, authors * *ML* — Hugging Face model / dataset / inference * *Local coordination* — `local-coord-mcp` (24 tools): multi-instance AI peer discovery, typed envelopes, claim/heartbeat/watchdog, quarantine + master/journeyman/apprentice supervision, track-record affinity, capability advertisement -* *Cartridges* — 115 pluggable cartridges across Teranga / Shield / Ayo trust tiers +* *Cartridges* — 125 pluggable cartridges across Teranga / Shield / Ayo trust tiers == Scope -*115 cartridges*, organised across the domains below. Each cartridge is a formally verified Idris2 ABI + Zig FFI + Deno/JS adapter triple, reachable through a single MCP endpoint. +*125 cartridges*, organised across the domains below. Each cartridge is a formally verified Idris2 ABI + Zig FFI + Deno/JS adapter triple, reachable through a single MCP endpoint. [%collapsible] .🔧 Git forges & code hosting — 4 cartridges diff --git a/ai-plugin.json b/ai-plugin.json index a8ec866d..cb94731c 100644 --- a/ai-plugin.json +++ b/ai-plugin.json @@ -2,8 +2,8 @@ "schema_version": "v1", "name_for_human": "Bundle of Joy Server", "name_for_model": "boj_server", - "description_for_human": "Cartridge-based DevOps toolkit with 115 formally verified domain cartridges spanning database, cloud, git, Kubernetes, containers, observability, secrets, IaC, ML, browser automation, communications, and research.", - "description_for_model": "A cartridge-based MCP server exposing 115 DevOps domain cartridges via a unified REST API. Each cartridge has a formally verified Idris2 ABI, Zig FFI bridge, and Deno/JS adapter. Domains include: database (VeriSimDB, PostgreSQL, Redis, DuckDB, MongoDB, Neo4j, ClickHouse, Turso, Supabase, Neon, ArangoDB), cloud providers (AWS, GCP, Cloudflare, Vercel, Verpex, DigitalOcean, Hetzner, Fly.io, Railway, Render, Linode), git forges (GitHub, GitLab), Kubernetes, containers, observability, secrets/vault, IaC, ML/AI (HuggingFace), browser automation (Firefox), communications (Gmail, Calendar), queues, SSG, research (academic papers), and language tooling. Use boj_menu to discover available cartridges, boj_cartridge_info to inspect a cartridge, and boj_cartridge_invoke to call operations.", + "description_for_human": "Cartridge-based DevOps toolkit with 125 formally verified domain cartridges spanning database, cloud, git, Kubernetes, containers, observability, secrets, IaC, ML, browser automation, communications, and research.", + "description_for_model": "A cartridge-based MCP server exposing 125 DevOps domain cartridges via a unified REST API. Each cartridge has a formally verified Idris2 ABI, Zig FFI bridge, and Deno/JS adapter. Domains include: database (VeriSimDB, PostgreSQL, Redis, DuckDB, MongoDB, Neo4j, ClickHouse, Turso, Supabase, Neon, ArangoDB), cloud providers (AWS, GCP, Cloudflare, Vercel, Verpex, DigitalOcean, Hetzner, Fly.io, Railway, Render, Linode), git forges (GitHub, GitLab), Kubernetes, containers, observability, secrets/vault, IaC, ML/AI (HuggingFace), browser automation (Firefox), communications (Gmail, Calendar), queues, SSG, research (academic papers), and language tooling. Use boj_menu to discover available cartridges, boj_cartridge_info to inspect a cartridge, and boj_cartridge_invoke to call operations.", "auth": { "type": "none" }, diff --git a/docs/EXPLAINME.adoc b/docs/EXPLAINME.adoc index 6971fa16..d949d3ef 100644 --- a/docs/EXPLAINME.adoc +++ b/docs/EXPLAINME.adoc @@ -19,7 +19,7 @@ This is the Model-Controller-Processor pattern: cartridges are pluggable service **Location**: `elixir/lib/boj_rest/catalog.ex` (Elixir GenServer cartridge discovery and initialization) -**How verified**: `BojRest.Catalog` scans `cartridges/*/cartridge.json` at startup, reads tool schemas from each, and stores them in an ETS table. It validates `name`, `version`, `tools` required fields and prevents duplicate names. 115 cartridges are auto-discovered. This enables the "unified endpoint" claim: a single REST server exposes the union of all cartridges' tools without hardcoding each one. +**How verified**: `BojRest.Catalog` scans `cartridges/*/cartridge.json` at startup, reads tool schemas from each, and stores them in an ETS table. It validates `name`, `version`, `tools` required fields and prevents duplicate names. 125 cartridges are auto-discovered. This enables the "unified endpoint" claim: a single REST server exposes the union of all cartridges' tools without hardcoding each one. **Caveat**: Auto-discovery is runtime dynamic; there is no compile-time verification that all cartridge schemas are valid JSON Schema. A malformed `cartridge.json` is silently skipped at startup. The authoritative manifest format is Nickel (closed decision `boj-cartridge-manifest-format-dd.md`); migration from JSON is future work. @@ -42,7 +42,7 @@ This is the Model-Controller-Processor pattern: cartridges are pluggable service | gossamer, burble, ephapax, hypatia, verisimdb, typed-wasm — universal ABI/FFI pattern across the estate | *Pluggable cartridge architecture* -| 115 cartridge directories (`cartridges/*/`), each with `abi/`, `ffi/`, `mod.js` structure; auto-discovered at startup via manifest scan +| 125 cartridge directories (`cartridges/*/`), each with `abi/`, `ffi/`, `mod.js` structure; auto-discovered at startup via manifest scan | echidna (prover orchestration as cartridges), hypatia (rule composition), gitbot-fleet (bot cartridges per service) | *PanLL ReScript workspace layer* @@ -50,7 +50,7 @@ This is the Model-Controller-Processor pattern: cartridges are pluggable service | idaptik (game UI panels), gossamer-powered SPAs, PanLL monorepo panels estate-wide | *panic-attack security gate* -| Pre-commit `panic-attack assail` enforces PA001-PA025 across all 115 cartridges; security module tests cover injection, unicode bypass, SSRF +| Pre-commit `panic-attack assail` enforces PA001-PA025 across all 125 cartridges; security module tests cover injection, unicode bypass, SSRF | Every RSR repo in the estate; panicbot wraps it in CI | *Elixir/BEAM + Deno runtime* @@ -70,7 +70,7 @@ This is the Model-Controller-Processor pattern: cartridges are pluggable service | `elixir/lib/boj_rest/js_worker.ex` | GenServer wrapping a single Deno port; newline-delimited JSON protocol | `elixir/lib/boj_rest/node_key.ex` | X25519 keypair persistence; ChaCha20-Poly1305 credential decryption | `elixir/priv/js_pool_worker.js` | Deno-side pool worker; module cache, env isolation per request -| `cartridges/*/` | 115 cartridge directories, each with abi/, ffi/, mod.js structure +| `cartridges/*/` | 125 cartridge directories, each with abi/, ffi/, mod.js structure | `src/abi/Boj/` | Idris2 ABI definitions (Protocol, Domain, Catalogue, Safety, etc.) | `panll/` | ReScript/TEA panel framework for UI workspace layer |=== diff --git a/docs/developer/llm-warmup-dev.adoc b/docs/developer/llm-warmup-dev.adoc index a9162d87..7d0889c4 100644 --- a/docs/developer/llm-warmup-dev.adoc +++ b/docs/developer/llm-warmup-dev.adoc @@ -83,7 +83,7 @@ elixir/ Elixir/BEAM REST server test/ 50 ExUnit tests (catalog, router, crypto, JS dispatch) config/ config.exs / test.exs -cartridges/ 115 cartridge directories +cartridges/ 125 cartridge directories database-mcp/ Example cartridge abi/database-mcp.ipkg Idris2 ABI abi/Database/Mcp.idr Idris2 source @@ -134,7 +134,7 @@ panll/src/ PanLL panel (ReScript/TEA) ---- just build # Build all Zig FFI layers (catalogue + cartridges) just build-release # Optimized build (-Doptimize=ReleaseFast) -just run # Start Elixir/BEAM server (REST 7700, auto-discovers 115 cartridges) +just run # Start Elixir/BEAM server (REST 7700, auto-discovers 125 cartridges) just serve # Server + Cloudflare tunnel just test # Elixir ExUnit test suite (mix test) just test-smoke # Quick: typecheck core ABI + ExUnit smoke @@ -229,7 +229,7 @@ POST /cartridge/{name}/invoke: { "tool": "...", "args": {...}, "credential_envel == Cartridge Matrix -115 cartridges organized in a 2D matrix (Protocol x Domain). +125 cartridges organized in a 2D matrix (Protocol x Domain). Each has: `abi/` (Idris2), `ffi/` (Zig), `mod.js` (Deno adapter). View status: `just matrix` diff --git a/docs/developer/llm-warmup-user.adoc b/docs/developer/llm-warmup-user.adoc index c9bae1c5..47e137d4 100644 --- a/docs/developer/llm-warmup-user.adoc +++ b/docs/developer/llm-warmup-user.adoc @@ -83,7 +83,7 @@ and many more. | Elixir REST server (Catalog, Router, JsWorkerPool) | `cartridges/` -| 115 cartridge directories +| 125 cartridge directories |=== diff --git a/docs/glama/CAPABILITIES.md b/docs/glama/CAPABILITIES.md index a70f1039..8fe42601 100644 --- a/docs/glama/CAPABILITIES.md +++ b/docs/glama/CAPABILITIES.md @@ -13,8 +13,8 @@ Copyright (c) Jonathan D.A. Jewell - **gRPC**: gRPC support for high-performance clients ### Cartridge System -- **115 Cartridges**: Covering databases, git, cloud, comms, ML, browser, and more -- **1041 Tools**: Specialized operations across all domains +- **125 Cartridges**: Covering databases, git, cloud, comms, ML, browser, and more +- **68 MCP Tools**: 45 boj_* discovery/domain tools + 23 coord_* tools; per-cartridge operations are reachable via boj_cartridge_invoke across the 125-cartridge catalogue - **Hot-Reloading**: Add/remove cartridges without restarting - **Isolation**: Each cartridge runs in its own sandbox diff --git a/docs/glama/RESOURCES.md b/docs/glama/RESOURCES.md index 83f3d964..e3edacb0 100644 --- a/docs/glama/RESOURCES.md +++ b/docs/glama/RESOURCES.md @@ -44,7 +44,7 @@ Factual statements about entities with temporal validity. { "id": "obs_456", "entity_id": "ent_123", - "content": "BoJ Server supports 115 cartridges", + "content": "BoJ Server supports 125 cartridges", "source": "documentation", "valid_from": "2026-01-01T00:00:00Z", "valid_to": null, diff --git a/docs/index.html b/docs/index.html index 2da63024..b3a0f10e 100644 --- a/docs/index.html +++ b/docs/index.html @@ -53,7 +53,7 @@

Install

What It Does

BoJ (Bundle of Joy) consolidates GitHub, GitLab, Cloudflare, Vercel, Verpex, -Gmail, Calendar, browser automation, research, ML, and 50+ open-source cartridges +Gmail, Calendar, browser automation, research, ML, and 125 open-source cartridges into a single MCP server endpoint for AI assistants.

Capabilities

diff --git a/docs/quickstarts/USER.adoc b/docs/quickstarts/USER.adoc index 636ae1a5..86e45480 100644 --- a/docs/quickstarts/USER.adoc +++ b/docs/quickstarts/USER.adoc @@ -10,7 +10,7 @@ toc::[] == What is BoJ Server? -Bundle of Joy (BoJ) Server is a cartridge-based MCP protocol gateway. Each cartridge (database-mcp, fleet-mcp, nesy-mcp, etc.) is a formally verified Idris2 ABI + Zig FFI + Deno/JS adapter triple. The server exposes REST (port 7700) via Elixir/BEAM with Zig FFI for `.so` cartridges and a persistent Deno worker pool for JS cartridges. 115 cartridges cover databases, clouds, messaging, CI/CD, git forges, secrets, queues, proofs, and more. +Bundle of Joy (BoJ) Server is a cartridge-based MCP protocol gateway. Each cartridge (database-mcp, fleet-mcp, nesy-mcp, etc.) is a formally verified Idris2 ABI + Zig FFI + Deno/JS adapter triple. The server exposes REST (port 7700) via Elixir/BEAM with Zig FFI for `.so` cartridges and a persistent Deno worker pool for JS cartridges. 125 cartridges cover databases, clouds, messaging, CI/CD, git forges, secrets, queues, proofs, and more. Three-class architecture: Class 1 (simple CLI), Class 2 (orchestrator with webhooks/MQTT), Class 3 (BEAM multiplier for global scale). @@ -76,7 +76,7 @@ Start the Elixir/BEAM server: just run ---- -This starts the BEAM application, auto-discovers all 115 cartridges, and launches the Deno worker pool for JS dispatch: +This starts the BEAM application, auto-discovers all 125 cartridges, and launches the Deno worker pool for JS dispatch: - REST API on http://localhost:7700 diff --git a/docs/specification/openapi.yaml b/docs/specification/openapi.yaml index 8a269526..07ed528b 100644 --- a/docs/specification/openapi.yaml +++ b/docs/specification/openapi.yaml @@ -11,7 +11,7 @@ openapi: 3.1.0 info: title: BoJ Server REST API - version: 0.4.6 + version: 0.4.7 summary: Formally verified cartridge server for cloud infrastructure, databases, git, containers, and more. description: | BoJ (Bundle of Joy) Server is a cartridge-based infrastructure management diff --git a/jsr.json b/jsr.json index 58d58d18..8eed6017 100644 --- a/jsr.json +++ b/jsr.json @@ -1,7 +1,7 @@ { "name": "@hyperpolymath/boj-server", "version": "0.4.7", - "description": "Bundle of Joy — cartridge-based MCP server with 100 domain cartridges, formally verified (Idris2) coord core", + "description": "Bundle of Joy — cartridge-based MCP server with 125 domain cartridges, formally verified (Idris2) coord core", "license": "MPL-2.0", "exports": "./mcp-bridge/main.js", "publish": { diff --git a/mcp-bridge/lib/offline-menu.js b/mcp-bridge/lib/offline-menu.js index b597cfa1..bb6fab31 100644 --- a/mcp-bridge/lib/offline-menu.js +++ b/mcp-bridge/lib/offline-menu.js @@ -47,9 +47,9 @@ export const OFFLINE_MENU = { tier_ayo: [ { name: "local-coord-mcp", version: "0.9.0", domain: "Agent", protocols: ["MCP","Agentic"], status: "Available", available: true, notes: "Localhost-only (127.0.0.1:7745) multi-instance AI coordination — peer discovery, typed envelopes, task claiming, master/journeyman/apprentice supervision with quarantine + watchdog TTL + track-record affinity + capability advertisement" }, ], - // `total` reflects the full cartridges/ directory (100 cartridges on disk); + // `total` reflects the full cartridges/ directory (125 cartridges on disk); // the tier_* arrays above enumerate the named ones exposed through the // offline menu. Regenerate counts with // `node mcp-bridge/lib/generate-offline-menu.js`. - summary: { total: 100, ready: 24, mounted: 0 }, + summary: { total: 125, ready: 24, mounted: 0 }, }; diff --git a/mcp-bridge/lib/version.js b/mcp-bridge/lib/version.js index 6a82591e..0bf66a70 100644 --- a/mcp-bridge/lib/version.js +++ b/mcp-bridge/lib/version.js @@ -4,4 +4,4 @@ // Single source of truth for server version and name. export const SERVER_NAME = "boj-server"; -export const SERVER_VERSION = "0.4.2"; +export const SERVER_VERSION = "0.4.7"; diff --git a/openapi.yaml b/openapi.yaml index dc2bfab8..9984425b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9,11 +9,11 @@ openapi: "3.1.0" info: title: Bundle of Joy Server API description: | - Cartridge-based DevOps toolkit with 115 formally verified domain cartridges. + Cartridge-based DevOps toolkit with 125 formally verified domain cartridges. Each cartridge has an Idris2 ABI (dependent type proofs), Zig FFI bridge, and HTTP adapter. The REST API at port 7700 provides discovery, inspection, and invocation of all cartridges. - version: "0.4.6" + version: "0.4.7" contact: name: Jonathan D.A. Jewell email: j.d.a.jewell@open.ac.uk diff --git a/site/index.md b/site/index.md index 2955b831..3b4f43f6 100644 --- a/site/index.md +++ b/site/index.md @@ -11,7 +11,7 @@ date: 2026-03-31 The public web home for this project is [boj-server.net](https://boj-server.net). -BoJ (Bundle of Joy) is a unified MCP server that consolidates all hyperpolymath tooling into a single endpoint — GitHub, GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, ML, and 50+ open-source cartridges. +BoJ (Bundle of Joy) is a unified MCP server that consolidates all hyperpolymath tooling into a single endpoint — GitHub, GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, ML, and 125 open-source cartridges. ## Project Links diff --git a/smithery.yaml b/smithery.yaml index 6eca6330..837cc82b 100644 --- a/smithery.yaml +++ b/smithery.yaml @@ -5,8 +5,8 @@ # https://smithery.ai name: boj-server -description: "Bundle of Joy — cartridge-based MCP server with 115 formally verified domain cartridges (database, cloud, git, k8s, containers, observability, secrets, IaC, and more)" -version: "0.4.6" +description: "Bundle of Joy — cartridge-based MCP server with 125 formally verified domain cartridges (database, cloud, git, k8s, containers, observability, secrets, IaC, and more)" +version: "0.4.7" author: "Jonathan D.A. Jewell" license: "MPL-2.0" homepage: "https://github.com/hyperpolymath/boj-server" @@ -31,41 +31,141 @@ server: tools: - name: boj_health - description: "Check BoJ server health status" + description: "Ping the BoJ server and report liveness." - name: boj_menu - description: "List all 115 cartridges with domains, protocols, and tiers" + description: "List every installed BoJ cartridge grouped by trust tier (Teranga, Shield, Ayo) with name, version, domain, support..." - name: boj_cartridges - description: "Show the cartridge matrix — protocol x domain grid" + description: "Return the BoJ capability matrix — a `protocol × domain` grid marking which cartridges serve each combination (e.g." - name: boj_cartridge_info - description: "Get detailed info about a specific cartridge" + description: "Return the full manifest of a single cartridge." - name: boj_cartridge_invoke - description: "Invoke a cartridge operation" + description: "Generic cartridge invocation — forward a typed command to a specific cartridge's REST endpoint and return its JSON..." + - name: boj_cloud_verpex + description: "Manage Verpex (cPanel UAPI) hosting resources including domains, DNS records, email accounts, MySQL databases, SSL..." - name: boj_cloud_cloudflare - description: "Manage Cloudflare Workers, D1, KV, R2, DNS" + description: "Manage Cloudflare edge resources including Workers scripts, D1 SQLite databases, KV namespaces, R2 object buckets,..." - name: boj_cloud_vercel - description: "Manage Vercel deployments, domains, env vars" - - name: boj_cloud_verpex - description: "Manage Verpex cPanel hosting" + description: "Manage Vercel projects, deployments, custom domains, environment variables, build logs, and serverless functions." + - name: boj_comms_gmail + description: "Gmail operations via the comms-mcp cartridge including send, read, search, and label management." + - name: boj_comms_calendar + description: "Google Calendar operations via the comms-mcp cartridge — list upcoming events, create new events, and check free/bu..." + - name: boj_ml_huggingface + description: "Hugging Face Hub operations via the ml-mcp cartridge — search models/datasets/spaces, fetch model cards, and run ho..." + - name: boj_browser_navigate + description: "Drive the controlled Firefox session to a new URL." + - name: boj_browser_click + description: "Click the first element matching a CSS selector on the current page." + - name: boj_browser_type + description: "Type literal text into the first input, textarea, or contenteditable element matching a CSS selector." + - name: boj_browser_read_page + description: "Extract the visible text content of the active tab." + - name: boj_browser_screenshot + description: "Capture a PNG screenshot of the active tab's current viewport." + - name: boj_browser_tabs + description: "Manage browser tabs within the active session." + - name: boj_browser_execute_js + description: "Execute a JavaScript snippet in the context of the active tab and return the value of the last expression." - name: boj_github_list_repos - description: "List GitHub repositories" + description: "List repositories owned by or accessible to the authenticated GitHub user." + - name: boj_github_get_repo + description: "Fetch detailed metadata for a single GitHub repository." - name: boj_github_create_issue - description: "Create GitHub issues" + description: "Open a new issue on a GitHub repository." + - name: boj_github_list_issues + description: "List issues on a GitHub repository, filtered by state (open, closed, all)." + - name: boj_github_get_issue + description: "Fetch a single issue's full details." + - name: boj_github_comment_issue + description: "Post a new Markdown comment on a GitHub issue." - name: boj_github_create_pr - description: "Create GitHub pull requests" + description: "Open a pull request between two branches." + - name: boj_github_list_prs + description: "List pull requests on a GitHub repository, filtered by state." + - name: boj_github_get_pr + description: "Fetch a single pull request's detailed metadata." + - name: boj_github_merge_pr + description: "Merge a pull request into the base branch." + - name: boj_github_search_code + description: "Search code across GitHub using the Code Search API v2." + - name: boj_github_search_issues + description: "Search issues and pull requests across GitHub." + - name: boj_github_get_file + description: "Read a file's contents from a GitHub repository at a specific branch, tag, or commit." + - name: boj_github_graphql + description: "Execute an arbitrary GitHub GraphQL v4 query." - name: boj_gitlab_list_projects - description: "List GitLab projects" - - name: boj_browser_navigate - description: "Navigate Firefox browser" - - name: boj_browser_screenshot - description: "Take browser screenshots" - - name: boj_comms_gmail - description: "Gmail operations" - - name: boj_ml_huggingface - description: "HuggingFace model search and inference" - - name: boj_research - description: "Academic paper search and citations" + description: "List GitLab projects accessible to the authenticated user." + - name: boj_gitlab_get_project + description: "Fetch metadata for a single GitLab project." + - name: boj_gitlab_create_issue + description: "Open a new issue on a GitLab project." + - name: boj_gitlab_list_issues + description: "List issues on a GitLab project, filtered by state." + - name: boj_gitlab_create_mr + description: "Open a merge request (MR) on a GitLab project." + - name: boj_gitlab_list_mrs + description: "List merge requests on a GitLab project, filtered by state." + - name: boj_gitlab_list_pipelines + description: "List recent CI/CD pipelines for a GitLab project." + - name: boj_gitlab_setup_mirror + description: "Configure a GitLab project to mirror its repository to an external URL." - name: boj_codeseeker - description: "CodeSeeker code intelligence — hybrid search (vector + text + path), knowledge graph traversal, coding patterns, Graph RAG" + description: "CodeSeeker hybrid code-intelligence cartridge providing vector + BM25 + path-tier search fused via RRF, knowledge-g..." + - name: boj_research + description: "Academic literature search via the research-mcp cartridge — access papers, citations, references, and author profil..." + - name: boj_search + description: "Web search across four providers (Tavily, Brave, Exa, Perplexity) behind a single cartridge." + - name: boj_vector + description: "Vector database + RAG operations across four providers (Pinecone, Weaviate, Qdrant, ChromaDB) behind a single cartr..." + - name: boj_multimodal + description: "Multi-modal audio/image/video operations across four cartridges: whisper-mcp (STT), elevenlabs-mcp (TTS + voice clo..." + - name: coord_register + description: "Register this AI instance as a coordination peer on the loopback coord bus (127.0.0.1:7745)." + - name: coord_list_peers + description: "List all currently-registered peers on the coord bus." + - name: coord_send + description: "Send a free-form (untyped) message to a specific peer or broadcast to all active peers." + - name: coord_receive + description: "Dequeue the next message from this peer's FIFO inbox." + - name: coord_claim_task + description: "Attempt mutex-style ownership of a named task." + - name: coord_status + description: "Set this peer's current work-status string, visible to all other peers via `coord_list_peers`." + - name: coord_promote_to_master + description: "Promote this peer from journeyman/apprentice to the master role." + - name: coord_send_gated + description: "Send a Nickel-contract-validated envelope with a declared risk tier (0-4)." + - name: coord_review + description: "List all currently-quarantined envelopes awaiting a master/journeyman decision." + - name: coord_review_entry + description: "Read the full body and metadata of a single quarantined envelope." + - name: coord_approve + description: "Approve a quarantined envelope, delivering the original message to its target." + - name: coord_reject + description: "Reject a quarantined envelope with a human-readable reason." + - name: coord_report_outcome + description: "Record the outcome of a completed claim or attempted operation against an affinity tag." + - name: coord_get_affinities + description: "Return the computed `effective_affinity` scores for all known (client_kind, tag) pairs." + - name: coord_set_declared_affinities + description: "Update this peer's self-reported strength tags." + - name: coord_scan_suggestions + description: "Trigger a pass of the reassignment scanner to compare track records against declared affinities." + - name: coord_transfer_master + description: "Pass authority from the current master to a named successor." + - name: coord_set_variant + description: "Set or update this peer's free-form model/variant label." + - name: coord_set_capabilities + description: "Advertise this peer's capability profile including class, tier, and prover strengths." + - name: coord_get_peer_capabilities + description: "Read another peer's advertised capability profile." + - name: coord_health + description: "Fetch a read-only operational snapshot of the coordination bus." + - name: coord_progress + description: "Signal activity and refresh the watchdog TTL for a held claim." + - name: coord_sweep_watchdog + description: "Perform an explicit watchdog tick to release expired claims." install: npm: "@hyperpolymath/boj-server" From 39c6118e1d4d0229f8331bfc36d1f6566e125d16 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 10:42:33 +0100 Subject: [PATCH 4/5] chore(site,readme): SonarCloud badges + canon site/security.txt - README.md + site/index.html: SonarCloud quality-gate badge. - site/.well-known/security.txt (the served one): Expires 2027, Canonical -> boj-server.net, drop bogus Hiring link (matches the root fix in #258). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 1 + site/.well-known/security.txt | 5 ++--- site/index.html | 1 + 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 12225fc1..cfe303d2 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell [![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) > **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. diff --git a/site/.well-known/security.txt b/site/.well-known/security.txt index 2a237e25..89b2526e 100644 --- a/site/.well-known/security.txt +++ b/site/.well-known/security.txt @@ -3,8 +3,7 @@ # https://securitytxt.org/ Contact: mailto:j.d.a.jewell@open.ac.uk -Expires: 2026-12-31T23:59:59.000Z +Expires: 2027-12-31T23:59:59.000Z Preferred-Languages: en -Canonical: https://github.com/hyperpolymath/boj-server/.well-known/security.txt +Canonical: https://boj-server.net/.well-known/security.txt Policy: https://github.com/hyperpolymath/boj-server/blob/main/SECURITY.md -Hiring: https://github.com/hyperpolymath/boj-server/careers diff --git a/site/index.html b/site/index.html index 84942549..5aecf100 100644 --- a/site/index.html +++ b/site/index.html @@ -32,6 +32,7 @@

Bundle of Joy

MPL-2.0 Glama MCP Source + SonarCloud