# WBTC MCP Server

Read-only MCP server for WBTC transparency data. The server runs locally over stdio and uses WBTC Public API `/public/v1` as its only data source.

## Version

| Item | Value |
| --- | --- |
| Server version | `1.0.0` |
| MCP SDK | `@modelcontextprotocol/sdk@1.29.0` |
| Public API | WBTC Public API `v1` |
| License / SPDX | `UNLICENSED` |

## Tools

- `get_proof_of_reserve`: reserve health only, returns `reserveRatio`.
- `get_supply`: supply only, returns `circulatingSupply` and native-chain `byChain[]`.
- `get_reserves`: reserve assets only, returns `nativeBtcReserve`, `btcPriceUsd`, and `reserveValueUsd`.
- `list_chains`: chain and contract metadata only.
- `list_custodian_addresses`: custodian BTC reserve address evidence only.
- `list_mint_burn_records`: paginated mint/burn records with filters.
- `list_merchants`: public merchant directory entries.
- `list_custodians`: public custodian directory entries.
- `list_ecosystem_projects`: public ecosystem project entries.

`get_about` is not registered yet because the current Public API v1.0 schema has no `/about` endpoint or equivalent public contract. It should be added after the upstream contract is defined.

Every tool declares a strict MCP `inputSchema` and a tool-specific `outputSchema`. No-argument tools use `{ "type": "object", "properties": {}, "additionalProperties": false }`.

## Configuration

| Env var | Default |
| --- | --- |
| `WBTC_PUBLIC_API_TIMEOUT_MS` | `8000` |

The Public API base URL is fixed in the package as `https://openapi.wbtc.network/public/v1`; users do not need to configure it.
The package does not read wallet keys, seed phrases, cloud credentials, or other sensitive local environment variables.
Authentication is not required because the server calls only public read-only API endpoints. The fixed base URL also prevents user-supplied URL SSRF patterns.

## Local Development

```bash
npm ci
npm run build
npm test
npm run test:e2e:staging
```

## Internal QA Install

Until official npm publishing is ready, install from the repository checkout:

```bash
cd services/wbtc-mcp
npm ci
npm run build
npm install -g .
```

Or install from an internally generated tarball:

```bash
npm install -g ./wbtc-mcp-1.0.0.tgz
```

MCP client configuration:

```json
{
  "mcpServers": {
    "wbtc": {
      "command": "wbtc-mcp",
      "env": {
        "WBTC_PUBLIC_API_TIMEOUT_MS": "15000"
      }
    }
  }
}
```

Repository-local QA notes live in `docs/usage.md`.