poker-solver

Decision-focused heads-up Texas Hold'em river analysis backed by a lightweight, restricted-tree CFR+ solver. Designed to supply computed frequencies and action EVs to conversational poker review—not to replace a general-purpose NLHE solver.

Status: published MVP v0.1 (not deployed). The river engine, stdio MCP adapter, HTTP MCP adapter and local tests work. A hosted Render instance and ChatGPT OAuth connection have not yet been deployed or verified. No preflop/flop/turn solve, multiway analysis, raises, rake, or live-game opponent modeling is included.

What it can do

A river solve supports OOP check/bet, IP check/bet after a check, and fold/call facing bets. The tool returns per-hand action frequencies, action EVs and a NashConv diagnostic. Input ranges are not inferred from earlier streets: you must supply plausible ranges at the start of the river.

Example: evaluate Carrie's bluff-catch

from poker_spot.core import evaluate_river_call

result = evaluate_river_call(
    board="Ks,9s,5h,Td,Ts",
    hero_hand="KdQd",
    villain_betting_range="QJs,AsJh:0.5,AsQd:0.5,AsJs",
    pot=505,
    bet=450,
)
print(result)

Important: The betting range is hypothetical and does not represent an independently verified range for the hand.

Related MCP server: MCP Poker

Quickstart

Requires Python 3.10+ (deployment example uses Python 3.12).

python -m venv .venv
source .venv/bin/activate               # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
OPENBLAS_NUM_THREADS=1 python -m unittest discover -s tests -v
python -m poker_spot example.json        # example restricted river solve

Local MCP (stdio)

python -m poker_spot.mcp_server

The program reads newline-delimited JSON-RPC messages from stdin and emits MCP tool responses to stdout. The root plugin.json/mcp.json and skills/river-review/ are retained from the local ChatGPT Desktop MVP.

Local HTTP MCP

export POKER_MCP_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export OPENBLAS_NUM_THREADS=1
uvicorn poker_spot.http_server:app --host 127.0.0.1 --port 8000

In another terminal, using the same token:

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H "Authorization: Bearer $POKER_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

GET /health returns 200 only when the token is configured. The stateless /mcp endpoint implements JSON responses for basic initialize, discovery and tool calls, and 202 for notifications. It is a deliberately small MCP HTTP implementation, not yet certified against ChatGPT's hosted connection/OAuth handshake. Callers need a way to send an Authorization bearer header. There are no persistent MCP sessions or SSE streams.

For a browser client sending an Origin header, the origin must appear in POKER_ALLOWED_ORIGINS (comma-separated); absent Origin is allowed if authorized. No unauthenticated solve requests are accepted. Limitations include no rate limiter across instances, no global compute timeout, and no production OAuth authorization server. Keep it private until the protection and compatibility checks are complete.

Deploy to Render

render.yaml uses a separate Python Web Service on Render's Free tier, in Frankfurt, one Uvicorn worker, with /health health checks. It does not reuse the trip-planning engine deployment and does not require Supabase or PostgreSQL.

1. In Render, create a Blueprint from this repository and review render.yaml.

2. Set a long random POKER_MCP_TOKEN as a Render secret; do not put it in git. Verify /health and an authorized /mcp call. Deployment is intentionally manual (autoDeployTrigger: off).

3. Before ChatGPT integration: verify client transport and add OAuth 2.0 authorization/resource metadata if needed for the hosted private plugin. Use the patterns in trip-planning-engine, not its travel-specific database logic. The pre-existing private local poker plugin has not automatically been switched to this endpoint.

An authenticated HTTP endpoint is not automatically a working hosted ChatGPT plugin. That final connection and authorization work remains a separate milestone.

Clone for development

git clone https://github.com/eddieyang-97/poker-solver.git
cd poker-solver
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
python -m unittest discover -s tests -v

Repo layout

poker_spot/
  core.py             Range expansion, showdown evaluator, CFR+ river solving
  mcp_server.py       Local MCP stdio adapter and tool schemas
  http_server.py      Authenticated stateless HTTP MCP adapter
  __main__.py         Run example solve from a JSON file
tests/
  test_core.py        Hand ranks, pot odds, CFR smoke checks
  test_mcp.py         Stdio JSON-RPC handshake/tool calls
  test_http.py        HTTP auth, MCP calls, request bounds
.github/workflows/ci.yml
render.yaml
AGENTS.md

Modeling conventions and limits

• Inputs are heads-up river-node ranges, not showdown hands alone; they can use AA, AKs, KQo:0.4, AsJh, and comma-separated combinations. Cards use Ks/Th notation.

• solve_river's EV baseline is symmetric relative to splitting the already committed pot. Compare action EVs at the same node. NashConv reports exploitability only against strategies in this fixed tree.

• For evaluate_river_call, pot is before the bet and bet is the amount to call. Pot-odds threshold = bet / (pot + 2*bet).

• Hosted solve limits: up to 1,500 iterations; up to 180 combos per range; up to 22,500 pair combinations as an upper bound; one solve at a time per process. These bounds reduce but do not eliminate denial-of-service/compute risks.

• Missing game-tree branches (raises) and range assumptions may distort recommendations even when CFR convergence is good.

• Educational/post-session analysis only. Do not rely on this tool for decisions during live real-money play.

Next milestones

1. Keep GitHub Actions green (initial CI passed on the scaffold commit).

2. Deploy a private Render service and test authenticated remote MCP calls.

3. Integrate ChatGPT-compatible OAuth (or confirm a supported alternative) and validate real connector calls.

4. Benchmark several river spots against an independent solver and expand input-range diagnostics.

5. Evaluate adding turn/flop solving with an established engine behind the same MCP interface.

The GitHub repository is currently public. Keep deployment secrets out of git.

MIT licensed (see LICENSE).