BSV-AIO-MCP

A read-only Model Context Protocol server that gives any MCP-capable assistant (Cursor, Claude Desktop, Claude Code, …) grounded answers about Bitcoin SV: the BRC specifications, Bitcoin Script opcodes, BEEF transaction formats, the Rúnar smart-contract toolchain, the Tier 0 SDKs (@bsv/sdk, @bsv/wallet-toolbox, go-sdk, go-wallet-toolbox) and a structured corpus of Craig Wright's essays.

It answers from a pinned snapshot of these sources — never from the live web.

Design invariants

• Snapshot-only. Every claim quotes a contiguous slice of a cited, pinned document. The server never fetches live HTTP and never actuates (no broadcasting, no wallet creation, no faucet claims). Live facts are declared in needs for the host to resolve.

• Fail-closed. When the snapshot cannot answer, the server says so (insufficient + a specific gap) instead of presenting incidental mentions as an answer.

• Authority model. BRCs rank 1, SDK/package cards 2, ops playbooks 3, essays 4. A named or governing spec always outranks commentary.

• Deny list. Deprecated/unsafe packages (bsv, run-sdk, js-1sat-ord, …) are never recommended; naming one as a dependency returns the denial, its reason (e.g. CVE-2025-69287) and its successor.

• Recency honesty. "Latest/newest/superseded" questions are answered as of the pin date, with the pin declared in the package's gaps.

Related MCP server: Official Solana MCP Server

Install

Requires Node.js ≥ 22.13. No build step, no API keys, no network access at runtime.

Add to your MCP client config — Cursor (~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), or equivalent:

{
  "mcpServers": {
    "bsv-aio": {
      "command": "npx",
      "args": ["-y", "bsv-aio-mcp"]
    }
  }
}

Restart the client. The server builds its local SQLite index from the shipped snapshot on first launch (a few seconds), then answers over stdio.

From source

git clone https://github.com/BMX-Casey94/BSV-AIO-MCP.git
cd BSV-AIO-MCP
npm install
npm run build

Then point the client at the built entry directly:

{
  "mcpServers": {
    "bsv-aio": {
      "command": "node",
      "args": ["C:/path/to/BSV-AIO-MCP/server/dist/index.mjs"]
    }
  }
}

Configuration

Tools

The corpus

The snapshot pins: the BRC index and full BRC bodies; BSV Academy opcode/Script documentation; the Rúnar documentation set; Tier 0 package/symbol/spec cards plus Tier 0/1 repo documentation (READMEs, docs, examples) with evidenced BRC-to-package edges; a deny list; testnet operations notes; ordinality/provenance rules; curated Teranode throughput benchmark facts (AWS 1M TPS trial, SSRN 79.09B TPS preprint — conditions and sources inline); an attributed analysis card on Bitcoin's 2014–2017 direction change (documented / disputed / unproven kept separate); and 476 summarised Craig Wright essays (Medium 2018–2022 and Substack 2025–2026) with a curated contradiction map. See CORPUS.md for the full corpus documentation.

The snapshot is the product: answers are reproducible and auditable against it. It does not update itself. npx bsv-aio-mcp serves whatever pin was inside the last npm publish. The operator refreshes weekly (or on a repo tag) with the gated jobs below, then republishes so consumers receive the new pin. Full policy: mcp/refresh-policy.md.

$env:BSV_AIO_ALLOW_REFRESH = "1"
npm run refresh:tier0 --workspace=server   # Tier 0 SDKs/wallets + BRC bodies (regenerates brc_index.json)
npm run refresh:tier1 --workspace=server   # Tier 1 services/libraries
npm run fetch:academy --workspace=server   # Academy + Rúnar
npm test

Each job is guarded against accidental corpus collapse (80% retention). Review the diff, commit, bump the patch version, and npm publish.

Development

npm install          # install workspace deps
npm run build        # bundle server/dist
npm test             # 210 tests: goldens (A–D), tools, composition, ingest
npm run typecheck    # tsc --noEmit
node server/probe-full-battery.mjs   # adversarial smoke battery against the built server

Security model

Stdio transport only — no network listener. All tool inputs are schema-validated with length caps; FTS queries are tokenised, quoted and capped; snapshot file reads are confined to the corpus root (symlink-resolved); the serving database handle is reopened read-only after ingest; the deny list and live-fetch refusal cannot be bypassed by prompt phrasing. The threat model and test battery are in server/test/.