# poworacle

Live proof-of-work mining data as MCP tools: how long a solo
miner would wait for a block, what it costs to produce one coin,
the current state of a network, which hardware earns what, and
recent mining news.

poworacle is a keyless forwarding client. It serves six tools
over stdio MCP (and as CLI subcommands) and forwards each call
to the public BackPow MCP endpoint at
`https://mcp.backpow.com/mcp` — no API key, no account, nothing
to configure. The upstream server is stateless, so each call is
a single Streamable HTTP POST carrying a `tools/call` JSON-RPC
request; the upstream result's content is returned verbatim.
Upstream JSON-RPC errors come back as `backpow error:
<message>`, an unparseable response as `backpow error:
malformed response`, and a transport failure (including a
timeout) as `backpow unreachable`.

Two environment variables adjust the client (both are this
rebuild's own knobs, not upstream requirements):

| Variable | Default | Purpose |
| --- | --- | --- |
| `BACKPOW_MCP_URL` | `https://mcp.backpow.com/mcp` | Endpoint override |
| `BACKPOW_TIMEOUT_MS` | `30000` | Per-call timeout, AbortController-enforced |

## Tools

| Tool | Answers |
| --- | --- |
| `calculate_solo_mining_odds` | Mean time to a block and Poisson odds over 1/7/30/90/365 days for a given coin and hashrate, plus the electricity cost of the attempt |
| `get_cost_of_production` | All-in electricity cost of mining one unit on the most efficient tracked hardware, against spot price and margin |
| `get_coin_oracle` | Live difficulty, hashrate, block height and reward for one chain, with a measurement-confidence block |
| `list_pow_coins` | Paginated catalogue of tracked PoW networks, filterable by algorithm or profitability |
| `get_hardware_benchmarks` | Hardware matched to the coins it can mine, ranked by net USD per day at a given electricity rate |
| `get_pow_news` | Recent PoW mining and network news, optionally filtered to one coin |

Ambiguity and missing measurements are refused upstream rather
than guessed or substituted, and those errors pass through
unchanged apart from the `backpow error:` rendering.

## CLI

```bash
npx @reneturcios/poworacle get_coin_oracle '{"coin_id":"Kaspa"}'
npx @reneturcios/poworacle calculate_solo_mining_odds '{"coin_id":"Bitcoin","hashrate":100,"hashrate_unit":"TH/s"}'
npx @reneturcios/poworacle list_pow_coins '{"algorithm":"SHA-256"}'
npx @reneturcios/poworacle --version
```

Each tool subcommand takes one JSON argument string. Exit
codes: 0 on success, 1 when the tool result is an error, 2 on
a usage error (unknown command, extra arguments, or a
non-object JSON argument).

## MCP

```bash
npx @reneturcios/poworacle mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "poworacle": {
      "command": "npx",
      "args": ["-y", "@reneturcios/poworacle", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/poworacle          # stdio MCP server (CMD defaults to "mcp")
docker run --rm ghcr.io/cloudcorprecords/poworacle get_pow_news '{"coin_id":"Bitcoin"}'
```

## Development

```bash
npm install
npm run build      # tsc -> dist/ (dist/cli.js is the bin)
npm test           # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev        # tsx src/cli.ts — run the CLI from source
```

## License

MIT — see [LICENSE](LICENSE).