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.

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

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.

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.adoc). REST API 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 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

Related MCP server: OrigeneMCP

Scope

115 cartridges, organized across the domains below. Each cartridge is a formally verified Idris2 ABI + Zig FFI + Deno/JS adapter triple, reachable through a single MCP endpoint. Click any section to expand.

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

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

Bridge-level tools: boj_comms_gmail, boj_comms_calendar.

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

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

Bridge-level tools: boj_codeseeker, boj_research.

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

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.

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:

npm test

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.org 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:

   [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX)

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

License

MPL-2.0 — see LICENSE.