llm-chess-mcp

MCP-среда для игры в шахматы, которая позволяет LLM играть, анализировать и адаптировать свою силу, не перекладывая каждое решение на движок.

Вместо возврата единственного лучшего хода она предоставляет объективную силу (Stockfish), вероятность человеческого хода (Maia3) и статистику реальных партий (Lichess), чтобы LLM могла сама выбирать, как играть. LLM отвечает за стратегию и суждения; MCP-сервер выполняет все вычисления.

Движки

Всё выполняется внутри процесса Node — на этапе развёртывания не требуется внешний процесс движка или среда Python. Опубликованный пакет включает модель Maia3 5M; другие варианты экспорта не являются вариантами выполнения, если их ONNX-файлы не предоставлены отдельно.

Related MCP server: Chess MCP

Установка

Требуется Node.js 20 или новее.

Установка не требуется — запустите напрямую через npx:

npx -y llm-chess-mcp

Модель Maia3 уже включена, поэтому не нужно устанавливать Python, torch или бинарные файлы движка. npx загружает пакет при первом запуске и кэширует его.

Чтобы установить его постоянно, вместо этого:

npm install -g llm-chess-mcp

Сборка из исходников

pnpm install
pnpm build
pnpm test

pnpm test:unit запускает набор модульных тестов. pnpm test:e2e сначала выполняет сборку, затем запускает тесты транспорта MCP. pnpm check выполняет полный локальный контроль; перед публикацией используйте pnpm release:check.

Поддержка

Архитектура описывает границы среды выполнения и сервисов.

Локальные команды проверки качества:

pnpm typecheck
pnpm test:coverage
pnpm contract:check
pnpm check
pnpm test:package

pnpm test:stress запускает короткую проверку параллельности с реальным движком. pnpm test:live обращается к Lichess только при установленном LICHESS_TOKEN; в противном случае он пропускается без сетевого запроса.

Экспорт Maia3 в ONNX (только на этапе сборки)

Этот шаг требует Python + PyTorch один раз. Он загружает контрольную точку Maia3, проверяет реimplementation на соответствие оригиналу и экспортирует models/maia3-5m.onnx.

uv venv .venv-maia3 --python 3.13
uv pip install --python .venv-maia3/bin/python -r scripts/requirements.txt
uv pip install --python .venv-maia3/bin/python "maia3 @ git+https://github.com/CSSLab/maia3.git@1e13597c42d4858b7cfd7cfdae01e297263364b2"
pnpm export:maia3            # -> models/maia3-5m.onnx

Полученный файл .onnx фиксируется/включается в пакет; конечным пользователям никогда не нужны Python или torch.

Токен Lichess (необязательно)

Обозреватель дебютов теперь требует аутентификации. Создайте персональный токен доступа на https://lichess.org/account/oauth/token/create и укажите его в .env:

cp .env.example .env
# set LICHESS_TOKEN=...

Без токена opening_explorer возвращает уведомление об отключении; все остальные инструменты работают.

Фильтры обозревателя строгие. Скорости: ultraBullet, bullet, blitz, rapid, classical и correspondence; диапазоны рейтинга: 0, 1000, 1200, 1400, 1600, 1800, 2000, 2200 и 2500. masters не принимает ни один из фильтров. Недействительные фильтры отклоняются локально. Временные сбои (сеть, таймаут, 429 и 5xx) повторяются один раз в пределах общего бюджета в 12 секунд; недействительные запросы и другие ответы 4xx не повторяются.

Настройка в вашем MCP-клиенте

opencode

Добавьте в opencode.json (проект) или ~/.config/opencode/opencode.json (глобально):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "llm-chess-mcp": {
      "type": "local",
      "command": ["npx", "-y", "llm-chess-mcp"],
      "enabled": true,
      "environment": {
        "LICHESS_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

Добавьте в .mcp.json (проект) или ~/.claude.json (глобально) или выполните:

claude mcp add llm-chess-mcp -- npx -y llm-chess-mcp

{
  "mcpServers": {
    "llm-chess-mcp": {
      "command": "npx",
      "args": ["-y", "llm-chess-mcp"],
      "env": {
        "LICHESS_TOKEN": "your-token"
      }
    }
  }
}

Codex CLI

Добавьте в ~/.codex/config.toml:

[mcp_servers.llm-chess-mcp]
command = "npx"
args = ["-y", "llm-chess-mcp"]

[mcp_servers.llm-chess-mcp.env]
LICHESS_TOKEN = "your-token"

Или через CLI:

codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_TOKEN=your-token

Инструменты

Формат результатов

structuredContent — это канонический успешный результат. Сбои на уровне обработчика устанавливают isError и предоставляют structuredContent.error. Сбои схемы ввода генерируются MCP SDK до обработчика и используют его стандартный текстовый результат isError без structuredContent. В противном случае content — это лишь краткое человекочитаемое резюме, и его нельзя разбирать как данные.

Соглашения о счёте

• Оценки Stockfish даны с точки зрения стороны, делающей ход: положительный cp означает, что сторона, делающая ход, лучше; mate N означает, что сторона, делающая ход, ставит мат за N ходов. wdl — это [win, draw, loss] в промилле для стороны, делающей ход.

• move_candidates возвращает moverCp (точка зрения делающего ход — чем выше, тем лучше для игрока, выбирающего ход) и whiteCp (фиксированная точка зрения белых), чтобы знак никогда не менялся.

• move_evaluate сообщает оценку с точки зрения делающего ход, а также cpLoss (потерянные сотые пешки по сравнению с лучшим ходом) и классификацию: best / excellent / good / inaccuracy / mistake / blunder.

• maia3Prob — это вероятность человеческого хода, а не качество хода. Ход с высокой вероятностью может быть объективно плохим.

Структура кандидатов

move_candidates возвращает каждого кандидата с тремя независимыми аспектами:

{
  "uci": "g1f3",
  "san": "Nf3",
  "objective": { "rank": 1, "moverCp": 55, "whiteCp": 55, "cpLoss": 0, "moverMate": null, "wdl": [153, 844, 3] },
  "human": { "maia3Prob": 0.62, "selfElo": 1500, "opponentElo": 1500 },
  "opening": { "status": "available", "games": 18421, "frequency": 0.31 }
}

• objective — Stockfish: сила движка, никогда не смешивается с человечностью. moverCp — с точки зрения делающего ход (чем выше, тем лучше для выбирающего).

• human — условная вероятность Maia3 при целевом Elo.

• opening — эмпирическая частота Lichess (другой сигнал, чем Maia3).

opening.status может быть available, no_data (API работает, но нет партий в этой позиции), unavailable (таймаут/429/401) или disabled (нет токена). Результаты Stockfish + Maia3 возвращаются всегда, независимо от этого.

move_candidates также возвращает moveSensitivity, описывающий, насколько резко меняется оценка между лучшими линиями движка:

{ "moveSensitivity": { "level": "high", "topMoveSpreadCp": 245 } }

level может быть low (разброс <80cp), medium (80–200cp) или high (≥200cp). Высокая чувствительность означает, что выбор среди правдоподобных альтернатив может существенно изменить оценку — это полезно для решения, стоит ли ослабить игру или играть точно.

Уровни анализа

Инструменты Stockfish принимают пресет analysis_level вместо сырых параметров UCI:

Явные переопределения depth/multipv по-прежнему доступны для продвинутого использования.

Защита от устаревшей позиции

Каждое чтение состояния возвращает revision. game_play_move требует expected_revision; если игра продвинулась с момента вашего последнего чтения, ход отклоняется:

{ "error": { "code": "STALE_POSITION", "message": "position changed: expected revision 2, current 3" } }

Ограничения выполнения

• Сохраняется до 1 000 игровых сессий; неактивные сессии истекают через один час.

• move_evaluate принимает не более 10 ходов за вызов.

• Импортируемые PGN ограничены 1 МиБ и 4 096 полуходами.

• Stockfish принимает до 32 активных или поставленных в очередь анализов.

Намерения

move_candidates_by_intent ранжирует кандидатов для выбранного намерения. Это удобный слой поверх move_candidates; фиксированные пороги ниже являются эвристическими значениями по умолчанию, а не источником истины:

Этот инструмент ранжирует кандидатов, но не выбирает ход. Используйте возвращённые сигналы и контекст разговора для принятия окончательного решения — не сопоставляйте уровень игрока механически с намерением.

Пример потока

Обычный цикл игры состоит из трёх вызовов:

1. create_game → game_id

2. move_candidates → выберите ход

3. game_play_move (с expected_revision) → зафиксируйте его

Углубляйтесь только при необходимости:

• position_analyze — объективные лучшие линии

• human_move_distribution — что сыграл бы человек с данным Elo

• opening_explorer — статистика реальных партий

• move_evaluate — оцените конкретный ход (или сравните несколько)

Проверка ONNX Maia3

Экспортированная модель ONNX проходит регрессионное тестирование против исходной реализации Maia3 на фиксированных позициях и парах Elo:

.venv-maia3/bin/python scripts/verify_maia3.py --model 5m

Она проверяет согласованность ходов top-1/top-k и максимальную ошибку вероятности для обнаружения регрессий экспорта/выполнения. Встроенный maia3-5m.onnx проходит с 100% согласованностью top-1 и top-5 и максимальной ошибкой вероятности < 1e-4.

Проверка пакета

Артефакты пакета проверяются локально; этот проект намеренно не имеет размещённого CI-процесса.

Запустите pnpm check для детерминированного офлайн-контроля. Используйте pnpm test:package, чтобы упаковать проект, установить архив в чистую временную директорию и запустить установленный бинарник llm-chess-mcp против реальных сред выполнения Stockfish и Maia. pnpm release:check выполняет обе проверки, а также аудит производственных зависимостей и пробный запуск манифеста пакета.

Лицензия и атрибуция

Этот проект лицензирован под AGPL-3.0 (см. LICENSE).

Он включает и зависит от сторонних компонентов:

Встроенная модель Maia3 (models/maia3-5m.onnx) получена из UofTCSSLab/Maia3-5M на b6559de2398d7140b985f28fd2c19fb5e47ddabe. Экспорт в ONNX выполняется на этапе сборки (scripts/export_maia3.py); во время выполнения не исполняется никакой Python-код Maia3.