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

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.

| Cartridge | Description | |---|---| | github-api-mcp | GitHub REST API — repos, issues, PRs, search | | gitlab-api-mcp | GitLab REST API — projects, issues, MRs | | github-actions-mcp | GitHub Actions — workflows, runs, jobs, artifacts, secret rotation | | git-mcp | Multi-forge git operations (GitHub, GitLab, Gitea, Bitbucket) |

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

| Cartridge | Description | |---|---| | cloud-mcp | Multi-cloud session manager (AWS / GCP / Azure / DO / Vercel) | | aws-mcp | AWS gateway — session-based auth, per-region slots, throttle management | | gcp-mcp | GCP gateway — project-scoped auth, quota tracking, multi-service routing | | cloudflare-mcp | Cloudflare v4 — Workers, D1, KV, R2, DNS, zone settings, SSL/TLS | | digitalocean-mcp | DigitalOcean — droplets, volumes, domains, SSH keys, snapshots, databases | | hetzner-mcp | Hetzner Cloud — servers, volumes, firewalls, networks, snapshots, floating IPs | | fly-mcp | Fly.io Machines v1 — apps, machines, volumes, secrets, regions, IPs, certs | | linode-mcp | Linode/Akamai — instances, volumes, domains, NodeBalancers, StackScripts | | railway-mcp | Railway GraphQL v2 — projects, services, deployments, env, domains, logs | | render-mcp | Render REST v1 — services, deploys, env groups, custom domains, jobs |

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

| Cartridge | Description | |---|---| | database-mcp | Universal SQL/NoSQL gateway across multiple engines | | postgresql-mcp | PostgreSQL — full transaction support, connection pooling, query lifecycle | | mongodb-mcp | MongoDB — collection-level CRUD, aggregation pipelines, sessions | | redis-mcp | Redis — KV, sorted sets, pub/sub, streams, Lua scripting | | neo4j-mcp | Neo4j — graph database query and write | | clickhouse-mcp | ClickHouse — columnar queries, bulk inserts, real-time analytics | | duckdb-mcp | DuckDB — in-process analytics over Parquet/CSV/JSON/Arrow | | arango-mcp | ArangoDB — AQL queries, multi-model documents, graph traversals | | turso-mcp | Turso libSQL — edge SQLite, multi-DB, embedded replica sync | | supabase-mcp | Supabase — Postgres, Auth, Storage, Edge Functions | | neon-mcp | Neon — serverless Postgres, branch management, query execution | | verisimdb-mcp | VeriSimDB — verified simulation database with formal drift detection |

| Cartridge | Description | |---|---| | container-mcp | Build / create / start / stop / remove via Podman or Docker | | docker-hub-mcp | Docker Hub — image search, repos, tag listing, manifests | | k8s-mcp | Kubernetes — namespace-scoped CRUD with lifecycle management | | stapeln-mcp | Stapeln stack manager — Chainguard-base composable container layers | | vordr-mcp | Vordr integrity monitor — BLAKE3 tamper-detection on container images |

| Cartridge | Description | |---|---| | buildkite-mcp | Buildkite — pipelines, builds, jobs, artifacts | | circleci-mcp | CircleCI — pipelines, workflows, jobs, artifacts | | laminar-mcp | Laminar — minimalist CI/CD pipeline management | | hypatia-mcp | Hypatia — neurosymbolic CI security/quality/compliance scanner | | observe-mcp | Unified observability — metrics, logs, traces | | grafana-mcp | Grafana — dashboards, panel queries, alert rules, annotations | | prometheus-mcp | Prometheus — PromQL instant + range queries, alerts, targets | | sentry-mcp | Sentry — issues, events, projects, releases, deployments |

| Cartridge | Description | |---|---| | comms-mcp | Gmail + Google Calendar — send, read, search, labels, events, free/busy | | slack-mcp | Slack — messages, channels, threads, search, users | | discord-mcp | Discord — messages, channel history, guilds, reactions | | telegram-mcp | Telegram Bot API — messages, chats, inline queries, updates | | matrix-mcp | Matrix — messages, room join/leave, history, membership | | notifyhub-mcp | Unified notify — Email, SMS, WhatsApp, Slack, Telegram, Discord |

Bridge-level tools: boj_comms_gmail, boj_comms_calendar.

| Cartridge | Description | |---|---| | google-docs-mcp | Docs — document retrieval, content, search, headings, comments | | google-sheets-mcp | Sheets — metadata, cell ranges, named ranges, sheet listing | | notion-mcp | Notion — pages, databases, blocks | | obsidian-mcp | Obsidian vault — note search, content, backlinks, tags, graph | | linear-mcp | Linear — issues, projects, cycles, labels | | jira-mcp | Jira — projects, issues, sprints, workflows | | todoist-mcp | Todoist — tasks, projects, completion, labels | | airtable-mcp | Airtable — bases, table schemas, record CRUD | | zotero-mcp | Zotero — library search, items, collections, tags | | academic-workflow-mcp | Academic workflow — Zotero integration, citations, paper review |

| Cartridge | Description | |---|---| | ml-mcp | Hugging Face + others — search, model info, inference, spaces, datasets | | claude-ai-mcp | Anthropic Messages API — Claude models, token counting, multi-turn | | claude-agents-power-mcp | Specialized AI-agent management for dev teams | | model-router-mcp | Task classifier — recommends opus/sonnet/haiku per task | | echidna-llm-mcp | LLM advisor for the ECHIDNA formal-verification engine | | agent-mcp | OODA-loop agent session enforcer | | local-coord-mcp | Multi-instance peer discovery + typed envelopes + supervision (21 tools) | | local-memory-mcp | Persistent local memory for Claude, Cursor, Codex (13 tools, no cloud) |

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

| Cartridge | Description | |---|---| | browser-mcp | Firefox automation via Marionette — navigate, click, type, screenshot, exec JS | | gossamer-mcp | Native desktop windows — panel loading, JS bridge |

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

| Cartridge | Description | |---|---| | codeseeker-mcp | CodeSeeker — vector + BM25 + path-tier fused via RRF; KG traversal; Graph-RAG | | coderag-mcp | Enterprise code intelligence — graph-based analysis for AI-assisted dev | | research-mcp | Semantic Scholar / OpenAlex — papers, citations, references, authors | | opendatamcp | Public dataset access for LLM apps | | origenemcp | Biomedical platform — 600+ tools/databases (ChEMBL, PubChem, FDA, OpenTargets) |

Bridge-level tools: boj_codeseeker, boj_research.

| Cartridge | Description | |---|---| | lsp-mcp | Generic Language Server Protocol 3.17 gateway — spawn any LSP server | | dap-mcp | Generic Debug Adapter Protocol gateway | | bsp-mcp | Generic Build Server Protocol 2.x gateway | | lang-mcp | Multi-language session manager — Eclexia, AffineScript, BetLang, Ephapax | | toolchain-mcp | Toolchain orchestrator — mint/provision/configure language toolchains | | orchestrator-lsp-mcp | Cross-domain LSP router across all 12 poly-*-lsp servers | | affinescript-mcp | AffineScript — type check, parse, format, lint, compile, hover, definition | | typed-wasm-mcp | AffineScript → typed-wasm at Level 7/10 ownership soundness | | npm-registry-mcp | npm — search, metadata, versions, downloads, dependency analysis | | pypi-mcp | PyPI — Python packages, search, metadata, versions, downloads | | crates-mcp | crates.io — Rust crates, search, metadata, versions, downloads | | hackage-mcp | Hackage — Haskell packages | | hex-mcp | Hex.pm — Elixir/Erlang packages | | opam-mcp | opam — OCaml packages |

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

| Cartridge | Description | |---|---| | secrets-mcp | Secrets management — Vault, SOPS, env-vault | | vault-mcp | Vault CLI credential broker — execute, list, verify, rotate | | sanctify-mcp | Sanctify — PHP lint + deviation detection | | panic-attack-mcp | panic-attacker static analysis — dangerous patterns, banned constructs, drift | | vext-mcp | Vext — signed-message verification, attestation chains | | rokur-mcp | Rokur — Svalinn secrets GUI authorisation layer | | dns-shield-mcp | DNS security — DoQ, DoH, DNSSEC, CAA |

| Cartridge | Description | |---|---| | iac-mcp | Terraform / OpenTofu lifecycle — plan → apply → destroy with state lifecycle | | conflow-mcp | Conflow — configuration management | | bofig-mcp | Bofig — evidence graph query for investigative workflows | | proof-mcp | Proof verification — Lean, Coq, Agda, Isabelle, Idris2, Z3, more | | nesy-mcp | Neural-symbolic harmonisation — symbolic truth overrides neural probability | | ephapax-mcp | Ephapax — proof-compiler query tools for formal verification | | pmpl-mcp | PMPL licence chain verification + artefact hashing |

| Cartridge | Description | |---|---| | boj-health | Self-health — status, ping, uptime | | fleet-mcp | gitbot-fleet gate compliance tracker | | reposystem-mcp | Reposystem — managed repos, health, mirrors, RSR compliance | | 007-mcp | oo7 agent meta-language — parse/run/trace/build/test/lint | | k9iser-mcp | K9 contract regeneration (k9iser generate/validate/apply) | | idaptik-admin-mcp | IDApTIK game server administration | | burble-admin-mcp | Burble WebRTC server administration | | game-admin-mcp | Game server admin + configuration drift | | aerie-mcp | Aerie environment lifecycle manager | | hesiod-mcp | DNS lookup cartridge | | fireflag-mcp | Fireflag — extension-to-MCP mapping and discovery | | kategoria-mcp | Type-theory learning system — classification + learner evaluation | | civic-connect-mcp | CivicConnect community engagement platform |

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

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.