# seranox-mcp-server

[MCP](https://modelcontextprotocol.io) server that wraps the **Seranox** metered API, so Claude, Cursor, or any MCP-compatible agent can read the tape on Robinhood Chain — new pairs, wallet intel, equities dislocation, risk scans — and build **unsigned** swap routes.

Every tool is a 1:1 wrapper over one `/api/v1` endpoint. No business logic lives here, and nothing here can sign or move funds: `seranox_build_route` returns an unsigned transaction for the user's wallet to sign. Each result carries `cost.seraBurned` (from the API's `x-sera-burned` header) so an agent can reason about spend.

## Tools

| Tool | Endpoint | Burns |
|---|---|---|
| `seranox_status` | `GET /health` | 0 |
| `seranox_list_pairs` | `GET /pairs` — filter by risk verdict, max age, limit | 1 SERA |
| `seranox_get_pair` | `GET /pairs/:id` — by id, `$SYMBOL`, or address | 1 SERA |
| `seranox_risk_scan` | `GET /pairs/:id/risk` — honeypot, mint authority, LP lock, deployer, concentration (utility #15) | 5 SERA |
| `seranox_list_wallets` | `GET /wallets` — tracked wallets, filter by tag | 1 SERA |
| `seranox_wallet_flow` | `GET /wallets/:address/flow` — by address or label | 2 SERA |
| `seranox_equities_dislocation` | `GET /equities/dislocation?ticker=` — on-chain vs last close, read-only | 1 SERA |
| `seranox_build_route` | `POST /route` — **unsigned** tx + fee quote; needs an API key (utility #10) | routed fee |

## Install

```bash
pnpm install && pnpm build
```

## Configure

| Env | Default | Purpose |
|---|---|---|
| `SERANOX_API_URL` | `https://app.seranox.xyz/api/v1` | API base. Use `http://localhost:5173/api/v1` against a local `seranox-dapp`. |
| `SERANOX_API_KEY` | — | Key bound to a staked account. Optional for read tools; required for `seranox_build_route`. |

### Claude Code

```bash
claude mcp add seranox -e SERANOX_API_URL=https://app.seranox.xyz/api/v1 -e SERANOX_API_KEY=… -- node /path/to/seranox-mcp-server/dist/index.js
```

### Claude Desktop / Cursor (`mcpServers`)

```json
{
  "mcpServers": {
    "seranox": {
      "command": "node",
      "args": ["/path/to/seranox-mcp-server/dist/index.js"],
      "env": { "SERANOX_API_URL": "https://app.seranox.xyz/api/v1", "SERANOX_API_KEY": "…" }
    }
  }
}
```

## Develop

```bash
pnpm dev          # run over stdio from source (tsx)
pnpm test         # vitest — in-memory MCP transport + fake API
pnpm lint && pnpm typecheck
```

stdout is the MCP wire; log only to stderr.

## Layout

```
src/index.ts      stdio entry
src/server.ts     createServer(): registers every tool; API type shapes
src/client.ts     fetch wrapper: auth header, x-sera-burned, error mapping
src/config.ts     env → config
src/tools/        result + error helpers
tests/            protocol-level tests via InMemoryTransport
```

MIT.