# bloxberg-mcp

An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for the
[bloxberg](https://bloxberg.org) blockchain — the permissioned Ethereum-based network
operated by 50+ research institutions worldwide.

Connect any MCP-capable AI assistant (Claude Code, Claude Desktop, Cursor, …) to
bloxberg: query chain state, explore transactions and contracts, and **verify Research
Object Certificates** (W3C Verifiable Credentials anchored on-chain) — the first MCP
server with native support for bloxberg's scientific-data certification stack.

## Tools

| Tool | What it does |
|---|---|
| `get_network_info` | Chain id, latest block, gas price, node version, endpoints |
| `get_block` | Block by number, hash, or `latest` |
| `get_transaction` | Transaction + receipt by hash |
| `get_balance` | Native BERG balance of an address |
| `read_contract` | Call any read-only contract function via a human-readable ABI signature |
| `get_address_transactions` | Address tx history (Blockscout explorer, paginated) |
| `get_token_info` | ERC-20/721/1155 token metadata (Blockscout) |
| `get_contract_source` | Verified contract source + ABI (Blockscout) |
| `inspect_certificate` | Parse a Research Object Certificate locally — issuer, subject, proof info |
| `verify_certificate` | Full cryptographic verification of a certificate against the chain, using the bloxberg [`cert-verifier-js`](https://www.npmjs.com/package/@bloxberg-org/cert-verifier-js-bloxberg) engine (MerkleProof2019 replay, on-chain Merkle-root comparison, issuer identity, status) |

## Networks

| `network` value | Chain | chainId | RPC |
|---|---|---|---|
| `l1` (default) | bloxberg mainnet (Proof-of-Authority) | 8995 | `https://core.bloxberg.org` |
| `l2-testnet` | bloxberg 2.0 testnet (Arbitrum AnyTrust) | 77888 | `https://explorer.l2.bloxberg.org/rpc` |

## Setup

Requires Node.js ≥ 20.

```bash
git clone https://github.com/adi-ghag/bloxberg-mcp.git
cd bloxberg-mcp
npm install && npm run build
```

**Claude Code:**

```bash
claude mcp add bloxberg -- node /path/to/bloxberg-mcp/dist/index.js
```

**Claude Desktop / generic MCP client** (`mcpServers` config):

```json
{
  "mcpServers": {
    "bloxberg": {
      "command": "node",
      "args": ["/path/to/bloxberg-mcp/dist/index.js"]
    }
  }
}
```

Then ask your assistant things like:

- *"What's the latest block on bloxberg?"*
- *"Read `name()` from contract 0x787B…4C41 on the bloxberg L2 testnet"*
- *"Here's my research certificate JSON — verify it against the chain."*

## Example: verifying a Research Object Certificate

bloxberg anchors only the **Merkle root of a certificate batch** on-chain — an
individual file hash is never on-chain by itself, so verification requires the full
credential document. `verify_certificate` accepts the credential JSON (inline or by URL)
and replays the whole pipeline: format validation → MerkleProof2019 proof replay →
on-chain root comparison → issuer identity → status. The result lists every step with
its pass/fail status.

## Development

```bash
npm test           # unit tests (mocked network)
npm run test:live  # + integration tests against real bloxberg endpoints
npx tsx scripts/smoke.mts   # manual end-to-end smoke test
```

## Limitations (v1)

- Read-only by design: no transaction signing or sending — the server never touches keys.
- `verify_certificate` supports credentials anchored on bloxberg L1 (what the published
  verifier engine knows). Verification of L2-testnet-anchored credentials is
  experimental and may fail chain lookup.
- Explorer tools use the Blockscout **v1** API (the v2 REST API is disabled on
  bloxberg's Blockscout instances).

## License

MIT © Aditya Ghag