Skip to main content
Glama
README.md
[![CI](https://img.shields.io/github/actions/workflow/status/mayazrakib/gambit/ci.yml?branch=master&label=CI)](https://github.com/mayazrakib/gambit/actions/workflows/ci.yml?query=branch%3Amaster)
[![Security](https://img.shields.io/github/actions/workflow/status/mayazrakib/gambit/security.yml?branch=master&label=security)](https://github.com/mayazrakib/gambit/actions/workflows/security.yml?query=branch%3Amaster)
[![License](https://img.shields.io/github/license/mayazrakib/gambit)](https://github.com/mayazrakib/gambit/blob/master/LICENSE)

## 1. Introduction

Gambit is an MCP server that gives connected hosts validated chess facts, bounded local Stockfish analysis, attributed API information, and a localhost playing workspace. The connected host writes the explanations and handles audio.

## 2. Usage

Install Python 3.14.7, uv 0.12.10, Node.js 24.22.0, npm 11.19.1, Task 3.54.0, and Stockfish. Then initialize and start the server:

```sh
uv sync --locked --extra vision
uv run gambit initialize
uv run gambit
```

`.env.example` documents the optional settings. Keep real credentials private. `showcase/configuration.toml` shows TOML configuration, and `uv run gambit serve --transport streamable-http --port 3025` serves MCP over HTTP.

### 2.1. Playing Workspace

Build the sibling `../chessboard` checkout first. Then build the interface and start the workspace:

```sh
npm ci --prefix ui
npm run build --prefix ui
uv run gambit play --port 3030
```

## 3. Features

- Position facts, batch analysis, and move comparisons.
- PGN validation and board recognition.
- Opening classifications.
- Opt-in, attributed provider requests.
- Temporary live games.

Contract version 3 preserves White-relative scores, history identity, units, attribution, search bounds, and revision checks.

Only opening classifications and non-personal configuration persist. Games, evidence, jobs, and API caches stay bounded and process-local. Gambit doesn't support learner profiles, personalized databases, server-authored explanations, speech synthesis, local tablebases, or bulk personal downloads.

## 4. Architecture

`src/gambit/` separates providers, knowledge, game evidence, local engines, live state, and MCP and HTTP transport. `ui/src/` owns browser presentation and uses sibling Chessboard events. Stale revisions never publish annotations, rejected optimistic moves roll back, hints hide solutions, and opponent strength stays separate from evidence analysis.

HTTP binds to loopback and validates the peer, host, origin, request type, and size. `GAMBIT_UI_ORIGIN` can allow one exact HTTPS `.ts.net` origin through loopback. Forwarded headers never replace the peer.

### 4.1. Conventions

- Never persist personal identifiers or response bodies in logs.
- Preserve the existing remote MCP connection.
- Don't add Python comments or docstrings.

### 4.2. Verification

Backend checks use `uv run --locked --extra vision pytest`. Explicit style checks use `uv run ruff check src tests tools/scripts` and `uv run python tools/scripts/format_code.py --check`. `tools/scripts/generate_tutor_skill.py --check` validates the portable `.ai/skills/chess/` output against the authoritative Agents sources.

## 5. Dependencies

| Dependency | Version | Use |
|---|---|---|
| `mcp` | 2.3.0 | Runtime: MCP server |
| `python-chess` | 1.999 | Runtime: chess rules and engine protocol |
| `python-dotenv` | 1.2.4 | Runtime: environment configuration |
| `httpx` | 0.28.1 | Runtime: provider requests |
| `numpy` | 2.5.4 | Optional `vision` runtime: image arrays |
| `onnxruntime` | 1.31.0 | Optional `vision` runtime: recognition model inference |
| `pillow` | 13.0.0 | Optional `vision` runtime: image decoding |
| `libcst` | 1.9.0 | Development: source formatting checks |
| `pytest` | 9.1.1 | Development: tests |
| `pytest-asyncio` | 1.4.1 | Development: asynchronous tests |
| `ruff` | 0.17.2 | Development: static checks |
| `uv_build` | `>=0.12,<0.13`, declared; not locked | Build: package backend |

`ui/README.md` lists the browser workspace's dependencies.

## 6. Roadmap

- [x] Contract version 3 and the temporary live workspace.
- [ ] Revalidate remote and voice behavior separately when deployment is requested.

## 7. Contributing

Read `AGENTS.md` and the applicable skills in `.ai/skills/` before contributing. Set up the development environment with `uv sync --locked --extra vision`. Follow the repository conventions, preserve supported behavior, and add relevant tests for behavior changes. Run `uv run --locked --extra vision pytest` and `uv build --out-dir build/packages` before opening a pull request. Describe the change, its purpose, and the validation results in the pull request.

## 8. License

`gambit` is licensed under the MIT license. See LICENSE for the complete license text.

TDQS

C2.7/5.0

Scored across 58 tools

Disambiguation2/5

Many tools overlap heavily: analyze_position, evaluate_position, analyze_positions, inspect_position, and explain_position all inspect or evaluate a FEN, while analyze_game, review_game, start_analysis_job, and get_analysis all analyze entire games. Move assessment is similarly fragmented across evaluate_move, compare_candidate_moves, tutor_move, assess_candidate_move, and submit_teaching_move. Descriptions attempt to differentiate, but the agent must read carefully to avoid picking the wrong tool.

Naming Consistency4/5

All tool names use snake_case and mostly follow a verb_noun pattern (e.g., create_game_lessons, get_opening_plans, start_progressive_analysis). Minor deviations exist, such as 'inspect_position' vs 'analyze_position' and 'tutor_move' vs 'evaluate_move', but the overall convention is predictable and readable.

Tool Count1/5

With 58 tools, the set is far beyond a reasonable scope, and many tools duplicate functionality (e.g., multiple analysis and evaluation endpoints). The domain is broad (engine analysis, openings, repertoire, tutoring, speech, tablebases), but the sheer number creates a heavy, confusing surface that is not well-scoped.

Completeness4/5

The surface covers a wide range of chess analysis and teaching workflows: engine evaluation, game review, openings, repertoire drills, tactics, tablebases, speech synthesis, and learner progress. Minor gaps include no deletion or update for some entities (e.g., no delete_repertoire, no update_game_lesson), but the core lifecycle operations are present.