# MCP Poker

An MCP server for poker play recommendations — real equity calculations, player tracking, and exploit-based recommendations.

## How It Works

- **Equity engine:** Monte Carlo simulation using `phevaluator` (a fast C-based poker hand evaluator). Suits, flushes, and all hand types are fully accounted for. No hardcoded hand rankings — everything is computed.
- **Player tracking:** Imports PokerNow hand histories, stores all hands/actions in SQLite, and computes detailed player statistics (VPIP, PFR, 3-bet, c-bet, aggression, WTSD, etc.)
- **Exploit engine:** Detects player leaks from historical data and adjusts GTO recommendations to exploit specific tendencies.
- **Multi-way aware:** Advice adjusts based on number of players in the hand — bluffing less in multi-way, tightening value ranges, accounting for equity dilution.

## Architecture

```
src/                          # TypeScript source (MCP server)
├── index.ts                  # Entry point — wires tools to MCP server
├── tools/
│   ├── import.ts             # import_pokernow_log, set_hero, set_player_alias, add_player_note
│   ├── player.ts             # get_player_stats, get_player_tendencies, get_player_profile, list_players
│   ├── recommend.ts          # recommend_action (main coaching tool)
│   ├── history.ts            # search_hands, analyze_hand, get_session_summary, list_sessions
│   └── guide.ts              # get_tool_guide (LLM documentation)
├── gto/
│   ├── preflop-ranges.ts     # Equity-driven preflop advice (no hardcoded ranges)
│   ├── postflop.ts           # MC equity calculator bridge + postflop advice engine
│   └── exploit.ts            # Player leak detection + exploit adjustments
├── db/
│   ├── schema.ts             # SQLite schema + auto-migration
│   └── queries.ts            # All DB queries + stat calculations + player profiles
└── types.ts                  # Shared TypeScript types

python/                       # Python (equity calculations, CSV parsing)
├── equity_calculator.py      # Monte Carlo equity calculator using phevaluator
├── parse_pokernow.py         # PokerNow CSV log parser
└── requirements.txt

data/                         # SQLite database (created at runtime, gitignored)
```

- `src/` = TypeScript source code
- `dist/` = Compiled JavaScript output (gitignored, built by `npm run build`)
- `python/` = Python scripts called by the TS server
- `.venv/` = Python virtual environment with phevaluator

## Setup

### Prerequisites

- Node.js >= 18
- Python 3.8+

### Install

```bash
npm install
npm run build
python3 -m venv .venv
.venv/bin/pip install phevaluator
```

### Add to Cursor

The `.cursor/mcp.json` is already configured. After opening this project in Cursor, the server should be available. If not, add to your MCP config:

```json
{
  "mcpServers": {
    "poker": {
      "command": "node",
      "args": ["/path/to/mcp-poker/dist/index.js"]
    }
  }
}
```

## Tools (14 total)

| Tool | Description |
|---|---|
| `import_pokernow_log` | Import a PokerNow CSV hand history file |
| `set_hero` | Set which player is you |
| `set_player_alias` | Link two PokerNow IDs as the same person |
| `add_player_note` | Save a note about a player |
| `get_player_stats` | Full stat sheet (VPIP, PFR, 3-bet, c-bet, AF, WTSD, etc.) |
| `get_player_tendencies` | Natural language leak analysis + exploit recommendations |
| `get_player_profile` | Comprehensive behavioral dossier (positional, multi-way, trends, showdowns) |
| `list_players` | List all tracked players |
| `recommend_action` | Real-time coaching with Monte Carlo equity + exploit adjustments |
| `search_hands` | Query hand history with filters |
| `analyze_hand` | Deep replay of a specific hand |
| `get_session_summary` | Session results + biggest pots |
| `list_sessions` | List all imported sessions |
| `get_tool_guide` | Returns full documentation on all tools for the LLM |

For detailed input/output specs for every tool, call `get_tool_guide` from the LLM or see `src/tools/guide.ts`.

## Data Storage

All data is stored locally in `data/poker.db` (SQLite). Nothing leaves your machine.