# arcium-mcp — MCP Server for Arcium Confidential Computing

Connects AI agents (Claude, GPT, any MCP client) to the Arcium encrypted computation network on Solana.

## Status

**Alpha.** Full MCP server with 19 tools across 4 categories. Network Explorer and Encryption Engine use the real Arcium SDK. App Templates implement the full encrypt → submit → await → decrypt pipeline (requires deployed MXE programs and wallet). Supports both stdio and HTTP/SSE transport.

## Architecture

```
AI Agent  <-->  MCP Protocol  <-->  arcium-mcp-server  <-->  Arcium Network (Solana)
                (stdio or HTTP)          |
                                @arcium-hq/client + reader
```

## Tools (19 across 4 categories)

### Network Explorer (7) — read-only, no wallet
| Tool | Description |
|------|-------------|
| `arcium_list_mxes` | List all MXE execution environments |
| `arcium_get_mxe_info` | Detailed MXE info |
| `arcium_list_clusters` | List computation clusters |
| `arcium_get_cluster_info` | Cluster details |
| `arcium_list_nodes` | List ARX nodes |
| `arcium_get_node_info` | Node details |
| `arcium_network_stats` | Aggregate stats |

### Encryption Engine (4) — client-side, no transactions
| Tool | Description |
|------|-------------|
| `arcium_generate_keypair` | x25519 keypair |
| `arcium_get_mxe_pubkey` | Fetch MXE public key for ECDH |
| `arcium_encrypt_values` | Encrypt with RescueCipher |
| `arcium_decrypt_result` | Decrypt computation output |

### Computation Manager (4) — inspect, track, and manage computations
| Tool | Description |
|------|-------------|
| `arcium_get_comp_definition` | Circuit details |
| `arcium_check_computation` | Check tx status |
| `arcium_await_finalization` | Wait for computation to finalize |
| `arcium_list_mempool` | List pending computations |

### App Templates (4) — full execution flow with deployed programs
| Tool | Description |
|------|-------------|
| `arcium_play_coinflip` | Encrypted coin flip |
| `arcium_play_rps` | Rock-paper-scissors |
| `arcium_sealed_bid` | Sealed auction bid |
| `arcium_private_vote` | Encrypted DAO vote |

## Quick Start

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

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SOLANA_RPC_URL` | Solana RPC endpoint | `https://api.mainnet-beta.solana.com` |
| `ARCIUM_CLUSTER_OFFSET` | Cluster offset | `0` |
| `ARCIUM_WALLET_PRIVATE_KEY` | Base58 or JSON array Solana keypair | (none — read-only mode) |
| `ARCIUM_MCP_TRANSPORT` | Transport mode: `stdio` or `http` | `stdio` |
| `ARCIUM_MCP_PORT` | HTTP port (when transport=http) | `3000` |
| `ARCIUM_COINFLIP_PROGRAM` | Coinflip MXE program ID | (disabled) |
| `ARCIUM_RPS_PROGRAM` | RPS MXE program ID | (disabled) |
| `ARCIUM_AUCTION_PROGRAM` | Auction MXE program ID | (disabled) |
| `ARCIUM_VOTING_PROGRAM` | Voting MXE program ID | (disabled) |

### Claude Desktop config (stdio)

```json
{
  "mcpServers": {
    "arcium": {
      "command": "node",
      "args": ["path/to/dist/index.js"],
      "env": {
        "SOLANA_RPC_URL": "https://api.devnet.solana.com"
      }
    }
  }
}
```

### HTTP/SSE mode (for hosted usage)

```bash
ARCIUM_MCP_TRANSPORT=http ARCIUM_MCP_PORT=3000 npm start
# MCP endpoint: http://localhost:3000/mcp
# Health check: http://localhost:3000/health
```

## Development (Ralph Wiggum Method)

This project uses the [Ralph Wiggum method](https://ghuntley.com/ralph/) for AI-driven iterative development.

```bash
# Planning mode — analyze specs vs code, generate task list
./loop.sh plan

# Build mode — implement one task per iteration, commit, repeat
./loop.sh 20
```

Key files:
- `specs/*` — Requirement specs per topic of concern
- `IMPLEMENTATION_PLAN.md` — Prioritized task list (generated/updated by Ralph)
- `AGENTS.md` — Operational guide for build/test commands
- `PROMPT_plan.md` / `PROMPT_build.md` — Loop instructions

## License

MIT