// SPDX-License-Identifier: PMPL-1.0-or-later // SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk

= boj-server :toc: preamble :icons: font

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://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] image:https://glama.ai/mcp/servers/hyperpolymath/boj-server/badge[Glama MCP Server,link=https://glama.ai/mcp/servers/hyperpolymath/boj-server] image:https://api.thegreenwebfoundation.org/greencheckimage/boj-server.net[Green Hosting,link="https://www.thegreenwebfoundation.org/green-web-check/?url=boj-server.net"]

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

Add to Claude Code:

[source,bash]

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

Or clone and configure:

[source,bash]

git clone https://github.com/hyperpolymath/boj-server cd boj-server/mcp-bridge && npm install

Start the BoJ REST API first (port 7700), then:

claude mcp add boj-server -- node mcp-bridge/main.js

Glama listing: https://glama.ai/mcp/servers/hyperpolymath/boj-server

== Features

• 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

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

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

[source,bash]

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:

[source,bash]

node --test mcp-bridge/tests/

== License

PMPL-1.0-or-later