Getting Started

Getting Started

Install

The bridge ships as an npm package and has zero runtime dependencies. It runs on Node, Deno or Bun — all three are exercised in CI.

# Claude Code
claude mcp add boj-server -- npx -y @hyperpolymath/boj-server

# or clone and run the bridge directly
git clone https://github.com/hyperpolymath/boj-server
node boj-server/mcp-bridge/main.js

There is no npm install step for the bridge itself. If a document tells you to run one, it predates the zero-dependency refactor.

Fetch the cartridges

Cartridges are not in this repository — see Home. Without a cache the catalogue is empty:

scripts/fetch-cartridges.sh
export BOJ_CARTRIDGES_PATH="$HOME/.boj/cartridges"

BOJ_CARTRIDGES_REF and BOJ_CARTRIDGES_REPO override the ref and source; see the script's own header, which is the authoritative description of its behaviour.

Verify it works

The bridge is inspectable with no backend running — that is deliberate:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node mcp-bridge/main.js

For the full stack (Elixir REST on :7700 + bridge), see BUILD-FROM-SOURCE.

Toolchain

Pinned in .tool-versions — that file is the source of truth, not this page. At time of writing: Zig 0.16.0, Idris2 0.8.0, Deno 2.7.x, Elixir 1.18 / OTP 27.

Zig 0.16 removed std.Thread.Mutex, std.time.*Timestamp, std.crypto.random and std.posix.getenv. The canonical shim ffi/zig/src/cartridge_shim.zig provides replacements over std.Io. Build against 0.16 or newer.

Quickstarts by audience

• USER — consume the server
• DEV — work on it
• BUILD-FROM-SOURCE — full stack from scratch
• MAINTAINER — operate and release