npm package: @puul/mcp-server
Description: MCP server for the Puul Partner API — let AI agents interact with prediction markets and lottery pools
Latest version: 1.1.0

# @puul/mcp-server

MCP (Model Context Protocol) server for the [Puul Partner API](https://ivorypay.gitbook.io/puul-api-documentation/). Enables AI agents to interact with prediction markets and lottery pools.

## Quick Start

### Claude Desktop / Cursor (Standalone)

Add to your MCP config (`claude_desktop_config.json` or Cursor settings):

```json
{
  "mcpServers": {
    "puul": {
      "command": "npx",
      "args": ["@puul/mcp-server"],
      "env": {
        "PUUL_CLIENT_ID": "pk_live_...",
        "PUUL_CLIENT_SECRET": "sk_live_..."
      }
    }
  }
}
```

### Hosted (SSE) — Zero Install

Connect any MCP-compatible client to our hosted endpoint:

```json
{
  "mcpServers": {
    "puul": {
      "url": "https://mcp.joinpuul.com/sse"
    }
  }
}
```

> **Note:** The hosted endpoint uses Puul's demo credentials. For production use, run the standalone server with your own partner keys.

### Self-Hosted (SSE)

```bash
PUUL_CLIENT_ID=pk_live_... PUUL_CLIENT_SECRET=sk_live_... npm run start:sse
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PUUL_CLIENT_ID` | ✅ | Partner API client ID |
| `PUUL_CLIENT_SECRET` | ✅ | Partner API client secret |
| `PUUL_BASE_URL` | ❌ | API base URL (defaults to production) |
| `PORT` | ❌ | SSE server port (default: 3001) |

## Available Tools

### Authentication
| Tool | Description |
|------|-------------|
| `puul_get_access_token` | Verify authentication is working |

### Markets
| Tool | Description |
|------|-------------|
| `puul_list_markets` | Browse live prediction markets (filter by country) |

### User Linking
| Tool | Description |
|------|-------------|
| `puul_link_user` | Link an external user to Puul (required before predictions/lottery) |

### Predictions
| Tool | Description |
|------|-------------|
| `puul_get_quote` | Get binding quote with slippage protection (10s expiry) |
| `puul_place_prediction` | Place a prediction on a market outcome |
| `puul_get_prediction` | Check prediction status and returns |
| `puul_list_predictions` | List prediction history (filter by status) |

### Lottery
| Tool | Description |
|------|-------------|
| `puul_list_lottery_pools` | Browse lottery pools (filter by status/frequency) |
| `puul_get_lottery_pool` | Get pool details and winning numbers |
| `puul_buy_lottery_ticket` | Purchase lottery tickets for a linked user |
| `puul_list_lottery_entries` | List ticket purchases |
| `puul_get_draw_results` | Get draw results and winnings |

### Wallet
| Tool | Description |
|------|-------------|
| `puul_get_balance` | Check omnibus wallet balance |
| `puul_get_deposit_account` | Get deposit bank account details |
| `puul_get_withdrawal_fees` | Preview withdrawal fees and receive amount |

## Resources

| URI | Description |
|-----|-------------|
| `puul://markets/live` | Live snapshot of all open markets |
| `puul://lottery/pools/open` | Currently open lottery pools |

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally (stdio)
PUUL_CLIENT_ID=... PUUL_CLIENT_SECRET=... npm start

# Run locally (SSE)
PUUL_CLIENT_ID=... PUUL_CLIENT_SECRET=... npm run start:sse
```

## Programmatic Usage

```typescript
import { createPuulMcpServer } from '@puul/mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createPuulMcpServer({
    clientId: 'pk_live_...',
    clientSecret: 'sk_live_...',
});

await server.connect(new StdioServerTransport());
```

## License

MIT — [Ivorychain Technologies Inc.](https://www.joinpuul.com)