# Sphere MCP Gaming Server
MCP (Model Context Protocol) server for the Unicity gaming platform. Provides LLM access to games with payment-gated day passes via Nostr.
## Features
- **Day Pass System**: Users pay once for 24-hour access to all games
- **Nostr Integration**: Payment requests sent via Nostr protocol
- **Unicity Blockchain**: Uses nametags for identity and payment routing
- **Auto Identity**: Server creates its own blockchain identity on first run
- **HTTP Transport**: Supports both legacy SSE and modern Streamable HTTP
## Available Games
| ID | Name | Description |
|----|------|-------------|
| `unicity-quake` | Unicity Quake | Fast-paced multiplayer arena shooter |
| `boxy-run` | Boxy Run | Endless runner with blockchain rewards |
| `unirun` | Unirun | Unicity-native endless runner |
## MCP Tools
| Tool | Parameters | Description |
|------|------------|-------------|
| `list_games` | - | List all available games |
| `check_access` | `unicity_id` | Check access status and day pass validity |
| `get_game` | `unicity_id`, `game` | Get access to a specific game (initiates payment if needed) |
| `confirm_payment` | `unicity_id`, `game` (optional) | Wait for payment confirmation |
| `get_wallet_balance` | `password` | Get MCP wallet balance (admin) |
All tools that require user identity take `unicity_id` as a parameter, making the API stateless and suitable for multi-user scenarios.
## HTTP Endpoints
The server runs on HTTP (default port 3001) with two transport protocols:
### Legacy SSE (MCP Inspector, older clients)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/sse` | GET | Establish SSE stream, returns POST endpoint |
| `/messages?sessionId=xxx` | POST | Send JSON-RPC messages |
### Streamable HTTP (modern clients)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/mcp` | POST | Send JSON-RPC requests |
| `/mcp` | GET | SSE stream for responses |
Session ID is passed via `mcp-session-id` header.
### Health Check
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Returns `{ status, sseSessions, httpSessions }` |
## Quick Start
### 1. Configure Environment
```bash
cp .env.example .env
```
Edit `.env` with required values:
```env
# Required
MCP_NAMETAG=gaming-mcp
PAYMENT_COIN_ID=your_coin_id_here
```
### 2. Run with Docker Compose
```bash
docker compose up -d
```
The server will:
1. Generate a new private key (saved to `./data/identity.json`)
2. Mint a nametag on Unicity blockchain
3. Publish Nostr binding for the nametag
4. Start listening for MCP connections
### 3. View Logs
```bash
docker compose logs -f
```
## Testing the MCP
### Option 1: MCP Inspector (Recommended)
The MCP Inspector provides a web UI to interact with the server:
```bash
# Start the server
npm run build && npm start
# In another terminal, connect inspector to HTTP endpoint
npx @modelcontextprotocol/inspector --url http://localhost:3001/sse
```
This opens a browser UI where you can call tools interactively.
### Option 2: curl (Health Check)
```bash
curl http://localhost:3001/health
```
### Option 3: Claude Desktop Integration
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"gaming": {
"url": "http://localhost:3001/sse"
}
}
}
```
## Example Workflow
1. **User lists available games:**
```
Tool: list_games
```
2. **User requests a game with their Unicity ID:**
```
Tool: get_game
Args: { "unicity_id": "alice", "game": "unicity-quake" }
```
3. **If no day pass, payment is requested.** The user receives a payment request in their Unicity wallet.
4. **User confirms payment:**
```
Tool: confirm_payment
Args: { "unicity_id": "alice" }
```
5. **On successful payment, user gets game URL and 24h access.**
## Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `MCP_NAMETAG` | Yes | - | Nametag for this MCP server |
| `PAYMENT_COIN_ID` | Yes | - | Coin ID for payments |
| `MCP_PRIVATE_KEY_HEX` | No | Auto-generated | Private key (hex) |
| `NOSTR_RELAY_URL` | No | `wss://nostr-relay.testnet.unicity.network` | Nostr relay |
| `AGGREGATOR_URL` | No | `https://goggregator-test.unicity.network` | Unicity aggregator |
| `AGGREGATOR_API_KEY` | No | (testnet key) | Aggregator API key |
| `PAYMENT_AMOUNT` | No | `1000000000` | Payment amount |
| `DAY_PASS_HOURS` | No | `24` | Day pass duration |
| `PAYMENT_TIMEOUT_SECONDS` | No | `120` | Payment timeout |
| `DATA_DIR` | No | `./data` | Data persistence directory |
| `ADMIN_PASSWORD` | No | Auto-generated | Admin password for wallet access |
| `HTTP_PORT` | No | `3001` | HTTP server port |
## Data Persistence
The server stores identity and nametag data in `DATA_DIR`:
- `identity.json` - Private key (keep this safe!)
- `nametag-{name}.json` - Minted nametag token
Mount this directory as a volume to persist across container restarts.
## Development
```bash
# Install dependencies
npm install
# Build
npm run build
# Run locally
npm start
# Watch mode
npm run dev
```
## Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ LLM Client │────▶│ MCP Server │────▶│ Nostr Relay │
│ (Claude, etc.) │ │ (HTTP transport)│ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Unicity │ │ User Wallet │
│ Aggregator │ │ (Sphere app) │
└─────────────────┘ └─────────────────┘
```
## License
MIT
