BoJ Server

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

image::site/assets/favicon.svg[BoJ Server mark,96,96]

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.

[cols="1s,4",frame=none,grid=none] |=== | Published | image:https://img.shields.io/npm/v/@hyperpolymath/boj-server?logo=npm[npm, link="https://www.npmjs.com/package/@hyperpolymath/boj-server"] image:https://img.shields.io/badge/SWH-Archived-blue?logo=softwareheritage[Software Heritage, link="https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/boj-server"] image:https://aiagentslisting.com/boj-server/badge.svg?variant=score[Boj Server MCP score, link="https://aiagentslisting.com/mcp/boj-server"]

| Runtimes | image:https://img.shields.io/badge/bun-%3E%3D1.0-black?logo=bun[Bun, link="https://bun.sh"] image:https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js[Node, link="https://nodejs.org"] image:https://img.shields.io/badge/deno-compatible-blue?logo=deno[Deno, link="https://deno.land"]

| Security & Health | 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/sonar/quality_gate/hyperpolymath_boj-server?server=https%3A%2F%2Fsonarcloud.io&logo=sonarcloud[Quality Gate, link="https://sonarcloud.io/summary/new_code?id=hyperpolymath_boj-server"]

| Compliance | image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0, link="LICENSE"] image:https://api.reuse.software/badge/github.com/hyperpolymath/boj-server[REUSE Compliance, link="https://api.reuse.software/info/github.com/hyperpolymath/boj-server"] image:https://img.shields.io/greenweb/boj-server.net?logo=thegreenwebfoundation[Green Web Hosted, link="https://www.thegreenwebfoundation.org/green-web-check/?url=boj-server.net"] |===

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:#what-is-proven[What is proven]
• 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 ABI model — an Idris2 safety and dispatch ABI (HTTP, CORS, API keys, WebSocket lifecycle, prompt injection, catalogue, dispatch, credential isolation), %default total, with four documented axioms and nothing else unsound. Proofs are about the Idris model; see link:#what-is-proven[What is proven] for where they stop.

'''''

== 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)

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

Or run the server directly with npx (any MCP client that launches a stdio command):

npx -y @hyperpolymath/boj-server

=== 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"]
    }
  }
}

Restart Claude Desktop after saving. No env block is needed: BOJ++_++URL defaults to http://localhost:7700. Set it under env only if your backend listens elsewhere.

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

# 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.5.0). The MCP bridge itself reports 0.5.0 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 Idris2 ABI safety layer has discharged proof obligations; the only believe++_++me sites are four documented axioms over the compiler's opaque Char/String primitives, tracked in link:PROOF-NEEDS.adoc[PROOF-NEEDS.adoc]. See link:#what-is-proven[What is proven] for the Proven / Witnessed / Trusted breakdown.
• 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].

'''''

== What is proven

Every safety claim BoJ makes sits in one of three bins. "Proven" always means proven about a model, so the claim is only as good as the match between that model and the running code. That is why the Witnessed column matters.

[cols="1,1,1",options="header"] |=== |Proven — the compiler checks it |Witnessed — an artefact backs it |Trusted — relied on from outside

a|

• The Idris2 ABI in src/abi/Boj/ (17 modules, all %default total) covers catalogue and dispatch, HTTP/CORS/API-key/WebSocket/prompt-injection safety predicates, and the credential-isolation model.
• believe++_++me appears only in four documented axioms over opaque Char/String primitives (SafetyLemmas.idr); CI (scripts/check-trusted-base.sh) pins that count and greps the rest of the Idris tree for believe++_++me, assert++_++total, assert++_++smaller and idris++_++crash. The grep has known gaps (a use followed by a -- comment is skipped; partial, covering and holes are not scanned). CI runs it, and the full typecheck, on every PR and push to main.
• Limit: these proofs are about the Idris model. The model is only ever typechecked, never compiled or linked into the running server, and 13 of the 17 C safety checks it binds (libbozsafety) are not yet implemented. a|
• Property tests (Elixir StreamData, elixir/test/backend_assurance/) of the behaviour each of the four axioms assumes, run against Elixir analogues of the Chez primitives (not the compiled Idris code); last executed and green 2026-10-06.
• Zig FFI enum constants checked at compile time against a hand-kept mirror of the Idris values (the Idris side itself is not compared).
• TLA+ specs of the JS worker, worker pool and invoker (specs/elixir-harness/), model-checked with TLC by hand (results recorded in its README), not in CI.
• npm package published with provenance; SLSA level 3 provenance on release tarballs; container build attestation.
• Coherence tests: the advertised tool list matches the dispatch table. a|
• The JavaScript bridge (mcp-bridge/) and the Zig FFI: the proofs cover the model, not this code.
• Tool annotations (readOnlyHint, destructiveHint, …): hand-written labels, not derived from types and not enforced at dispatch.
• Postgres, Docker, cloud and forge APIs behaving as documented; cartridge backends you run yourself.
• The Idris2 compiler, Zig, the Node/Deno/Bun runtime and the operating system.
• The AI choosing the right tool. Prompt injection is limited by input hardening, not proven away. |===

Planned next steps that move items left (Trusted → Witnessed → Proven) are tracked in link:PROOF-NEEDS.adoc[PROOF-NEEDS.adoc]: link every bound C symbol and gate CI on it, and derive tool annotations from a typed effect declaration that the dispatcher enforces.

'''''

== 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.