# TexasSolver MCP Server

A Model Context Protocol (MCP) server that enables Claude and other LLMs to interact with the TexasSolver console poker solver through structured parameters.

## Features

- **Run Solver**: Execute the TexasSolver with custom game parameters (pot, stack, ranges, board, bet sizes)
- **Load Ranges**: List and load preflop range files from the TexasSolver ranges directory
- **Build Game Trees**: Generate game tree configurations without running the solver (for inspection/editing)
- **List Outputs**: Query previously generated solver outputs
- **Structured Input**: LLM provides structured parameters - no natural language parsing needed

## Installation

### 1. Prerequisites

- Node.js 18.0.0 or higher
- TexasSolver binary (v0.2.0 or compatible)

### 2. Install Dependencies

```bash
cd /Users/bensimmons/Desktop/TexasSolverMCP
npm install
```

### 3. Configure Environment

Copy `.env.example` to `.env` and update the `TEXAS_SOLVER_PATH`:

```bash
cp .env.example .env
# Edit .env and set TEXAS_SOLVER_PATH to your solver location
```

Example:
```
TEXAS_SOLVER_PATH=/Users/bensimmons/Desktop/TexasSolverMCP/TexasSolver-v0.2.0-MacOs/console_solver
```

## Usage

### Running the MCP Server

```bash
npm start
```

The server will start and listen for MCP requests via stdio.

### Claude Desktop Integration

Add the following to your Claude Desktop configuration file at:
`~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "texassolver": {
      "command": "node",
      "args": ["/Users/bensimmons/Desktop/TexasSolverMCP/src/index.js"],
      "env": {
        "TEXAS_SOLVER_PATH": "/Users/bensimmons/Desktop/TexasSolverMCP/TexasSolver-v0.2.0-MacOs/console_solver"
      }
    }
  }
}
```

## MCP Tools

### `run_solver`

Execute the TexasSolver with game parameters.

**Parameters:**
- `pot` (number): Starting pot size
- `effective_stack` (number): Player stack size
- `board` (string): Board cards (e.g., "Qs,8d,7h" for flop, empty for preflop)
- `range_ip` (string): In-position player range (e.g., "AA-22,AK-AJ")
- `range_oop` (string): Out-of-position player range
- `bet_sizes` (object, optional): Custom bet sizes by position, street, and action
- `solver_config` (object, optional): Solver settings (thread_num, accuracy, max_iteration, etc.)
- `output_name` (string, optional): Custom output filename

**Example:**
```
Run AcQc vs 22+ on Ac7h2h board, 10bb pot, 100bb stacks
```

**Returns:**
```javascript
{
  success: true,
  output_file: "/absolute/path/to/result_2025-01-15T10-35-22-abc123.json",
  command_file: "/absolute/path/to/cmd_2025-01-15T10-30-45-abc123.txt",
  execution_time_ms: 45000,
  solver_log: "..."
}
```

### `list_ranges`

Discover available preflop range files.

**Parameters:**
- `filter` (string, optional): Filter by position or scenario
- `range_set` (string, optional): "6max", "qb", or all (default)

**Returns:**
```javascript
{
  ranges: [
    {
      path: "6max_range/BTN",
      full_path: "/absolute/path/to/BTN",
      name: "BTN Opening Range",
      scenario: "Open",
      position: "BTN"
    },
    ...
  ]
}
```

### `load_range`

Load and parse a specific range file.

**Parameters:**
- `range_path` (string): Path from `list_ranges` or absolute path

**Returns:**
```javascript
{
  range_string: "AA:1.0,KK:1.0,QQ:0.5,...",
  parsed_hands: [
    { hand: "AA", weight: 1.0 },
    { hand: "KK", weight: 1.0 },
    ...
  ],
  hand_count: 150,
  total_combos: 1325.5
}
```

### `build_game_tree_config`

Generate a game tree configuration without running the solver.

**Parameters:** Same as `run_solver` (without `solver_config`)

**Returns:**
```javascript
{
  command_file: "/path/to/cmd_...txt",
  commands: [
    "set_pot 10",
    "set_effective_stack 100",
    ...
  ],
  preview: "Full command file content as string"
}
```

### `list_outputs`

List previously generated solver outputs.

**Parameters:**
- `limit` (number, optional): Maximum results (default: 20)
- `sort_by` (string, optional): "date" (default) or "size"

**Returns:**
```javascript
{
  outputs: [
    {
      filename: "result_2025-01-15T10-35-22-abc123.json",
      path: "/absolute/path/to/result_...json",
      size_mb: "26.5",
      created_at: "2025-01-15T10:35:22.000Z",
      associated_command: "/path/to/cmd_...txt"
    },
    ...
  ]
}
```

## Project Structure

```
texassolver-mcp/
├── package.json
├── .gitignore
├── .env.example
├── .env
├── README.md
├── src/
│   ├── index.js                 # Entry point and initialization
│   ├── server.js                # MCP server setup
│   ├── tools/                   # MCP tool implementations
│   │   ├── run-solver.js
│   │   ├── load-range.js
│   │   ├── configure-tree.js
│   │   └── list-outputs.js
│   ├── solver/                  # Solver integration
│   │   ├── command-builder.js
│   │   ├── executor.js
│   │   └── validator.js
│   ├── ranges/                  # Range file handling
│   │   ├── loader.js
│   │   ├── parser.js
│   │   └── index.js
│   ├── storage/
│   │   └── manager.js           # File management
│   └── utils/
│       └── constants.js         # Constants
└── data/                        # Server data (generated)
    ├── commands/                # Generated command files
    ├── outputs/                 # Solver JSON outputs
    └── temp/                    # Temporary files
```

## How It Works

### Solver Execution Flow

1. **Input Validation**: Validates all parameters (ranges, board, bet sizes)
2. **Command Generation**: Builds a command file with solver settings
3. **Process Spawning**: Spawns the console_solver binary
4. **Command Piping**: Pipes the command file to solver stdin
5. **Output Capture**: Captures solver stdout/stderr for logging
6. **Completion**: Waits for solver to finish (timeout: 10 minutes)
7. **Result Return**: Returns paths to output JSON and command file

### Range File Format

Ranges are stored as comma-separated hands with optional weights:
```
AA:1.0,KK:1.0,QQ:0.5,AKs:1.0,AKo:0.75,...
```

- `AA:1.0` - Always include AA
- `AKo:0.75` - Include AKo 75% of the time
- `JJ` - Implicit weight of 1.0 if not specified

## Error Handling

The server provides detailed error messages for:
- Invalid solver path or missing binary
- Invalid game parameters (pot, stack, ranges, board)
- Invalid bet sizes
- Solver process failures
- Output file not created
- Timeout (10 minutes)

All errors include:
- Human-readable message
- Error type (VALIDATION_ERROR, EXECUTION_ERROR, OUTPUT_ERROR)
- Detailed context (command file, solver log, exit code)

## Development

### Running Tests

```bash
npm test
```

### Testing with Sample Data

The TexasSolver includes sample command files in:
```
TexasSolver-v0.2.0-MacOs/resources/text/commandline_sample_input.txt
```

## Troubleshooting

### "Solver binary not found"
- Verify `TEXAS_SOLVER_PATH` in `.env` points to the actual binary
- Check file permissions: `ls -la /path/to/console_solver`

### "Permission denied"
- Make sure the binary is executable: `chmod +x /path/to/console_solver`

### "Solver timed out"
- Complex game trees can take time to solve
- Reduce accuracy or max_iteration in solver_config
- Increase SOLVER_TIMEOUT_MS in .env if needed

### "Output file not created"
- Check available disk space
- Verify the data/outputs/ directory is writable
- Check solver_log in error response for solver-specific errors

## License

MIT

## Support

For issues or feature requests, please refer to the documentation or check the MCP server logs.