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_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 秒总预算内重试一次；无效请求和其他 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 MiB 和 4,096 层（ply）。

• 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 —— 评估某一具体着法（或比较多个）

Maia3 ONNX 验证

导出的 ONNX 模型在固定局面和 Elo 组合上与上游 Maia3 实现进行回归测试：

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

它检查 top-1/top-k 着法一致性和最大概率误差，以检测导出/运行时回归。随包的 maia3-5m.onnx 通过测试，top-1 和 top-5 一致性为 100%，最大概率误差 < 1e-4。

包验证

包工件在本地验证；本项目有意不设托管 CI 工作流。

运行 pnpm check 进行确定性离线门禁。使用 pnpm test:package 打包项目，在干净的临时目录中安装 tarball，并针对真实的 Stockfish 和 Maia 运行时运行已安装的 llm-chess-mcp 二进制文件。pnpm release:check 同时运行两个检查，并加上生产依赖审计和包清单试运行。

许可证与归属

本项目采用 AGPL-3.0 许可（见 LICENSE）。

它打包并依赖第三方组件：

随附的 Maia3 模型（models/maia3-5m.onnx）衍生自 UofTCSSLab/Maia3-5M at b6559de2398d7140b985f28fd2c19fb5e47ddabe。 ONNX 导出是构建时步骤（scripts/export_maia3.py）；运行时 不执行任何 Maia3 Python 代码。