# wax-mcp-full

**v0.1.0** — a local-first [MCP](https://modelcontextprotocol.io) server for the WAX blockchain.

It lets an AI host (Claude Desktop, Cursor, Grok Build, …) query accounts, chain state, AtomicAssets / AtomicMarket, Hyperion history, and WAXP prices, and **prepare unsigned transactions** for a wallet to sign. No API keys. Mainnet and testnet.

This is an early public release. It is more complete than the archived `yksanjo/wax-mcp-server` (8 tools, single RPC, dead v1 history). It is **not** a 1.0.

## Features

| Area | What you get |
|---|---|
| Account | WAXP + token balances, CPU/NET/RAM, permissions, account info |
| Chain | `get_info`, `get_block`, `get_table_rows`, ABI summary |
| History | Hyperion `/v2` actions + transaction (not v1 history) |
| AtomicAssets | assets, templates, schemas, collections, mints, transfers |
| AtomicMarket | sales, auctions, buy offers, stats, price history, recent sales, top collections |
| Market | WAXP price + market data (CoinGecko → CoinPaprika) |
| Health | multi-endpoint status |
| Safe writes | unsigned transfer / stake / unstake / vote / Atomic transfer+burn + simulate |
| Signing | **off by default** — use a wallet |

Also registers **resources** (`wax://account/{name}`, …) and **prompts** (`inspect-account`, `market-overview`, …).

## Requirements

- Node.js 20+
- HTTPS access to public WAX guild APIs (no keys)

## Install

```bash
git clone https://github.com/eoinjosephcurran-code/wax-mcp-full.git
cd wax-mcp-full
npm install
npm run build
node dist/index.js --help
```

Dev (no build):

```bash
npx tsx src/index.ts --network mainnet
```

## Add it to a host

Replace `/ABSOLUTE/PATH/TO/wax-mcp-full` with the folder you cloned.

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wax": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/wax-mcp-full/dist/index.js"],
      "env": { "WAX_NETWORK": "mainnet" }
    }
  }
}
```

Restart Claude Desktop.

### Cursor

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "wax": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/wax-mcp-full/dist/index.js"]
    }
  }
}
```

### Grok Build

`~/.grok/config.toml`:

```toml
[mcp_servers.wax]
command = "node"
args = ["/ABSOLUTE/PATH/TO/wax-mcp-full/dist/index.js"]
startup_timeout_sec = 30
```

Or: `grok mcp add wax -- node /ABSOLUTE/PATH/TO/wax-mcp-full/dist/index.js`

Copy-paste templates live in `examples/`.

## Configuration

| Variable | Meaning |
|---|---|
| `WAX_NETWORK` | `mainnet` (default) or `testnet` |
| `WAX_RPC_URLS` | Comma-separated HTTPS RPC URLs |
| `WAX_ATOMIC_URLS` | AtomicAssets / AtomicMarket hosts |
| `WAX_HYPERION_URLS` | Hyperion history hosts |
| `WAX_LIGHT_URLS` | Light API hosts |
| `WAX_PRICE_URLS` | CoinGecko / CoinPaprika bases |
| `WAX_TIMEOUT_MS` | Per-request timeout (default 12000, 1000–30000) |
| `WAX_RETRIES` | Retries per URL on transient errors (default 2) |
| `WAX_TX_EXPIRE_SECONDS` | Unsigned tx expiration (default 180) |
| `WAX_ENABLE_SIGNING` | Must be `1` **and** a key source to broadcast |
| `WAX_KEYS_FILE` | File of WIFs (one per line) — prefer this over env |

CLI: `--network mainnet\|testnet`.

Only **https** URLs are accepted. Tools never take an RPC URL argument.

`eosjs` is **not** installed by default. Prefer a wallet. Local `wax_sign_broadcast` requires `npm install eosjs` plus `WAX_ENABLE_SIGNING=1`.

## Safety

- Prepare tools return **unsigned** JSON. Sign in Anchor, WAX Cloud Wallet, or `cleos`.
- `wax_simulate_transaction` never broadcasts. Public RPCs often cannot dry-run unsigned JSON; then `simulated` is `false`.
- Never put a private key in chat or in a tool argument.

## Example prompts

- “What is the WAXP price and 24h volume?”
- “Show CPU/NET/RAM and tokens for `eosio`.”
- “List recent AtomicMarket sales for `alien.worlds`.”
- “Prepare an unsigned transfer of `1.00000000 WAX` from `alice` to `bob` — do not sign it.”

More in `examples/example-prompts.md`.

## Tests

```bash
npm test           # unit + MCP smoke + live probes (skip-soft if offline)
npm run test:live  # live probes; fail if public APIs are down
npm run typecheck
```

## Known limits (v0.1)

- Public Atomic / Hyperion nodes can be slow or rate-limit.
- Simulate is best-effort; many RPCs refuse unsigned JSON.
- MCP resources have no `isError` flag — failures are JSON inside a successful read.
- `wax_get_block` returns headers + `transaction_count`, not full transactions.
- Optional local signing is a footgun. Leave it off.

## License

MIT