<!-- SPDX-License-Identifier: CC-BY-SA-4.0 --> <!-- GENERATED from README.adoc by standards/.github/workflows/readme-derive-reusable.yml — do not edit. -->

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.

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 for the full story.

Contents

• Features

• Install

• Quickstart

• Capabilities overview

• Cartridges

• Backend

• Transports

• Configuration

• Security

• License

• 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 + 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 Backend.

Claude Code (CLI)

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

{
  "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)

The bridge entrypoint is mcp-bridge/main.js and runs on any of the three runtimes with no install:

# 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:

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:

{ "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.

| 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 + per-peer worktree, advisory path-claims, and master-gated integration. The companion terminal UI lives in coord-tui/ and at 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.