Metadata-Version: 2.5
Name: puntersedge-mcp
Version: 0.1.0
Summary: Official MCP server for the PuntersEdge Australian racing & sports odds API — live bookmaker odds, results and market movement for AI agents.
Project-URL: Homepage, https://puntersedge.online/api
Project-URL: Documentation, https://puntersedge.online/developers
Project-URL: Get an API key, https://puntersedge.online/api#signup
Author-email: PuntersEdge <hello@puntersedge.online>
License: MIT
Keywords: ai-agents,australia,mcp,odds,racing,sports-betting
Requires-Python: >=3.10
Requires-Dist: mcp>=2.0.0
Description-Content-Type: text/markdown

# PuntersEdge MCP Server

Official [MCP](https://modelcontextprotocol.io) server for the
[PuntersEdge Australian racing & sports odds API](https://puntersedge.online/api) —
live per-bookmaker odds, best-price comparison, full-field race results and market
movement, for AI agents.

## Install

```bash
pip install puntersedge-mcp
```

## Configure

Get a free API key (1,500 credits/month, no card) at
[puntersedge.online/api](https://puntersedge.online/api#signup), then add to your MCP
client config (Claude Desktop, Claude Code, or any MCP host):

```json
{
  "mcpServers": {
    "puntersedge": {
      "command": "puntersedge-mcp",
      "env": { "PUNTERSEDGE_API_KEY": "your-key-here" }
    }
  }
}
```

## Tools

| Tool | Cost | What it returns |
|---|---|---|
| `racing_next_to_go` | 2 cr | Next AU/NZ races with runners and live per-bookmaker prices |
| `racing_best_odds` | 3 cr | Best win/place/tote per runner, with the book offering it |
| `racing_results` | 2 cr | Settled results incl. the full finishing order (`runners`) with stable registry ids |
| `racing_price_history` | 3 cr | Recorded price ticks for one race — the movement record |
| `racing_movers` | 3 cr | Biggest firmers and drifters right now |
| `list_sports` | 1 cr | The sport catalogue |
| `sports_odds` | 2 cr | Per-bookmaker prices for a sport's fixtures |
| `best_odds` | 2 cr | Best price per outcome for one sport |
| `check_usage` | free | Plan, allowance, credits used, reset date |
| `demo_next_to_go` | free | No-key sandbox sample to explore the shape |

Every tool response includes `credits_remaining` so an agent can budget without
spending a call. Costs are enforced server-side; a 402 means the monthly allowance is
spent (hard stop, never overage billing).

## Notes for agents

- Racing is under `racing_*` tools, not a sport key. Categories: horse, greyhound,
  harness.
- Prices are decimal odds. Every racing quote carries its own `age_seconds`; every
  sports market carries a `quality` object. Trust those over assumptions.
- Settle only against `status: "final"` results — interim placings can change on
  protest.
- `runner_ref` in results is a stable registry identifier that persists across
  meetings — use it, not the name, for longitudinal joins.
