Metadata-Version: 2.5
Name: poker-coach-engine
Version: 0.1.0
Summary: MCP poker math engine for No-Limit Texas Hold'em analysis
Author: Poker Coach Engine
License: MIT
License-File: LICENSE
Keywords: equity,mcp,poker,poker-math,texas-holdem
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: mcp<3.0,>=2.0
Description-Content-Type: text/markdown

# Poker Coach Engine

A small MCP math engine for a No-Limit Texas Hold'em Poker Coach Agent.

## What it does

The MCP server exposes one tool: `poker_analyze`.

It can return:

- current hand class
- Hero equity versus a supplied Villain range
- fallback equity versus random opponent cards
- required equity / pot odds for a call
- call EV relative to folding
- SPR
- next-card hand-improvement outs
- board classification
- basic legal-action validation

It intentionally does **not** invent GTO frequencies or final strategy. Your Agent should combine this tool with its poker strategy / GTO knowledge base and opponent model.

## Supported range notation (v0.1)

Examples:

```text
AA
77,22,A7s,A2s,AQs,AJs
99+
AJs+
A5s-A2s
76s-54s
AKs
AKo
AK
AhKh
A5s:0.5
```

`A5s:0.5` means the combo class is weighted at 50% when sampled.

## Important input definition

`pot_before_call` means the pot already in the middle **after Villain's current bet/raise has gone in, but before Hero calls**.

Example:

- 38 BB is currently in the pot
- Hero needs 11 BB more to call

Use:

```text
pot_before_call = 38
call_amount = 11
```

The required equity is `11 / (38 + 11) = 22.45%`.

## Local install

Requires Python 3.10+.

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e .
```

Run the MCP server over stdio:

```bash
poker-coach-engine
```

## Test the math modules

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
```

On Windows PowerShell:

```powershell
$env:PYTHONPATH="src"
python -m unittest discover -s tests -v
```

## Build for PyPI

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
```

Upload to TestPyPI first if desired, then publish to PyPI.

After it is public on PyPI, Alibaba Cloud Model Studio can launch a Python MCP package through `uvx <package-name>`.

## Bailian MCP config

After publishing the package, use:

```json
{
  "mcpServers": {
    "poker-engine": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "poker-coach-engine"
      ]
    }
  }
}
```

If PyPI says the package name is already taken, rename `[project].name` in `pyproject.toml`, publish using that new name, and put the same new name in the `args` array.

## Safety / scope

This package performs poker math and simulation. It does not interact with poker clients, automate gameplay, obtain hidden cards, or bypass platform rules.
