# Radiant MCP Server

**Model Context Protocol (MCP) server for the Radiant blockchain** — lets AI agents query chain state, manage Glyph tokens, resolve WAVE names, and — when given a private key — build, sign, and broadcast transactions on the Radiant network.

> ## ⚠️ This server can hold private keys and move funds
>
> Unlike a read-only data server, radiant-mcp-server exposes a full **write/signing surface**. It can:
>
> - **Store WIF private keys server-side** in a keyring at `~/.radiant-mcp/keyring.json` (override with `RADIANT_KEYRING_FILE`). The file is required to be `0600` (owner read/write only) on POSIX — the server refuses to load it otherwise.
> - **Generate and restore wallets** — random keys and BIP39 mnemonics — returning WIF private keys and seed phrases in tool output.
> - **Build, sign, and broadcast transactions** — send RXD, batch-pay, and mint / transfer / burn Glyph tokens — using either a transient WIF passed per call or a key referenced by alias from the keyring.
>
> Any agent or client connected to this server can invoke those tools. **Treat connecting it like handing over a hot wallet.** Read [Security & key handling](#security--key-handling) before exposing it beyond loopback.

## Features

### 59 tools across 12 categories

Read/query tools need no keys. The **Keyring**, **Wallet**, and **Transactions** categories hold or receive private keys and can move funds — see [Security & key handling](#security--key-handling).

#### Read & query — no private keys

**Blockchain (8 tools)**
- `radiant_get_chain_info` — Current chain status (height, tip hash, network params)
- `radiant_get_balance` — RXD balance for an address (confirmed + unconfirmed)
- `radiant_get_utxos` — List unspent outputs for an address
- `radiant_get_history` — Full transaction history for an address (returns all entries — large for active addresses)
- `radiant_get_transaction` — Transaction details by txid
- `radiant_get_block_header` — Block header by height
- `radiant_estimate_fee` — Fee estimate (ElectrumX estimate + min-relay policy floor)
- `radiant_broadcast_transaction` — Broadcast a **pre-signed** raw tx (no key required, but publishes to the network)

**Glyph Tokens (10 tools)**
- `radiant_get_token` — Token info by reference
- `radiant_list_tokens` — Tokens held by an address
- `radiant_get_token_balance` — Specific token balance for an address
- `radiant_search_tokens` — Search tokens by name/ticker
- `radiant_get_token_metadata` — Full CBOR metadata
- `radiant_get_token_history` — Token transaction history
- `radiant_get_tokens_by_type` — Filter tokens by type (FT/NFT/etc.)
- `radiant_validate_protocols` — Check whether a Glyph protocol combination is valid
- `radiant_parse_glyph_envelope` — Decode a Glyph envelope from raw script hex
- `radiant_get_token_utxos` — Discover all token UTXOs (and their `tokenRef`s) held by an address

**dMint Mining (4 tools)**
- `radiant_get_dmint_contracts` — List active mineable tokens
- `radiant_get_dmint_contract` — Details for one dMint contract
- `radiant_get_dmint_by_algorithm` — dMint contracts filtered by mining algorithm
- `radiant_get_most_profitable_dmint` — dMint contracts ranked by profitability

**WAVE Naming (5 tools)**
- `radiant_resolve_wave_name` — Resolve a WAVE name to its zone records
- `radiant_check_wave_available` — Check name availability
- `radiant_wave_reverse_lookup` — Names owned by an address
- `radiant_wave_subdomains` — List child names of a WAVE name
- `radiant_wave_stats` — Naming-system statistics

**DEX / Swap (2 tools)**
- `radiant_get_swap_orders` — Open swap orders for a pair (on-chain orderbook)
- `radiant_get_swap_history` — Trade history for a token

**Connection & Monitoring (3 tools)**
- `radiant_connection_health` — ElectrumX connection status and latency
- `radiant_reconnect` — Force a fresh ElectrumX reconnect when the session is wedged
- `radiant_watch_address` — Subscribe to real-time payment notifications for an address (ElectrumX scripthash subscription)

**Utility / Reference (2 tools)**
- `radiant_get_protocol_info` — Glyph protocol type reference
- `radiant_validate_address` — Validate an address; show its type (P2PKH/P2SH) and scripthash

**Script Tools — offline (2 tools)**
- `radiant_decode_script` — Decode raw script hex into human-readable opcodes (no network)
- `radiant_compile_script` — Compile RadiantScript (`.cash`/`.rxd`) source into a deployment artifact (ABI, ASM, hex). Offline; requires the `rxdc` compiler binary (set `RXDC_PATH`, or keep the RadiantScript repo as a sibling directory)

**On-Chain AI Primitives (9 tools)**
- `radiant_create_inference_proof` — blake3 inference-proof commitment `hash(modelHash ‖ inputHash ‖ output)`
- `radiant_verify_inference_proof` — Verify an inference-proof commitment off-chain
- `radiant_build_agent_profile` — Build an AI-agent identity profile (+ WAVE zone records) with a blake3 commitment
- `radiant_resolve_agent_identity` — Resolve an agent's identity (capabilities, pricing, API endpoint) from its WAVE name
- `radiant_check_token_access` — Token-gated access check (does an address hold the minimum balance?)
- `radiant_open_channel` — Build initial state for a micropayment channel
- `radiant_update_channel` — Update channel state (transfer photons payer → payee)
- `radiant_build_data_asset` — Build Glyph NFT metadata for a data-marketplace asset
- `radiant_search_data_assets` — Search the data marketplace (datasets, models, etc.)

> These AI primitives compute commitments/metadata or read chain state — they do **not** hold keys or broadcast. Use the Transactions tools below to publish their output on-chain.

#### Write & signing — private keys involved

> 🔑 The next three categories are the security-relevant surface. See [Security & key handling](#security--key-handling).

**Keyring — server-side WIF storage (3 tools)**
- `radiant_register_key` — Store a WIF private key under an alias in the server-side keyring (`~/.radiant-mcp/keyring.json`, `0600`). Lets signing tools reference the key by `key_alias` instead of resending the WIF on every call
- `radiant_list_keys` — List registered aliases and their derived addresses (WIFs are **never** returned)
- `radiant_remove_key` — Remove an alias from the keyring

**Wallet — key generation & derivation (3 tools)**
- `radiant_create_wallet` — Generate a new wallet (random key, or BIP39 mnemonic with BIP32 HD derivation). **Returns the WIF and, if requested, the mnemonic**
- `radiant_restore_wallet` — Restore a wallet from a BIP39 mnemonic. **Returns the derived WIF**
- `radiant_derive_address` — Derive an address / public key / WIF from a mnemonic + BIP32 path (per-task sub-wallets)

**Transactions — build, sign & broadcast (8 tools)**

Each accepts either a transient `wif` (sent through the transport) **or** a `key_alias` from the keyring. Unless noted, these sign **and broadcast**.
- `radiant_send_rxd` — Send RXD: select coins, build, sign, broadcast 🔑
- `radiant_send_batch` — Send RXD to up to 100 recipients in one transaction 🔑
- `radiant_transfer_token` — Transfer a Glyph FT/NFT to another address 🔑
- `radiant_burn_token` — Permanently burn a Glyph token (Glyph protocol 6) 🔑
- `radiant_create_ft` — Mint a Glyph Fungible Token (2-tx commit+reveal) 🔑
- `radiant_create_nft` — Mint a Glyph NFT (2-tx commit+reveal) 🔑
- `radiant_build_transaction` — Build **and sign** a transaction in dry-run mode; returns raw hex/fee/size **without** broadcasting (set `dry_run=false` to broadcast). Inspect before committing high-value txs 🔑
- `radiant_estimate_tx_fee` — Estimate fee from input/output counts (pure arithmetic — **no key, no network, no broadcast**)

### 10 Resources

**Static reference data (6)**
- `radiant://docs/chain-overview` — Blockchain overview
- `radiant://docs/opcodes` — Opcode reference (including V2)
- `radiant://docs/protocols` — Glyph protocols, dMint algorithms, DAA modes
- `radiant://docs/network-params` — Network parameters (JSON)
- `radiant://docs/sdk-quickstart` — radiantjs quick-start guide
- `radiant://docs/knowledge-base` — Comprehensive AI knowledge base

**Dynamic / live data (4)**
- `radiant://chain/status` — Live chain status (height, tip hash, sync state)
- `radiant://dmint/active` — Currently active dMint contracts
- `radiant://network/fees` — Fee estimates for several confirmation targets
- `radiant://tokens/popular` — Popular fungible tokens and NFT collections

## Transports

The same 59 tools and 10 resources are exposed over three transports (all driven by the single source of truth in `src/register-tools.ts`):

| Transport | Entry | Start | Default bind |
|-----------|-------|-------|--------------|
| **stdio** (MCP) | `dist/index.js` | `npm start` / `npm run dev` | local process (used by Windsurf, Claude Desktop, Cursor) |
| **REST** (HTTP) | `dist/rest.js` | `npm run start:rest` | `127.0.0.1:3080` |
| **SSE** (MCP over HTTP) | `dist/sse.js` | `npm run start:sse` | `127.0.0.1:3090` |

### REST API

A standard REST API mirrors the tools for any HTTP client. Key-handling endpoints (`/keyring/*`, `/wallet/*`, `/tx/*`, `/token/*`) are auth-gated — see [Security & key handling](#security--key-handling).

```bash
# Start REST server
npm run start:rest

# Query chain info
curl http://localhost:3080/api/chain

# Get address balance
curl http://localhost:3080/api/address/1A1zP1.../balance

# Search tokens
curl http://localhost:3080/api/tokens/search?q=mytoken

# Full endpoint list
curl http://localhost:3080/api
```

OpenAPI 3.1 spec: `docs/openapi.yaml`

## Security & key handling

This server has a real write surface. The defaults are loopback-only and conservative, but you should understand them before exposing the server.

### How private keys reach the server

1. **Transient WIF** — pass `wif` on each signing call. It travels through the MCP/HTTP transport and may appear in agent transcripts and client logs.
2. **Server-side keyring** — call `radiant_register_key` once, then reference the key by `key_alias` on later calls. The WIF stays out of subsequent transport/transcripts but is **persisted on disk** in the keyring file.

### The keyring file

- Location: `~/.radiant-mcp/keyring.json` (override with `RADIANT_KEYRING_FILE`).
- Permissions: must be `0600` (owner read/write only) on POSIX. The server **refuses to load** a keyring with looser permissions (`chmod 600 <path>` to fix), and writes new entries back at `0600`.
- Contents: WIF private keys in plaintext JSON. Anyone who can read this file controls the funds. `radiant_list_keys` never returns WIFs, but the file itself does contain them.

### Network exposure & auth (REST and SSE)

Both HTTP transports **default to loopback** (`HOST=127.0.0.1`) so key-handling tools are not exposed to the LAN by accident.

- **REST** — key-handling endpoints (`/keyring/*`, `/wallet/create`, `/wallet/restore`, `/wallet/derive`, `/tx/send`, `/tx/build`, `/tx/send-batch`, `/token/create/ft`, `/token/create/nft`, `/token/transfer`, `/token/burn`) are wrapped in an auth check:
  - `RADIANT_API_TOKEN` **set** → those endpoints require `Authorization: Bearer <token>`.
  - `RADIANT_API_TOKEN` **unset** → those endpoints are **loopback-only** (`127.0.0.1` / `::1`); non-loopback requests get `401`.
  - This holds even if you set `HOST=0.0.0.0` — key endpoints stay locked down until a token is configured. **Read-only endpoints are not token-gated**, so binding to `0.0.0.0` exposes read queries to the network.
- **SSE** — binds loopback by default and logs a warning if `HOST` is non-loopback, because the SSE transport exposes the WIF-handling tools. Put an authenticated reverse proxy in front before allowing remote access.

To expose write endpoints remotely: set `RADIANT_API_TOKEN` to a strong secret, set `HOST=0.0.0.0` (ideally behind a TLS-terminating reverse proxy), and send the bearer token on every key-handling request.

### Safety switch

Set `RADIANT_TEST_MODE` (to any value other than `0`/`false`) to block real broadcasts — `radiant_broadcast_transaction` and the signing tools will refuse to publish. Useful for dry runs and CI.

## Installation

```bash
npm install
npm run build
```

## Configuration

### Windsurf / Cascade

Add to your MCP settings (`~/.codeium/windsurf/mcp_config.json`):

```json
{
  "mcpServers": {
    "radiant": {
      "command": "node",
      "args": ["/path/to/radiant-mcp-server/dist/index.js"],
      "env": {
        "ELECTRUMX_HOST": "electrumx.radiantcore.org",
        "RADIANT_NETWORK": "mainnet"
      }
    }
  }
}
```

> ⚠️ This launches the full server, including the keyring, wallet, and signing tools. Any key registered via `radiant_register_key` is written to `~/.radiant-mcp/keyring.json` and is usable by the agent on every subsequent call. Only connect it in an environment you trust to act on those funds.

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "radiant": {
      "command": "node",
      "args": ["/path/to/radiant-mcp-server/dist/index.js"],
      "env": {
        "ELECTRUMX_HOST": "electrumx.radiantcore.org"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ELECTRUMX_WSS` | `true` | Connect over secure WebSocket (`wss://host`, port 443). Firewall-proof and works on mobile/corporate networks; requires Node 22+. Set `false` to use a raw TCP/SSL socket instead. |
| `ELECTRUMX_HOST` | `electrumx.radiantcore.org` | ElectrumX server hostname |
| `ELECTRUMX_PORT` | `443` (wss) / `50012` (raw) | ElectrumX server port |
| `ELECTRUMX_SSL` | `true` | Use TLS for a raw socket (ignored when `ELECTRUMX_WSS=true`) |
| `RADIANT_NETWORK` | `mainnet` | Network: `mainnet` or `testnet` |
| `HOST` | `127.0.0.1` | Bind address for the REST and SSE servers (loopback by default) |
| `PORT` | `3080` | REST API port (also the SSE fallback port) |
| `SSE_PORT` | `3090` | SSE server port |
| `CORS_ORIGIN` | `*` | CORS allowed origin (REST) |
| `RADIANT_API_TOKEN` | _(unset)_ | Bearer token required for key-handling REST endpoints. When unset, those endpoints are loopback-only |
| `RADIANT_KEYRING_FILE` | `~/.radiant-mcp/keyring.json` | Path to the server-side keyring (must be `0600` on POSIX) |
| `RADIANT_TEST_MODE` | _(unset)_ | When set (and not `0`/`false`), blocks real transaction broadcasts |
| `RADIANT_RESPONSE_FORMAT` | `both` | Value formatting in responses: `satoshis`, `rxd`, or `both` (`satoshis` ~halves token cost on balance/UTXO-heavy calls) |
| `RXDC_PATH` | _(auto-detected)_ | Path to the `rxdc` RadiantScript compiler binary, used by `radiant_compile_script` |

## Development

```bash
# MCP server (development)
npm run dev

# REST API server (development)
npm run dev:rest

# SSE server (development)
npm run dev:sse

# Type check
npm run lint

# Build
npm run build

# Run tests
npx tsx test/smoke.ts   # MCP smoke test (no network)
npx tsx test/live.ts    # MCP live test (ElectrumX)
npx tsx test/rest.ts    # REST API test (ElectrumX)
```

## Architecture

```
AI Agent (Windsurf/Claude/Cursor)       Web App / HTTP Client
       │ MCP Protocol (stdio / SSE)            │ HTTP/REST
       ▼                                       ▼
radiant-mcp-server (index.ts / sse.ts)  radiant-rest-api (rest.ts)
  ├── Tools (59)                          ├── REST endpoints
  ├── Resources (10)                      ├── OpenAPI 3.1 spec
  │                                       └── bearer-token / loopback auth
  ├── Keyring (~/.radiant-mcp, 0600) ─────────────┤  (key-handling tools)
  └──────────┬────────────────────────────────────┘
             │ Shared ElectrumX Client (TCP/TLS)
             ▼
      RXinDexer / ElectrumX
        (Glyph + WAVE + Swap + dMint APIs)
```

All transports register the same tools/resources via `src/register-tools.ts`.

## About Radiant

Radiant (RXD) is a Layer 1 UTXO proof-of-work blockchain with native digital asset support. Key features:
- **SHA512/256d** mining algorithm
- **Glyph** token standard (FT, NFT, dMint, WAVE names, 11 protocol types)
- **256 MB** blocks, **5 minute** block time
- **21 billion** max supply
- **V2 opcodes** (block 410,000+): OP_BLAKE3, OP_K12, OP_LSHIFT, OP_RSHIFT, OP_2MUL, OP_2DIV

## License

MIT