BoJ-server
BoJ-server is a unified MCP endpoint that exposes health/introspection and a large catalogue of tools for cloud, code hosting, communications, browser automation, research, ML, and multi-agent coordination.
Introspection & dispatch —
boj_health,boj_menu,boj_cartridges,boj_cartridge_info, andboj_cartridge_invokefor inspecting and invoking any catalogued cartridge.Cloud management — Cloudflare (Workers, D1, KV, R2, DNS), Vercel (projects, deployments, domains, env vars, logs, functions), and Verpex/cPanel (domains, DNS, email, databases, SSL, cron, metrics).
Communications — Gmail (send, read, search, labels) and Google Calendar (list/create events, free/busy).
Browser automation (Firefox) — navigate, click, type, read page, screenshot, manage tabs, execute JavaScript.
GitHub — repos, issues, PRs, code search, file contents, GraphQL queries.
GitLab — projects, issues, merge requests, pipelines, push mirrors.
Research — Semantic Scholar paper search, details, citations, references, authors.
ML — Hugging Face model search, info, inference, spaces, datasets.
Multi-agent coordination — the README describes 23
coord_*tools for peer registration, task claims, typed envelopes, supervision, and review workflows.Caveats — Most cartridges need the BoJ REST backend (Elixir on
localhost:7700) and credentials to perform real actions; without them, only introspection tools respond and side-effect tools return{error, hint}.
Integrates Git as a core capability domain through formally verified cartridges, enabling AI agents to interact with repositories and manage source control via the server's unified 2D matrix architecture.
One MCP endpoint for the WHOLE toolchain — GitHub, GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, ML, multi-agent coordination, and a large catalogue of pluggable domain cartridges, all reachable through a single zero-dependency stdio bridge.
Published |
|
Runtimes |
|
Security & Health |
|
Compliance |
|
What it is, honestly: BoJ exposes 68 MCP tools today (45
boj_*+ 23coord_*) over stdio with zero runtime dependencies. It catalogues 125 domain cartridges, but most of those are an inspectable catalogue, not live services — a cartridge only performs real actions when its backend process is running and you supply the right credentials. The bridge is fully inspectable offline; side-effectful tools return a structured{error, hint}until their backend is up. See Cartridges for the full story.
Contents
Features
Unified endpoint — GitHub/GitLab, Cloudflare/Vercel/Verpex, Gmail/Calendar, Firefox browser automation, CodeSeeker code intelligence, Semantic Scholar research, and Hugging Face ML, all behind one MCP server.
68 MCP tools — 45
boj_*(5 core discovery/dispatch + explicit high-frequency tools) and 23coord_*multi-agent coordination tools.125-cartridge catalogue — a single
boj_cartridge_invokereaches any catalogued cartridge; explicitboj_<domain>_<verb>tools exist for the highest-frequency operations.Multi-instance AI coordination —
local-coord-mcplets several Claude / Gemini / Codex sessions on one machine discover each other, claim tasks without collision, and run under a master/journeyman/apprentice supervision model.Zero runtime dependencies — the bridge runs on Node, Deno, or Bun with no install step.
Inspectable offline —
boj_health,boj_menu,boj_cartridges, andboj_cartridge_infoanswer from an offline manifest so clients can introspect the server without any backend running.MCP resources & prompts — 7
boj://resources and reusable prompts (audit-repo,convene-cluster,deploy-with-dns-ssl,summarize-channel,triage-issues,proof-status).Hardened — per-call rate limiting, size caps, prompt-injection detection with Unicode-confusable normalisation, and error sanitisation (paths, stack traces, and env vars stripped from responses).
Formally verified ABI model — an Idris2 safety and dispatch ABI (HTTP, CORS, API keys, WebSocket lifecycle, prompt injection, catalogue, dispatch, credential isolation),
%default total, with four documented axioms and nothing else unsound. Proofs are about the Idris model; see What is proven for where they stop.
Install
BoJ ships as an MCP server over stdio. The published npm package (@hyperpolymath/boj-server) has zero runtime dependencies, so no install step is ever required regardless of runtime.
Most cartridges call the BoJ REST backend on
http://localhost:7700. Without it, the server is still fully inspectable; side-effectful tools return{error, hint}. See Backend.
Claude Code (CLI)
claude mcp add boj-server -- npx -y @hyperpolymath/boj-server@latestOr run the server directly with npx (any MCP client that launches a stdio command):
npx -y @hyperpolymath/boj-serverRelated MCP server: MCP Context Forge Gateway
Claude Desktop
Edit claude_desktop_config.json:
macOS —
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows —
%APPDATA%\Claude\claude_desktop_config.jsonLinux —
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"boj-server": {
"command": "npx",
"args": ["-y", "@hyperpolymath/boj-server@latest"]
}
}
}Restart Claude Desktop after saving. No env block is needed: BOJ_URL defaults to http://localhost:7700. Set it under env only if your backend listens elsewhere.
npx (any MCP client)
The minimum stdio spec is command: npx, args: ["-y", "@hyperpolymath/boj-server@latest"]. Optional env: BOJ_URL (default http://localhost:7700). This works with VS Code / Copilot, Cursor, Cline, Windsurf, Continue.dev, Zed, and the Gemini CLI — point each client’s MCP config at that command. This repo’s .mcp.json is a working reference config.
Deno / Bun / Node (from a clone)
The bridge entrypoint is mcp-bridge/main.js and runs on any of the three runtimes with no install:
# Deno (no install step; the project's documented runtime)
deno run -A /path/to/boj-server/mcp-bridge/main.js
# Bun (zero-install)
bun /path/to/boj-server/mcp-bridge/main.js
# Node (>= 18)
node /path/to/boj-server/mcp-bridge/main.jsQuickstart
After install, ask your LLM: "Use the boj_health tool." You get {status:"ok", uptime_s, version} when the backend is up, or a structured hint when it is offline.
To talk to the bridge directly over stdio, send newline-delimited JSON-RPC. Initialize, then list tools:
printf '%s\n%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"demo","version":"0"}}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| node mcp-bridge/main.jsThe initialize response reports protocol 2024-11-05 and server boj-server; tools/list returns 68 tool definitions (45 boj_*, 23 coord_*), each carrying a full description, JSON-Schema inputSchema/outputSchema, and MCP behaviour annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).
Call a tool:
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": { "name": "boj_health", "arguments": {} } }The server also implements resources/list (7 boj:// resources) and prompts/list.
Capabilities overview
The bridge exposes 45 boj_* tools and 23 coord_* tools. A subset of cartridges have explicit boj_<domain>_<verb> tools for high-frequency operations; everything catalogued is reachable through boj_cartridge_invoke.
Group | Tools | Examples |
Core discovery / dispatch | 5 |
|
GitHub | 14 |
|
GitLab | 8 |
|
Browser (Firefox) | 7 |
|
Cloud | 3 |
|
Communications | 2 |
|
Research / code intel / ML / search | 4 |
|
Coordination ( | 23 |
|
Set
BOJ_TOOL_SCOPE=coreto advertise only the discovery surface; explicitboj_<domain>_*tools remain reachable viaboj_cartridge_invokeregardless. A CSV of prefixes (e.g.core,github,browser) advertises core plus named groups.
Multi-agent coordination (coord_*)
A localhost multi-agent bus (default 127.0.0.1:7745) lets multiple AI sessions on one machine discover each other, claim tasks without collision, and operate under supervision (master approves; journeyman executes; apprentice stays gated):
Peers —
coord_register,coord_list_peers,coord_set_variant,coord_set_capabilities,coord_get_peer_capabilities.Typed envelopes —
coord_send,coord_send_gated,coord_receive(Nickel-contract validation, opt-in strict mode).Task claims —
coord_claim_taskwith role-based watchdog TTL,coord_progressheartbeats,coord_sweep_watchdog, optional advisorypathsforpath_overlapwarnings.Track record —
coord_report_outcome,coord_get_affinities,coord_set_declared_affinities,coord_scan_suggestions(emitsoverclaim/driftadvisory envelopes).Supervision —
coord_review,coord_review_entry,coord_approve,coord_reject,coord_promote_to_master,coord_transfer_master, pluscoord_status/coord_health.
Task-claim collision-freedom is a task-level guarantee, not a git-level lock: two journeymen claiming different tasks that touch the same file can still hit a vanilla merge conflict. The supported pattern is branch-per-claim + per-peer worktree, advisory path-claims, and master-gated integration. The companion terminal UI lives in coord-tui/ and at hyperpolymath/coord-tui.
Cartridges
BoJ catalogues 125 cartridges across trust tiers (Teranga / Shield / Ayo). Be clear about what that means:
Catalogued ≠ live.
boj_menulists the full catalogue, but most cartridges reportavailable: false. They are entries describing a capability — its API base URL, auth model (often brokered throughvault-mcp), and any native FFI path — not a running service.A cartridge becomes available when (1) its backend process is running and reachable via the BoJ REST API, and (2) you have supplied the credentials it needs.
Credentials are typically environment variables (
GITHUB_TOKEN,GITLAB_TOKEN,CF_API_TOKEN, OAuth tokens, …) or are brokered by thevault-mcpcredential cartridge.boj_cartridge_info <name>returns the cartridge’s manifest, including the exact auth requirement.Without backend or credentials, side-effectful tools return a structured
{error, hint}telling you what’s missing — they never silently fail.
Number transparency: 125 is the single source of truth — it is the number of
cartridge.jsonmanifests in the canonical boj-server-cartridges registry (the bundledcartridges/tree was retired from this repo; populate a local cache withscripts/fetch-cartridges.sh+BOJ_CARTRIDGES_PATH) and what the liveboj_menureports. Every packaging file (package.json,jsr.json,smithery.yaml,ai-plugin.json,openapi.yaml,CITATION.cff) is reconciled to it. Of those 125, most are a catalogue entry rather than a live service — see the bullets above.
Catalogued domains include: git forges & code hosting, cloud platforms (Cloudflare, Vercel, AWS, GCP, DigitalOcean, Hetzner, Fly, Linode, Railway, Render), databases (PostgreSQL, MongoDB, Redis, Neo4j, ClickHouse, DuckDB, Turso, Supabase, Neon, …), containers & Kubernetes, CI/CD & observability (Buildkite, CircleCI, Hypatia, Grafana, Prometheus, Sentry), messaging (Slack, Discord, Telegram, Matrix), productivity (Notion, Linear, Jira, Obsidian, Zotero), ML/AI & coordination, browser & web automation, code intelligence & research, developer tooling (LSP/DAP/BSP, language & package registries), security & secrets, IaC & proof systems, and hyperpolymath-native admin cartridges.
Backend
Most cartridges (GitHub/GitLab, cloud, ML, browser, CodeSeeker, etc.) call the BoJ REST API — an Elixir service on http://localhost:7700. Two modes:
Run BoJ locally — clone this repo and
just run(seedocs/quickstarts/USER.adoc). The REST API serves on port7700.Inspectable mode only — without the backend,
boj_health,boj_menu,boj_cartridges, andboj_cartridge_infostill respond from the offline manifest, so any MCP client can introspect the server. Side-effectful tools return{error, hint}until the backend is up.
Note on versions: when the backend is offline,
boj_healthmay report a placeholder backend version (0.1.0) from the bundled offline manifest — this is the manifest’s hardcoded value, not the npm package version (0.5.0). The MCP bridge itself reports0.5.0atinitialize.
The coordination bus (local-coord-mcp) is a separate localhost service, default http://127.0.0.1:7745 (COORD_BACKEND_URL).
Transports
Selected with BOJ_TRANSPORT (ADR-0013):
Value | Behaviour |
| Reads JSON-RPC from stdin, writes to stdout — how Claude Code / Desktop launch the bridge as a subprocess. |
| Starts an HTTP+SSE listener on |
| Runs stdio and HTTP simultaneously. |
HTTP auth: none (loopback only), or bearer against BOJ_HTTP_AUTH_TOKENS. mtls/oidc are planned, not yet implemented.
Configuration
Key environment variables (full schema in glama.json):
Variable | Default | Purpose |
|
| Base URL for the BoJ REST backend. |
| — | PAT for |
| — / | Token + base URL for |
|
|
|
|
| Max tool calls per minute. |
|
|
|
|
|
|
|
| HTTP transport port and bind address. |
|
| HTTP auth mode and accepted bearer tokens. |
|
| Coordination bus backend. |
|
|
|
| — | When set, every |
Security
Input hardening — per-call rate limiting (
BOJ_RATE_LIMIT), request size caps, and prompt-injection detection with Unicode-confusable normalisation.Error sanitisation — responses strip filesystem paths, stack traces, and environment variables before they reach the client.
HTTP safety —
BOJ_HTTP_AUTH=noneis refused on any non-loopback bind; bearer auth is required for remote exposure.Credential isolation — cartridge credentials are supplied per-cartridge (env vars or the
vault-mcpbroker), never embedded in tool definitions.Formal verification — the Idris2 ABI safety layer has discharged proof obligations; the only
believe_mesites are four documented axioms over the compiler’s opaqueChar/Stringprimitives, tracked inPROOF-NEEDS.adoc. See What is proven for the Proven / Witnessed / Trusted breakdown.Supply chain — SHA-pinned GitHub Actions; coherence tests assert the advertised tool list matches the cartridge manifest so nothing is advertised-but-undispatched.
Run the coherence tests:
node --test mcp-bridge/tests/Report vulnerabilities per SECURITY.md.
What is proven
Every safety claim BoJ makes sits in one of three bins. "Proven" always means proven about a model, so the claim is only as good as the match between that model and the running code. That is why the Witnessed column matters.
Planned next steps that move items left (Trusted → Witnessed → Proven) are tracked in PROOF-NEEDS.adoc: link every bound C symbol and gate CI on it, and derive tool annotations from a typed effect declaration that the dispatcher enforces.
License
Code — MPL-2.0 (Mozilla Public License 2.0) — the license published to npm and detected by GitHub.
Documentation — MPL-2.0 today (the repository’s REUSE config tags every file MPL-2.0); a CC-BY-SA-4.0 split for prose is the intended model, with the docs-licence rollout tracked as a follow-up.
Contributing & links
Repository — github.com/hyperpolymath/boj-server
Glama listing — glama.ai/mcp/servers/hyperpolymath/boj-server
Coordination TUI — hyperpolymath/coord-tui
Contributing — see
CONTRIBUTING.mdandCODE_OF_CONDUCT.md.Citing — citation metadata is in
CITATION.cff; GitHub renders a "Cite this repository" button from it.
Maintained by Jonathan D.A. Jewell.
Available Tools
41 toolsboj_browser_clickC
Click an element on the page by CSS selector
Inputs: selector (required).
boj_browser_execute_jsC
Execute JavaScript in the current page context
Inputs: script (required).
boj_browser_read_pageB
Read the text content of the current page
Inputs: no named parameters.
boj_browser_screenshotB
Take a screenshot of the current page
Inputs: no named parameters.
boj_browser_tabsC
List, create, or close browser tabs
Inputs: operation (required), url, tab_id.
boj_browser_typeC
Type text into an element on the page
Inputs: selector (required), text (required).
boj_cartridge_infoB
Get detailed information about a specific BoJ cartridge
Inputs: name (required).
boj_cartridge_invokeC
Invoke a BoJ cartridge operation. Send a command to a specific cartridge for execution.
Inputs: name (required), params.
boj_cartridgesB
Show the BoJ cartridge matrix — protocol x domain grid showing which cartridges serve which protocol/domain combinations
Inputs: no named parameters.
boj_cloud_cloudflareC
Manage Cloudflare resources — Workers, D1 databases, KV namespaces, R2 buckets, DNS zones/records
Inputs: operation (required), api_token, params.
boj_cloud_vercelC
Manage Vercel projects — deployments, domains, environment variables, logs, serverless functions
Inputs: operation (required), api_token, params.
boj_cloud_verpexC
Manage Verpex hosting via cPanel UAPI — domains, DNS, email, databases, SSL, cron, metrics
Inputs: operation (required), hostname, username, api_token, +2 more.
boj_comms_calendarC
Google Calendar operations — list events, create events, check availability
Inputs: operation (required), oauth_token, params.
boj_comms_gmailC
Gmail operations — send, read, search emails, manage labels
Inputs: operation (required), oauth_token, params.
boj_github_comment_issueD
Comment on an issue
Inputs: owner (required), repo (required), issue_number (required), body (required).
boj_github_create_issueC
Create an issue on a GitHub repo
Inputs: owner (required), repo (required), title (required), body, +1 more.
boj_github_create_prC
Create a pull request
Inputs: owner (required), repo (required), title (required), head (required), +2 more.
boj_github_get_fileC
Get file contents from a repo
Inputs: owner (required), repo (required), path (required), ref.
boj_github_get_issueD
Get a specific issue
Inputs: owner (required), repo (required), issue_number (required).
boj_github_get_prC
Get a specific pull request
Inputs: owner (required), repo (required), pull_number (required).
boj_github_get_repoC
Get a GitHub repository
Inputs: owner (required), repo (required).
boj_github_graphqlC
Execute a GitHub GraphQL query
Inputs: query (required), variables.
boj_github_list_issuesC
List issues on a GitHub repo
Inputs: owner (required), repo (required), state, per_page.
boj_github_list_prsC
List pull requests
Inputs: owner (required), repo (required), state.
boj_github_list_reposC
List your GitHub repositories
Inputs: per_page, sort.
boj_github_merge_prC
Merge a pull request
Inputs: owner (required), repo (required), pull_number (required), method.
boj_github_search_codeC
Search code on GitHub
Inputs: query (required).
boj_github_search_issuesC
Search issues and PRs on GitHub
Inputs: query (required).
boj_gitlab_create_issueC
Create a GitLab issue
Inputs: project_id (required), title (required), description.
boj_gitlab_create_mrD
Create a merge request
Inputs: project_id (required), title (required), source (required), target.
boj_gitlab_get_projectC
Get a GitLab project
Inputs: project_id (required).
boj_gitlab_list_issuesC
List GitLab project issues
Inputs: project_id (required), state.
boj_gitlab_list_mrsC
List merge requests
Inputs: project_id (required), state.
boj_gitlab_list_pipelinesC
List CI/CD pipelines
Inputs: project_id (required).
boj_gitlab_list_projectsC
List your GitLab projects
Inputs: per_page.
boj_gitlab_setup_mirrorC
Set up a push mirror
Inputs: project_id (required), target_url (required).
boj_healthB
Check BoJ server health status
Inputs: no named parameters.
boj_ml_huggingfaceC
Hugging Face operations — search models, model info, inference, spaces, datasets
Inputs: operation (required), api_token, params.
boj_researchC
Academic research — search papers, citations, references, authors
Inputs: operation (required), api_key, params.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Tools are generally well-differentiated by domain and action, with clear prefixes like 'boj_browser_', 'boj_github_', and 'boj_gitlab_' organizing them. Some potential confusion exists between similar operations across domains (e.g., 'boj_github_create_issue' and 'boj_gitlab_create_issue'), but the domain prefixes help distinguish them. A few tools like 'boj_cartridge_invoke' and 'boj_cartridge_info' have overlapping purposes but are still distinguishable by their specific functions.
Naming is highly consistent throughout, following a clear pattern of 'boj_[domain]_[action]' with snake_case used uniformly. Verbs like 'create', 'list', 'get', and 'manage' are applied predictably across domains (e.g., 'boj_github_create_issue', 'boj_gitlab_list_issues'). This consistency makes it easy for agents to understand and navigate the toolset without confusion.
With 41 tools, the count is excessive for a single server, making it feel bloated and potentially overwhelming for agents. While the tools cover multiple domains (browser, cloud, GitHub, GitLab, etc.), such a high number suggests poor scoping; it might be better split into separate, more focused servers. This heavy load can hinder agent efficiency and increase misselection risks.
The toolset shows strong coverage across its domains, with comprehensive CRUD operations for GitHub and GitLab (e.g., create, list, get, merge), browser automation, cloud management, and more. Minor gaps exist, such as missing update/delete operations for some resources (e.g., no 'update_issue' for GitLab), but agents can likely work around these. Overall, it supports a wide range of workflows without major dead ends.
Maintenance
Related MCP Connectors
Hosted MCP catalog with 30 tenant-isolated browser, RAG, AI, mail and media tools.
Capability-routed CLI/MCP: signed provenance exports, WCAG-validated themes, sovereign deploy modes.
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
Single-connection MCP gateway discovering and executing 490+ verified MCP & A2A tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAccess to many public datasets right from your LLM application.156MIT
- AlicenseNot gradedqualityNot gradedmaintenanceA feature-rich Model Context Protocol gateway that federates MCP and REST services, unifying discovery, authentication, and transport protocols while providing virtualization of legacy APIs as MCP-compliant tools.Apache 2.0
- FlicenseNot gradedqualityDmaintenanceAn advanced integrated MCP server platform that combines 600+ tools and multiple biomedical databases to enable comprehensive information retrieval across molecules, proteins, genes, and diseases for accelerating therapeutic research.40-
- AlicenseCqualityDmaintenanceAggregates multiple third-party APIs into unified MCP tools, providing out-of-the-box access to 10 popular services including OpenWeather, Google Maps, GitHub, Notion, Spotify, and more. Enables users to interact with weather data, search places, manage repositories, create content, and access various web services through a single MCP server.34MIT