Skip to main content
Glama

CI Security 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.

Related MCP server: Chess Engine MCP Server

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:

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:

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

  • 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.

Available Tools

58 tools
advance_lessonC

Mark a lesson step complete without equating completion to demonstrated mastery.

Inputs: step (required), lesson_id (required). Returns: object

analyze_chessboardB

Recognize a chessboard image and analyze it with Stockfish in one fast call. Intended for axis-aligned screenshots and diagrams. Unreliable OCR is rejected by default so analysis is not based on a silently wrong board.

Inputs: image (required), nodes, multipv, orientation, +3 more. Returns: object

analyze_gameC

Analyze a complete standard-chess PGN with adaptive Stockfish searches. Scores use White's perspective; nodes is the configured per-position budget.

Inputs: pgn (required), side, multipv, initial_nodes, +2 more. Returns: moves, engine, result, headers, +1 more

analyze_pawn_structureB

Return factual isolated, doubled, and passed-pawn geometry for both sides.

Inputs: fen (required). Returns: object

analyze_positionB

Analyze a FEN position with Stockfish. Evaluations are from the side-to-move perspective.

Inputs: fen (required), nodes, multipv. Returns: object

analyze_positionsC

Analyze a batch of FEN requests through one warm Stockfish process. All scores use White's perspective.

Inputs: positions (required). Returns: result

assess_candidate_moveC

Verify a candidate against unrestricted and forced-root searches at two budgets, retaining full supplied history.

Inputs: fen (required), move (required), history. Returns: fen, caveat, history, root_fen, +6 more

cancel_analysis_jobB

Cancel a job at its next search boundary. An active search has a bounded deadline.

Inputs: job_id (required). Returns: object

cancel_progressive_analysisB

Cancel queued or running progressive analysis and mark its result stale.

Inputs: request_id (required). Returns: error, status, context_id, request_id, +2 more

compare_candidate_movesC

Analyze and compare up to eight candidate moves under the same search profile.

Inputs: fen (required), moves (required), history, profile. Returns: object

create_game_lessonsC

Create up to twenty position-specific practice lessons from the learner's mistakes in a saved game analysis.

Inputs: side (required), learner_id (required), analysis_id (required). Returns: lessons, grouping, schema_version

create_repertoire_drillC

Create a repertoire recall drill without exposing its expected moves.

Inputs: fen (required), learner_id (required). Returns: object

create_tutor_turnC

Create a grounded tutor turn with engine evidence, teaching guidance, board actions, and speech segments.

Inputs: fen (required), intent, history, profile, +2 more. Returns: object

evaluate_endgameC

Combine endgame features with tablebase evidence or engine analysis when unavailable.

Inputs: fen (required). Returns: object

evaluate_moveB

Compare a legal move against engine analysis before and after it. Scores are White-relative.

Inputs: fen (required), move (required), history, profile. Returns: object

evaluate_positionC

Analyze a position with White-relative scores, immutable evidence, and optional move history.

Inputs: fen (required), moves, profile. Returns: id, fen, engine, profile, +9 more

explain_positionB

Inspect legal state, material, pins, attacks, and pawn structures without an engine.

Inputs: fen (required). Returns: object

find_openingB

Search locally imported opening names with pagination.

Inputs: query (required), offset. Returns: result

get_analysisC

Retrieve an immutable position analysis or completed game report.

Inputs: analysis_id (required). Returns: object

get_analysis_jobC

Read analysis job status and completed-search progress.

Inputs: job_id (required). Returns: object

get_analysis_metricsB

Report bounded engine latency samples, queue delays, cache hits, and reserved interactive capacity.

Inputs: no named parameters. Returns: cache_hits, queue_p95_ms, sample_count, search_count, +5 more

get_capabilitiesA

Report engine settings and exact local corpus counts without launching an engine.

Inputs: no named parameters. Returns: object

get_concept_progressC

Return concept-specific attempts, independent successes, and due review dates.

Inputs: learner_id (required). Returns: concepts, schema_version

get_due_repertoire_drillB

Select a due repertoire position using transposition-aware spaced review and hide expected moves.

Inputs: learner_id (required). Returns: object

get_learner_progressC

Read persisted learner preferences and a paginated training-progress view.

Inputs: learner_id (required), offset. Returns: object

get_opening_coverageB

Report exact local opening coverage by source, keeping theoretical plans and practical statistics distinct.

Inputs: no named parameters. Returns: sources, source_limit, schema_version, is_exhaustive_chess_coverage

get_opening_plansC

Retrieve transposition-matched opening plans separately from practical game statistics.

Inputs: fen (required). Returns: plans, caveat, schema_version, practical_statistics

get_opening_positionC

Get source-attributed corpus moves at a position, including transpositions.

Inputs: fen (required), offset. Returns: object

get_progressive_analysisC

Read progressive analysis status and its completed evidence ID, withholding stale results.

Inputs: request_id (required). Returns: error, status, context_id, request_id, +2 more

get_repertoire_moveC

Get personal repertoire moves at a position.

Inputs: fen (required), offset. Returns: object

get_speech_planC

Create interruptible speech segments and legal SAN/UCI pronunciations.

Inputs: fen (required), segments (required), moves. Returns: object

get_tablebase_diagnosticsA

Inspect configured tablebase directories and WDL/DTZ file pairing without claiming complete coverage.

Inputs: no named parameters. Returns: caveat, dtz_files, wdl_files, directories, +4 more

get_tablebase_resultC

Probe configured local Syzygy WDL and DTZ with explicit availability and draw semantics.

Inputs: fen (required). Returns: object

get_tacticB

Select a due puzzle near the learner's rating and begin a solution-hidden session.

Inputs: learner_id (required), theme. Returns: object

get_teaching_hintB

Reveal one of four progressive hint levels, recording assistance without exposing the full solution early.

Inputs: level (required), session_id (required). Returns: fen, status, concept, question, +3 more

import_opening_planB

Import a dated, versioned opening teaching plan with source attribution. Advice is not engine-verified automatically.

Inputs: plan (required). Returns: id, fen, name, plans, +10 more

import_opening_statisticsC

Import source-attributed aggregate opening outcomes for an explicitly described game population.

Inputs: fen (required), move (required), draws (required), source (required), +4 more. Returns: id, draws, source, move_uci, +6 more

import_opening_tsvC

Import a bounded Lichess-format opening TSV batch with explicit source attribution.

Inputs: tsv (required), source (required). Returns: object

import_puzzlesC

Import a bounded puzzle CSV batch, validating the setup move and complete source line.

Inputs: source (required), csv_text (required). Returns: object

import_studyC

Import a source-attributed PGN study, including variations and transpositions.

Inputs: pgn (required), name (required), source (required), is_repertoire. Returns: object

initialize_openingsB

Load the bundled, version-pinned Lichess named opening corpus into local storage.

Inputs: no named parameters. Returns: object

inspect_positionA

Inspect a FEN position without engine analysis.

Inputs: fen (required). Returns: object

parse_gameA

Parse one standard-chess PGN without Stockfish. Plies are one-based from the supplied starting position.

Inputs: pgn (required). Returns: moves, result, headers, initial_fen

recognize_chessboardA

Convert an axis-aligned 2D chessboard screenshot or book diagram to FEN locally. Pass image as a local path, file URL, raw base64, or base64 data URL. Returns confidence and reliability; do not silently trust a result whose reliable or plausible field is false.

Inputs: image (required), orientation, side_to_move, infer_castling_rights. Returns: object

record_training_attemptC

Record an explicitly reported training outcome with idempotent attempt identity.

Inputs: puzzle_id (required), attempt_id (required), learner_id (required), was_successful (required). Returns: object

resume_analysis_jobA

Resume an interrupted, failed, or cancelled game job using compatible durable search checkpoints.

Inputs: job_id (required). Returns: id, pgn, error, status, +5 more

review_gameB

Analyze and classify a complete PGN with deterministic Gambit review labels and per-player summaries. No prose coaching is generated.

Inputs: pgn (required), side, multipv, initial_nodes, +2 more. Returns: moves, engine, result, headers, +2 more

start_analysis_jobC

Start a bounded, persistent background game analysis or review job.

Inputs: pgn (required), should_review. Returns: object

start_lessonC

Start a persisted lesson in tactics, openings, middlegames, positioning, endgames, or calculation.

Inputs: topic (required), learner_id (required). Returns: object

start_progressive_analysisA

Return immediate preliminary evidence and queue deeper analysis; supersede older requests with the same context ID.

Inputs: fen (required), context_id (required), history. Returns: status, context_id, request_id, preliminary, +2 more

start_teaching_sessionC

Start a solution-hidden teaching cycle with a concept-specific learning objective.

Inputs: fen (required), history, learner_id. Returns: fen, status, concept, question, +3 more

submit_repertoire_moveC

Submit a legal move to a repertoire recall drill.

Inputs: move (required), session_id (required). Returns: object

submit_tactic_moveC

Check a puzzle move, play the source reply, and schedule completed puzzles for review.

Inputs: move (required), session_id (required). Returns: object

submit_teaching_moveC

Assess an answer, explain verified candidate lines, update concept progress, and schedule review.

Inputs: move (required), session_id (required). Returns: due_at, assessment, session_id, explanation, +3 more

synthesize_speechB

Synthesize a short local WAV using espeak-ng. Returns a local file URI, not streamed audio.

Inputs: text (required), rate, voice. Returns: object

tutor_moveB

Assess a proposed legal SAN or UCI move. Returns the resulting position and Stockfish's best replies, for move-by-move tutoring.

Inputs: fen (required), move (required), nodes, multipv. Returns: object

update_learner_profileC

Persist a learner's rating band, teaching preferences, and voice settings.

Inputs: learner_id (required), style, voice, detail, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables comprehensive chess analysis through Stockfish engine integration, positional evaluation, puzzle training, game review, and access to extensive chess databases. Provides visual board rendering, interactive game viewers, and tactical puzzle training with 3+ million problems from Lichess.
      34
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to perform professional-grade chess analysis using Stockfish and optionally Leela Chess Zero, including position analysis, full game review, opening lookup, and puzzle generation.
      12 npm
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP chess runtime that lets LLMs play, analyze, and adapt strength by exposing Stockfish, human move likelihood (Maia3), and Lichess statistics, with the LLM handling strategy and the server handling computation.
      13
      29 npm
      AGPL 3.0