llm-chess-mcp

LLMがプレイ、分析、強さの調整を、すべての判断をエンジンに委ねることなく行えるMCPチェスランタイムです。

単一の最善手を返すのではなく、客観的な強さ（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_TOKENが設定されている場合のみLichessにクエリを実行します。それ以外の場合はネットワークリクエストを行わずにスキップします。

Maia3をONNXにエクスポート（ビルド時のみ）

このステップではPython + PyTorchが一度だけ必要です。Maia3チェックポイントをダウンロードし、再実装をオリジナルに対して検証し、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秒の総予算内で1回再試行されます。無効なリクエストやその他の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によって生成され、structuredContentなしの標準のisErrorテキスト結果を使用します。それ以外の場合、contentは短い人間可読の要約のみであり、データとして解析してはなりません。

スコアの規約

• Stockfishのスコアは手番側の視点です。正のcp = 手番側が有利。mate N = 手番側がN手でメイト。wdlは手番側の[勝ち、引き分け、負け]をパーミルで表します。

• move_candidatesはmoverCp（動かす側の視点 — 手を選ぶプレイヤーにとって高いほど良い）とwhiteCp（固定の白の視点）を提供するため、符号が反転することはありません。

• move_evaluateは動かす側の視点からスコアを報告し、さらにcpLoss（最善手に対して失ったセンチポーン）と分類を提供します: best / excellent / good / inaccuracy / mistake / blunder。

• maia3Probは人間らしさであり、手の質ではありません。高い確率の手が客観的に悪い場合もあります。

候補構造

move_candidatesは各候補を3つの独立した側面で返します:

{
  "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 — ターゲットEloでのMaia3条件付き確率。

• opening — Lichessの経験的频率（Maia3とは異なるシグナル）。

opening.statusはavailable、no_data（APIはOKだがこの局面にゲームがない）、unavailable（タイムアウト/429/401）、またはdisabled（トークンなし）です。Stockfish + Maia3の結果は常に返されます。

move_candidatesはまたmoveSensitivityを返し、トップエンジンライン間で評価がどれだけ急激に変化するかを説明します:

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

levelはlow（<80cpスプレッド）、medium（80–200cp）、high（≥200cp）です。感度が高いということは、妥当な代替案の選択が評価を実質的に変える可能性があることを意味します — 手を緩めるか正確にプレイするかを決定するのに役立ちます。

分析レベル

Stockfishツールは生のUCIノブの代わりにanalysis_levelプリセットを受け入れます:

明示的なdepth/multipvオーバーライドは上級者向けに引き続き利用可能です。

古い位置ガード

すべての状態読み取りはrevisionを返します。game_play_moveは**expected_revisionを必須**とします。最後の読み取り以降にゲームが進行している場合、手は拒否されます:

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

ランタイム制限

• 最大1,000のゲームセッションが保持され、アイドルセッションは1時間後に期限切れになります。

• move_evaluateは1回の呼び出しで最大10手を受け入れます。

• インポートされたPGNは1 MiBと4,096プライに制限されます。

• Stockfishは最大32のアクティブまたはキューされた分析を受け入れます。

意図

move_candidates_by_intentは選択された意図に基づいて候補をランク付けします。これはmove_candidatesの利便性レイヤーです。以下の固定しきい値はヒューリスティックなデフォルトであり、真実の源ではありません:

このツールは候補をランク付けしますが、手を選択しません。返されたシグナルと会話の文脈を使用して最終決定を行ってください — ユーザーのスキルを機械的に意図にマッピングしないでください。

例のフロー

通常のプレイループは3つの呼び出しです:

1. create_game → game_id

2. move_candidates → 手を選ぶ

3. game_play_move（expected_revision付き）→ コミット

必要な場合にのみ深く進んでください:

• position_analyze — 客観的な最善ライン

• human_move_distribution — 特定のEloの人間がプレイする手

• opening_explorer — 実際の対局統計

• move_evaluate — 特定の手をスコアリング（または複数を比較）

Maia3 ONNX検証

エクスポートされたONNXモデルは、固定位置とEloペアにわたってアップストリームのMaia3実装に対して回帰テストされます:

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

トップ1/トップkの手の一致と最大確率誤差をチェックし、エクスポート/ランタイムの回帰を検出します。同梱のmaia3-5m.onnxは100%のトップ1およびトップ5一致、最大確率誤差<1e-4で合格します。

パッケージ検証

パッケージアーティファクトはローカルで検証されます。このプロジェクトには意図的にホストされたCIワークフローはありません。

pnpm checkを実行して決定論的なオフラインゲートを行います。pnpm test:packageを使用してプロジェクトをパックし、クリーンな一時ディレクトリにtarballをインストールし、インストールされた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) であり、ランタイムが Maia3 の Python コードを実行することはありません。