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.

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:

# Preferred — Deno (no install step; fetches imports on first run)
deno run -A /path/to/boj-server/mcp-bridge/main.js

# 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

The bridge has zero runtime dependencies (see package.json) so no install step is ever required, regardless of runtime.

Most cartridges require the BoJ REST backend running on http://localhost:7700 — see Backend below.

Claude Code (CLI)

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

Related MCP server: MCP Proxy Server

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%Claudeclaude_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.

Gemini CLI

This repo ships a gemini-extension.json — install it directly:

gemini extensions install https://github.com/hyperpolymath/boj-server

Or add to ~/.gemini/settings.json:

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

GitHub Copilot (VS Code)

VS Code 1.99+ supports MCP servers natively. Add to workspace .vscode/mcp.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.

Cursor

Workspace: .cursor/mcp.json. User-global: ~/.cursor/mcp.json.

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

Or use Settings → MCP → Add new MCP server.

Cline (VS Code extension)

Settings → Cline → MCP Servers → Edit MCP Settings:

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

Windsurf (Codeium Cascade)

Edit ~/.codeium/windsurf/mcp_config.json:

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

Continue.dev

In ~/.continue/config.yaml:

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

Zed

Settings (~/.config/zed/settings.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:

1. Run BoJ locally — clone this repo and just run (see QUICKSTART-USER). REST API on port

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

🔧 Git forges & code hosting — 4 cartridges

Bridge-level tools: boj_github_* (14), boj_gitlab_* (8) — 22 explicit tools. Auth via GITHUB_TOKEN / GITLAB_TOKEN env vars.

☁️ Cloud platforms — 10 cartridges

Bridge-level tools: boj_cloud_cloudflare, boj_cloud_vercel, boj_cloud_verpex. Other providers reachable via boj_cartridge_invoke.

🗄 Databases — 12 cartridges

📦 Containers, deploy & integrity — 5 cartridges

🔁 CI/CD & observability — 8 cartridges

💬 Communications & messaging — 6 cartridges

Bridge-level tools: boj_comms_gmail, boj_comms_calendar.

📚 Productivity & knowledge — 10 cartridges

🤖 ML, AI & coordination — 8 cartridges

Bridge-level tool: boj_ml_huggingface. coord_* tools (21) wire through local-coord-mcp — see the dedicated section below.

🌐 Browser & web automation — 2 cartridges

Bridge-level tools: boj_browser_* (7) — navigate, click, type, read_page, screenshot, tabs, execute_js.

🔍 Code intelligence & research — 5 cartridges

Bridge-level tools: boj_codeseeker, boj_research.

🛠 Developer tooling (LSP/DAP/BSP, languages, registries) — 14 cartridges

Plus opsm-mcp (Odds-and-Sods Package Manager) routes search/install/dep-resolution across all of the above.

🔒 Security & secrets — 7 cartridges

🏗 Infrastructure-as-code, config & proof — 7 cartridges

🌱 Hyperpolymath-native admin & ecosystem — 13 cartridges

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_<domain>_<verb> 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 <task-id> claims the task and provisions an isolated git worktree at ../<repo>-worktrees/<task> on branch agent/<peer-id>/<task>, 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.

# New machine setup
bash coord-tui/install.sh

# Then open your tools normally — registration and titling are automatic
claude
gemini
vibe

Glama AAA posture

This server targets Glama’s AAA tier. Posture:

• 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_<domain>_<action> and coord_<action> 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).

Run the coherence tests:

node --test mcp-bridge/tests/

Formal verification

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

Citing

If you use BoJ Server in academic work, citation metadata is in CITATION.cff. GitHub renders a "Cite this repository" button in the sidebar from this file.

Per-release DOIs are available via Zenodo. To enable them:

1. Log in to zenodo with your GitHub account.

2. Account → GitHub → flip the boj-server repository toggle to on.

3. Cut a new GitHub release; Zenodo auto-archives it and mints a DOI.

4. Add the DOI badge to this README.

5. Update the doi: field in CITATION.cff to match.

License

MPL-2.0 — see LICENSE.