Skip to content

README.md

Latest commit

 

History

History
73 lines (51 loc) · 4.72 KB

README.md

File metadata and controls

73 lines (51 loc) · 4.72 KB

boj-server

OpenSSF Best Practices Glama MCP Server Green Hosting

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 50+ open-source cartridges.

Install

Add to Claude Code:

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

Or clone and configure:

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 — 100 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).

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

License

MPL-2.0 — see LICENSE.