Skip to main content
Glama

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

npm Software Heritage Boj Server MCP score

Runtimes

Bun Node Deno

Security & Health

OpenSSF Best Practices OpenSSF Scorecard Quality Gate

Compliance

License: MPL-2.0 REUSE Compliance Green Web Hosted

What it is, honestly: BoJ exposes 68 MCP tools today (45 boj_* + 23 coord_*) 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 23 coord_* multi-agent coordination tools.

  • 125-cartridge catalogue — a single boj_cartridge_invoke reaches any catalogued cartridge; explicit boj_<domain>_<verb> tools exist for the highest-frequency operations.

  • Multi-instance AI coordination — local-coord-mcp lets 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, and boj_cartridge_info answer 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@latest

Or run the server directly with npx (any MCP client that launches a stdio command):

npx -y @hyperpolymath/boj-server

Related MCP server: MCP Context Forge Gateway

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"]
    }
  }
}

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

Quickstart

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

The 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

boj_health, boj_menu, boj_cartridges, boj_cartridge_info, boj_cartridge_invoke

GitHub

14

boj_github_list_repos, boj_github_create_issue, boj_github_create_pr, boj_github_merge_pr, boj_github_search_code, boj_github_graphql

GitLab

8

boj_gitlab_list_projects, boj_gitlab_create_mr, boj_gitlab_list_pipelines, boj_gitlab_setup_mirror

Browser (Firefox)

7

boj_browser_navigate, boj_browser_click, boj_browser_type, boj_browser_read_page, boj_browser_screenshot, boj_browser_tabs, boj_browser_execute_js

Cloud

3

boj_cloud_cloudflare, boj_cloud_vercel, boj_cloud_verpex

Communications

2

boj_comms_gmail, boj_comms_calendar

Research / code intel / ML / search

4

boj_research, boj_codeseeker, boj_ml_huggingface, boj_search

Coordination (local-coord-mcp)

23

coord_register, coord_claim_task, coord_send, coord_review, coord_approve, coord_health

Set BOJ_TOOL_SCOPE=core to advertise only the discovery surface; explicit boj_<domain>_* tools remain reachable via boj_cartridge_invoke regardless. 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_task with role-based watchdog TTL, coord_progress heartbeats, coord_sweep_watchdog, optional advisory paths for path_overlap warnings.

  • Track record — coord_report_outcome, coord_get_affinities, coord_set_declared_affinities, coord_scan_suggestions (emits overclaim/drift advisory envelopes).

  • Supervision — coord_review, coord_review_entry, coord_approve, coord_reject, coord_promote_to_master, coord_transfer_master, plus coord_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_menu lists the full catalogue, but most cartridges report available: false. They are entries describing a capability — its API base URL, auth model (often brokered through vault-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 the vault-mcp credential 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.json manifests in the canonical boj-server-cartridges registry (the bundled cartridges/ tree was retired from this repo; populate a local cache with scripts/fetch-cartridges.sh + BOJ_CARTRIDGES_PATH) and what the live boj_menu reports. 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:

  1. Run BoJ locally — clone this repo and just run (see docs/quickstarts/USER.adoc). The REST API serves 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, 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_health may 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 reports 0.5.0 at initialize.

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

stdio (default)

Reads JSON-RPC from stdin, writes to stdout — how Claude Code / Desktop launch the bridge as a subprocess.

http

Starts an HTTP+SSE listener on BOJ_HTTP_PORT (default 7780) for remote / Workers / browser deployments. Binds 127.0.0.1 by default; BOJ_HTTP_AUTH=none is refused on a non-loopback bind.

both

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

BOJ_URL

http://localhost:7700

Base URL for the BoJ REST backend.

GITHUB_TOKEN

—

PAT for boj_github_* tools.

GITLAB_TOKEN / GITLAB_URL

— / https://gitlab.com

Token + base URL for boj_gitlab_* tools.

BOJ_TOOL_SCOPE

full

full, core, or a CSV of domain prefixes (e.g. core,github,browser).

BOJ_RATE_LIMIT

60

Max tool calls per minute.

BOJ_LOG_LEVEL

info

debug / info / warn / error / silent.

BOJ_TRANSPORT

stdio

stdio / http / both.

BOJ_HTTP_PORT / BOJ_HTTP_BIND

7780 / 127.0.0.1

HTTP transport port and bind address.

BOJ_HTTP_AUTH / BOJ_HTTP_AUTH_TOKENS

none / —

HTTP auth mode and accepted bearer tokens.

COORD_BACKEND_URL

http://127.0.0.1:7745

Coordination bus backend.

COORD_REQUIRE_NICKEL

0

1 enables strict Nickel-contract validation on gated envelopes.

OTEL_EXPORTER_OTLP_ENDPOINT

—

When set, every tools/call emits an OTLP/JSON span to <endpoint>/v1/traces.

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=none is 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-mcp broker), never embedded in tool definitions.

  • Formal verification — the Idris2 ABI safety layer has discharged proof obligations; the only believe_me sites are four documented axioms over the compiler’s opaque Char/String primitives, tracked in PROOF-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

Maintained by Jonathan D.A. Jewell.

Available Tools

41 tools
boj_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_navigateC

Navigate Firefox to a URL

Inputs: url (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_menuB

List all BoJ cartridges with their domains, protocols, tiers, and availability

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

    C2.8/5.0

    Scored across 41 tools

    Disambiguation4/5

    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 Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A 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
    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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
      -
    • A
      license
      C
      quality
      D
      maintenance
      Aggregates 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.
      34
      MIT