// SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell [email protected] = BoJ Server :idprefix: :idseparator: -

One MCP endpoint for the WHOLE toolchain — GitHub, GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, ML, multi-agent coordination, and a large catalogue of pluggable domain cartridges, all reachable through a single zero-dependency stdio bridge.

link:LICENSE[image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0]] https://www.npmjs.com/package/@hyperpolymath/boj-server[image:https://img.shields.io/npm/v/@hyperpolymath/boj-server?logo=npm[npm]] https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/boj-server[image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices]] https://scorecard.dev/viewer/?uri=github.com/hyperpolymath/boj-server[image:https://api.scorecard.dev/projects/github.com/hyperpolymath/boj-server/badge[OpenSSF Scorecard]] https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/boj-server[image:https://archive.softwareheritage.org/badge/origin/https://github.com/hyperpolymath/boj-server/[Software Heritage]] https://sonarcloud.io/summary/new_code?id=hyperpolymath_boj-server[image:https://sonarcloud.io/api/project_badges/quality_gate?project=hyperpolymath_boj-server[Quality gate]]

---

What it is, honestly: BoJ exposes 68 MCP tools today (45 boj++_*++ {plus} 23 coord++_*++) over stdio with zero runtime dependencies. It catalogues 125 domain cartridges, but most of those are an inspectable catalogue, not live services — a cartridge only performs real actions when its backend process is running and you supply the right credentials. The bridge is fully inspectable offline; side-effectful tools return a structured ++{++error, hint} until their backend is up. See link:#cartridges[Cartridges] for the full story.

---

'''''

== Contents

• link:#features[Features]
• link:#install[Install]
• link:#quickstart[Quickstart]
• link:#capabilities-overview[Capabilities overview]
• link:#cartridges[Cartridges]
• link:#backend[Backend]
• link:#transports[Transports]
• link:#configuration[Configuration]
• link:#security[Security]
• link:#license[License]
• link:++#contributing--links++[Contributing & links]

'''''

== Features

• Unified endpoint — GitHub/GitLab, Cloudflare/Vercel/Verpex, Gmail/Calendar, Firefox browser automation, CodeSeeker code intelligence, Semantic Scholar research, and Hugging Face ML, all behind one MCP server.
• 68 MCP tools — 45 boj++_*++ (5 core discovery/dispatch {plus} explicit high-frequency tools) and 23 coord++_*++ multi-agent coordination tools.
• 125-cartridge catalogue — a single boj++_++cartridge++_++invoke reaches any catalogued cartridge; explicit boj++_<++domain++>_<++verb++>++ tools exist for the highest-frequency operations.
• Multi-instance AI coordination — local-coord-mcp lets several Claude / Gemini / Codex sessions on one machine discover each other, claim tasks without collision, and run under a master/journeyman/apprentice supervision model.
• Zero runtime dependencies — the bridge runs on Node, Deno, or Bun with no install step.
• Inspectable offline — boj++_++health, boj++_++menu, boj++_++cartridges, and boj++_++cartridge++_++info answer from an offline manifest so clients can introspect the server without any backend running.
• MCP resources & prompts — 7 boj:// resources and reusable prompts (audit-repo, convene-cluster, deploy-with-dns-ssl, summarize-channel, triage-issues, proof-status).
• Hardened — per-call rate limiting, size caps, prompt-injection detection with Unicode-confusable normalisation, and error sanitisation (paths, stack traces, and env vars stripped from responses).
• Formally verified core — the coordination ABI is written in Idris2 with discharged proof obligations; remaining axioms are documented, not hidden.

'''''

== Install

BoJ ships as an MCP server over stdio. The published npm package (@hyperpolymath/boj-server) has zero runtime dependencies, so no install step is ever required regardless of runtime.

---

Most cartridges call the BoJ REST backend on http://localhost:7700. Without it, the server is still fully inspectable; side-effectful tools return ++{++error, hint}. See link:#backend[Backend].

---

=== Claude Code (CLI)

[source,bash]

claude mcp add boj-server -- npx -y @hyperpolymath/boj-server@latest

=== Claude Desktop

Edit claude++_++desktop++_++config.json:

• macOS — ~/Library/Application Support/Claude/claude++_++desktop++_++config.json
• Windows — %APPDATA%++\++Claude++\++claude++_++desktop++_++config.json
• Linux — ~/.config/Claude/claude++_++desktop++_++config.json

[source,json]

{ "mcpServers": { "boj-server": { "command": "npx", "args": ["-y", "@hyperpolymath/boj-server@latest"], "env": { "BOJ_URL": "http://localhost:7700" } } } }

Restart Claude Desktop after saving.

=== npx (any MCP client)

The minimum stdio spec is command: npx, args: ++[++"-y", "@hyperpolymath/boj-server@latest"++]++. Optional env: BOJ++_++URL (default http://localhost:7700). This works with VS Code / Copilot, Cursor, Cline, Windsurf, Continue.dev, Zed, and the Gemini CLI — point each client's MCP config at that command. This repo's .mcp.json is a working reference config.

[[deno--bun--node-from-a-clone]] === Deno / Bun / Node (from a clone)

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

[source,bash]

Deno (no install step; the project's documented runtime)

deno run -A /path/to/boj-server/mcp-bridge/main.js

Bun (zero-install)

bun /path/to/boj-server/mcp-bridge/main.js

Node (>= 18)

node /path/to/boj-server/mcp-bridge/main.js

'''''

== Quickstart

After install, ask your LLM: "Use the boj++_++health tool." You get ++{++status:"ok", uptime++_++s, version} when the backend is up, or a structured hint when it is offline.

To talk to the bridge directly over stdio, send newline-delimited JSON-RPC. Initialize, then list tools:

[source,bash]

printf '%s\n%s\n'
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"demo","version":"0"}}}'
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
| node mcp-bridge/main.js

The initialize response reports protocol 2024-11-05 and server boj-server; tools/list returns 68 tool definitions (45 boj++_*++, 23 coord++_*++), each carrying a full description, JSON-Schema inputSchema/outputSchema, and MCP behaviour annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).

Call a tool:

[source,jsonc]

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "boj_health", "arguments": {} } }

The server also implements resources/list (7 boj:// resources) and prompts/list.

'''''

== Capabilities overview

The bridge exposes 45 boj++_*++ tools and 23 coord++_*++ tools. A subset of cartridges have explicit boj++_<++domain++>_<++verb++>++ tools for high-frequency operations; everything catalogued is reachable through boj++_++cartridge++_++invoke.

[cols=",,",options="header",] |=== |Group |Tools |Examples |Core discovery / dispatch |5 |boj++_++health, boj++_++menu, boj++_++cartridges, boj++_++cartridge++_++info, boj++_++cartridge++_++invoke |GitHub |14 |boj++_++github++_++list++_++repos, boj++_++github++_++create++_++issue, boj++_++github++_++create++_++pr, boj++_++github++_++merge++_++pr, boj++_++github++_++search++_++code, boj++_++github++_++graphql |GitLab |8 |boj++_++gitlab++_++list++_++projects, boj++_++gitlab++_++create++_++mr, boj++_++gitlab++_++list++_++pipelines, boj++_++gitlab++_++setup++_++mirror |Browser (Firefox) |7 |boj++_++browser++_++navigate, boj++_++browser++_++click, boj++_++browser++_++type, boj++_++browser++_++read++_++page, boj++_++browser++_++screenshot, boj++_++browser++_++tabs, boj++_++browser++_++execute++_++js |Cloud |3 |boj++_++cloud++_++cloudflare, boj++_++cloud++_++vercel, boj++_++cloud++_++verpex |Communications |2 |boj++_++comms++_++gmail, boj++_++comms++_++calendar |Research / code intel / ML / search |4 |boj++_++research, boj++_++codeseeker, boj++_++ml++_++huggingface, boj++_++search |Coordination (local-coord-mcp) |23 |coord++_++register, coord++_++claim++_++task, coord++_++send, coord++_++review, coord++_++approve, coord++_++health |===

---

Set BOJ++_++TOOL++_++SCOPE=core to advertise only the discovery surface; explicit boj++_<++domain++>_*++ tools remain reachable via boj++_++cartridge++_++invoke regardless. A CSV of prefixes (e.g. core,github,browser) advertises core plus named groups.

---

=== Multi-agent coordination (coord++_*++)

A localhost multi-agent bus (default 127.0.0.1:7745) lets multiple AI sessions on one machine discover each other, claim tasks without collision, and operate under supervision (master approves; journeyman executes; apprentice stays gated):

• Peers — coord++_++register, coord++_++list++_++peers, coord++_++set++_++variant, coord++_++set++_++capabilities, coord++_++get++_++peer++_++capabilities.
• Typed envelopes — coord++_++send, coord++_++send++_++gated, coord++_++receive (Nickel-contract validation, opt-in strict mode).
• Task claims — coord++_++claim++_++task with role-based watchdog TTL, coord++_++progress heartbeats, coord++_++sweep++_++watchdog, optional advisory paths for path++_++overlap warnings.
• Track record — coord++_++report++_++outcome, coord++_++get++_++affinities, coord++_++set++_++declared++_++affinities, coord++_++scan++_++suggestions (emits overclaim/drift advisory envelopes).
• Supervision — coord++_++review, coord++_++review++_++entry, coord++_++approve, coord++_++reject, coord++_++promote++_++to++_++master, coord++_++transfer++_++master, plus coord++_++status / coord++_++health.

Task-claim collision-freedom is a task-level guarantee, not a git-level lock: two journeymen claiming different tasks that touch the same file can still hit a vanilla merge conflict. The supported pattern is branch-per-claim {plus} per-peer worktree, advisory path-claims, and master-gated integration. The companion terminal UI lives in link:coord-tui/[coord-tui/] and at https://github.com/hyperpolymath/coord-tui[hyperpolymath/coord-tui].

'''''

== Cartridges

BoJ catalogues 125 cartridges across trust tiers (Teranga / Shield / Ayo). Be clear about what that means:

• Catalogued ≠ live. boj++_++menu lists the full catalogue, but most cartridges report available: false. They are entries describing a capability — its API base URL, auth model (often brokered through vault-mcp), and any native FFI path — not a running service.
• A cartridge becomes available when (1) its backend process is running and reachable via the BoJ REST API, and (2) you have supplied the credentials it needs.
• Credentials are typically environment variables (GITHUB++_++TOKEN, GITLAB++_++TOKEN, CF++_++API++_++TOKEN, OAuth tokens, …) or are brokered by the vault-mcp credential cartridge. boj++_++cartridge++_++info ++<++name++>++ returns the cartridge's manifest, including the exact auth requirement.
• Without backend or credentials, side-effectful tools return a structured ++{++error, hint} telling you what's missing — they never silently fail.

---

Number transparency: 125 is the single source of truth — it is the number of cartridge.json manifests in the canonical https://github.com/hyperpolymath/boj-server-cartridges[boj-server-cartridges] registry (the bundled cartridges/ tree was retired from this repo; populate a local cache with scripts/fetch-cartridges.sh + BOJ_CARTRIDGES_PATH) and what the live boj++_++menu reports. Every packaging file (package.json, jsr.json, smithery.yaml, ai-plugin.json, openapi.yaml, CITATION.cff) is reconciled to it. Of those 125, most are a catalogue entry rather than a live service — see the bullets above.

---

Catalogued domains include: git forges & code hosting, cloud platforms (Cloudflare, Vercel, AWS, GCP, DigitalOcean, Hetzner, Fly, Linode, Railway, Render), databases (PostgreSQL, MongoDB, Redis, Neo4j, ClickHouse, DuckDB, Turso, Supabase, Neon, …), containers & Kubernetes, CI/CD & observability (Buildkite, CircleCI, Hypatia, Grafana, Prometheus, Sentry), messaging (Slack, Discord, Telegram, Matrix), productivity (Notion, Linear, Jira, Obsidian, Zotero), ML/AI & coordination, browser & web automation, code intelligence & research, developer tooling (LSP/DAP/BSP, language & package registries), security & secrets, IaC & proof systems, and hyperpolymath-native admin cartridges.

'''''

== Backend

Most cartridges (GitHub/GitLab, cloud, ML, browser, CodeSeeker, etc.) call the BoJ REST API — an Elixir service on http://localhost:7700. Two modes:

[arabic] . Run BoJ locally — clone this repo and just run (see link:docs/quickstarts/USER.adoc[docs/quickstarts/USER.adoc]). The REST API serves on port 7700. . Inspectable mode only — without the backend, boj++_++health, boj++_++menu, boj++_++cartridges, and boj++_++cartridge++_++info still respond from the offline manifest, so any MCP client can introspect the server. Side-effectful tools return ++{++error, hint} until the backend is up.

---

Note on versions: when the backend is offline, boj++_++health may report a placeholder backend version (0.1.0) from the bundled offline manifest — this is the manifest's hardcoded value, not the npm package version (0.4.7). The MCP bridge itself reports 0.4.7 at initialize.

---

The coordination bus (local-coord-mcp) is a separate localhost service, default http://127.0.0.1:7745 (COORD++_++BACKEND++_++URL).

'''''

== Transports

Selected with BOJ++_++TRANSPORT (ADR-0013):

[cols=",",options="header",] |=== |Value |Behaviour |stdio (default) |Reads JSON-RPC from stdin, writes to stdout — how Claude Code / Desktop launch the bridge as a subprocess. |http |Starts an HTTP{plus}SSE listener on BOJ++_++HTTP++_++PORT (default 7780) for remote / Workers / browser deployments. Binds 127.0.0.1 by default; BOJ++_++HTTP++_++AUTH=none is refused on a non-loopback bind. |both |Runs stdio and HTTP simultaneously. |===

HTTP auth: none (loopback only), or bearer against BOJ++_++HTTP++_++AUTH++_++TOKENS. mtls/oidc are planned, not yet implemented.

'''''

== Configuration

Key environment variables (full schema in link:glama.json[glama.json]):

[cols=",,",options="header",] |=== |Variable |Default |Purpose |BOJ++_++URL |http://localhost:7700 |Base URL for the BoJ REST backend. |GITHUB++_++TOKEN |— |PAT for boj++_++github++_*++ tools. |GITLAB++_++TOKEN / GITLAB++_++URL |— / https://gitlab.com |Token {plus} base URL for boj++_++gitlab++_*++ tools. |BOJ++_++TOOL++_++SCOPE |full |full, core, or a CSV of domain prefixes (e.g. core,github,browser). |BOJ++_++RATE++_++LIMIT |60 |Max tool calls per minute. |BOJ++_++LOG++_++LEVEL |info |debug / info / warn / error / silent. |BOJ++_++TRANSPORT |stdio |stdio / http / both. |BOJ++_++HTTP++_++PORT / BOJ++_++HTTP++_++BIND |7780 / 127.0.0.1 |HTTP transport port and bind address. |BOJ++_++HTTP++_++AUTH / BOJ++_++HTTP++_++AUTH++_++TOKENS |none / — |HTTP auth mode and accepted bearer tokens. |COORD++_++BACKEND++_++URL |http://127.0.0.1:7745 |Coordination bus backend. |COORD++_++REQUIRE++_++NICKEL |0 |1 enables strict Nickel-contract validation on gated envelopes. |OTEL++_++EXPORTER++_++OTLP++_++ENDPOINT |— |When set, every tools/call emits an OTLP/JSON span to ++<++endpoint++>++/v1/traces. |===

'''''

== Security

• Input hardening — per-call rate limiting (BOJ++_++RATE++_++LIMIT), request size caps, and prompt-injection detection with Unicode-confusable normalisation.
• Error sanitisation — responses strip filesystem paths, stack traces, and environment variables before they reach the client.
• HTTP safety — BOJ++_++HTTP++_++AUTH=none is refused on any non-loopback bind; bearer auth is required for remote exposure.
• Credential isolation — cartridge credentials are supplied per-cartridge (env vars or the vault-mcp broker), never embedded in tool definitions.
• Formal verification — the coordination ABI safety layer is written in Idris2 with discharged proof obligations; remaining believe++_++me sites are isolated, documented axioms over the compiler's opaque Char/String primitives, tracked in link:PROOF-NEEDS.md[PROOF-NEEDS.md].
• Supply chain — SHA-pinned GitHub Actions; coherence tests assert the advertised tool list matches the cartridge manifest so nothing is advertised-but-undispatched.

Run the coherence tests:

[source,bash]

node --test mcp-bridge/tests/

Report vulnerabilities per link:SECURITY.md[SECURITY.md].

'''''

== License

• Code — link:LICENSE[MPL-2.0] (Mozilla Public License 2.0) — the license published to npm and detected by GitHub.
• Documentation — MPL-2.0 today (the repository's REUSE config tags every file MPL-2.0); a CC-BY-SA-4.0 split for prose is the intended model, with the docs-licence rollout tracked as a follow-up.

'''''

[[contributing--links]] == Contributing & links

• Repository — https://github.com/hyperpolymath/boj-server[github.com/hyperpolymath/boj-server]
• npm — https://www.npmjs.com/package/@hyperpolymath/boj-server[`@hyperpolymath/boj-server`]
• Glama listing — https://glama.ai/mcp/servers/hyperpolymath/boj-server[glama.ai/mcp/servers/hyperpolymath/boj-server]
• Coordination TUI — https://github.com/hyperpolymath/coord-tui[hyperpolymath/coord-tui]
• Contributing — see link:CONTRIBUTING.md[CONTRIBUTING.md] and link:CODE_OF_CONDUCT.md[CODE++_++OF++_++CONDUCT.md].
• Citing — citation metadata is in link:CITATION.cff[CITATION.cff]; GitHub renders a "Cite this repository" button from it.

Maintained by Jonathan D.A. Jewell.