Skip to content

docs(readme): fenced install blocks so MCP directories can parse them #341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hyperpolymath merged 1 commit into from
Oct 6, 2026
Merged

docs(readme): fenced install blocks so MCP directories can parse them #341

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,15 @@ ____

=== Claude Code (CLI)

[source,bash]
----
```bash
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):

```bash
npx -y @hyperpolymath/boj-server
```

=== Claude Desktop

Expand All @@ -76,8 +81,7 @@ Edit `claude++_++desktop++_++config.json`:
* *Windows* — `%APPDATA%++\++Claude++\++claude++_++desktop++_++config.json`
* *Linux* — `~/.config/Claude/claude++_++desktop++_++config.json`

[source,json]
----
```json
{
"mcpServers": {
"boj-server": {
Expand All @@ -87,7 +91,7 @@ Edit `claude++_++desktop++_++config.json`:
}
}
}
----
```

Restart Claude Desktop after saving.

Expand All @@ -100,8 +104,7 @@ The minimum stdio spec is `command: npx`, `args: ++[++"-y", "@hyperpolymath/boj-

The bridge entrypoint is `mcp-bridge/main.js` and runs on any of the three runtimes with no install:

[source,bash]
----
```bash
# Deno (no install step; the project's documented runtime)
deno run -A /path/to/boj-server/mcp-bridge/main.js

Expand All @@ -110,7 +113,7 @@ bun /path/to/boj-server/mcp-bridge/main.js

# Node (>= 18)
node /path/to/boj-server/mcp-bridge/main.js
----
```

'''''

Expand Down
75 changes: 40 additions & 35 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,11 @@

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

[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](LICENSE)
[![npm](https://img.shields.io/npm/v/@hyperpolymath/boj-server?logo=npm)](https://www.npmjs.com/package/@hyperpolymath/boj-server)
[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/boj-server)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hyperpolymath/boj-server/badge)](https://scorecard.dev/viewer/?uri=github.com/hyperpolymath/boj-server)
[![Software Heritage](https://archive.softwareheritage.org/badge/origin/https://github.com/hyperpolymath/boj-server/)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/boj-server)
[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=hyperpolymath_boj-server)](https://sonarcloud.io/summary/new_code?id=hyperpolymath_boj-server)
| Published | [![npm](https://img.shields.io/npm/v/@hyperpolymath/boj-server?logo=npm)](https://www.npmjs.com/package/@hyperpolymath/boj-server) [![Software Heritage](https://img.shields.io/badge/SWH-Archived-blue?logo=softwareheritage)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/boj-server) [![Boj Server MCP score](https://aiagentslisting.com/boj-server/badge.svg?variant=score)](https://aiagentslisting.com/mcp/boj-server) |
|----|----|
| **Runtimes** | [![Bun](https://img.shields.io/badge/bun-%3E%3D1.0-black?logo=bun)](https://bun.sh) [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js)](https://nodejs.org) [![Deno](https://img.shields.io/badge/deno-compatible-blue?logo=deno)](https://deno.land) |
| **Security & Health** | [![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/boj-server) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hyperpolymath/boj-server/badge)](https://scorecard.dev/viewer/?uri=github.com/hyperpolymath/boj-server) [![Quality Gate](https://img.shields.io/sonar/quality_gate/hyperpolymath_boj-server?server=https%3A%2F%2Fsonarcloud.io&logo=sonarcloud)](https://sonarcloud.io/summary/new_code?id=hyperpolymath_boj-server) |
| **Compliance** | [![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](LICENSE) [![REUSE Compliance](https://api.reuse.software/badge/github.com/hyperpolymath/boj-server)](https://api.reuse.software/info/github.com/hyperpolymath/boj-server) [![Green Web Hosted](https://img.shields.io/greenweb/boj-server.net?logo=thegreenwebfoundation)](https://www.thegreenwebfoundation.org/green-web-check/?url=boj-server.net) |

> **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](#cartridges) for the full story.

Expand Down Expand Up @@ -68,6 +67,12 @@ BoJ ships as an MCP server over **stdio**. The published npm package (`@hyperpol
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):

``` bash
npx -y @hyperpolymath/boj-server
```

## Claude Desktop

Edit `claude_desktop_config.json`:
Expand Down Expand Up @@ -139,16 +144,16 @@ The server also implements `resources/list` (7 `boj://` resources) and `prompts/

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

Expand Down Expand Up @@ -200,32 +205,32 @@ The coordination bus (`local-coord-mcp`) is a separate localhost service, defaul

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. |
| 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`](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`. |
| 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

Expand Down
Loading