Chess Esca

chess-esca-mcp

一个基于 esca 的 MCP 服务：以 JSON 形式提供棋规，供 Agent 读取。

输入 FEN 和着法，输出枚举值及其对应的格子。着法是否合法及原因、局面的状态和双方可提出的和棋，以及局面的命名事实、子力决定的残局及其理论结论、开局的 ECO 代码、开局库中的着法，还有 PGN 的读取与写入。每个分类答案还会附带 prose：用一句通俗的英文描述同一内容，与枚举值并列，而非取而代之。

这里没有引擎，也没有搜索。 此服务的任何回答都不会说明某个着法有多 好。要获取数值和着法线路，请使用 chess-uci-mcp，它可以驱动 Stockfish 或 Leela；两者回答的问题不同，很适合并列使用。

依赖项

Python 3.12 或更新版本，以及 uv/uvx。

用法

"mcpServers": {
  "chess-esca-mcp": {
    "command": "uvx",
    "args": ["chess-esca-mcp@latest"]
  }
}

对于 Claude Desktop，请在 claude_desktop_config.json 中配置，路径为 Settings → Developer → Edit Config：

• macOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

对于 Claude Code，插件会自动完成配置：

/plugin marketplace add AnglerfishChess/plugins
/plugin install chess-esca-mcp@anglerfish-chess

此服务不接受参数。它只会读取你提供的局面，以及你为 book_moves 指定的开局库文件。

工具

每个工具都以相同方式接收局面：fen（省略时使用初始局面）、从该局面开始的着法——每步以 SAN（Nf3）或 UCI（g1f3）格式书写——或改为提供完整棋局的 pgn。variant 的值为 classic 或 chess960。只有提供引导至该局面的着法时，才能判断重复局面和五十回合和棋请求，因为 FEN 不包含这些信息。

工具	回答内容
position	完整状态：行棋方、将军及其将军子、棋局状态、自动和棋及可请求的和棋及其依据、合法着法数量、开局、子力、双方两种王车易位的所有阻碍、吃过路兵机会、牵制和串击，以及由子力决定的残局。
legal_moves	所有合法着法的 SAN 和 UCI 格式，以及每步着法的作用、被吃棋子、升变、将军和静态交换评估；并按吃子、将军、王车易位、升变、吃过路兵和非吃子着法分组。
explain_move	某一步着法是否合法。若不合法，则一次列出所有原因及每个原因所依据的格子；若合法，则说明它会带来的变化、着法后的局面，以及它会开启的和棋请求。
facts	按组列出局面的命名事实，每个值都标有名称；若双方的值不同，还会标明颜色。groups 用于选择分组；除非明确请求，否则不包含 placement 和 maps。
ending	子力决定的残局：其标识、类别、理论上的结果判断、获胜技巧，以及判定所依据的兵赛、象和对王。
opening	局面的 ECO 代码和名称，以及该线路到达的最深命名局面。
book_moves	Polyglot 开局库中适用于该局面的着法及其权重。
pgn	读取 PGN 棋局，返回棋局头信息、着法、注释、最终局面、开局和结果。
to_pgn	将着法列表写成 PGN 棋局。

如果输入未指定局面、着法或棋局，返回内容为 {"error": {"kind": ..., "message": ..., "hint": ...}}，不会返回回溯信息。

资源 esca://facts-catalogue 列出所有事实分组及其包含的字段、每个字段的类型，以及一条释义；它由 esca 根据事实定义自动生成。提示词 analyse-position 会引导 Agent 使用这些工具读取局面。

开局库

不附带任何棋库。book_moves 接受你自己的 Polyglot .bin 文件路径；这种格式很常见，因此任何支持读取 Polyglot 的引擎都能使用为其编写的棋库。esca.polyglot 提供用于获取棋库的 download(url, path)，以及用于从 PGN 写入棋库的 Builder。

开发

该服务是 esca 仓库中的第二个发行包：库位于仓库根目录，此目录与其并列。开发时，它会使用相邻 crate 中的 esca；安装后，则会使用 PyPI 上的版本。

git clone https://github.com/AnglerfishChess/esca.git
cd esca/mcp

uv sync --all-groups     # builds the esca extension from ../ and installs it here
uv run --no-sync pytest
uvx ruff check . && uvx ruff format --check . && uvx pyrefly check

在检出目录中运行 uv run chess-esca-mcp。

版本号与 esca 自身一致：同一个标签会同时发布库和此服务，esca== 固定的也是同一个版本。

MCP 注册表

registry.modelcontextprotocol.io 是公开 MCP 服务的索引。该条目由 server.json 描述，名称为 io.github.AnglerfishChess/chess-esca-mcp；PyPI 软件包的所有权由本文件顶部附近的 mcp-name: 标记证明，该标记会成为 PyPI 显示的软件包描述。注册表从已发布的制品中读取，因此只有包含该标记的版本发布到 PyPI 后，条目才会生效。

相关项目

• esca — 此服务所使用的库。
• chess-uci-mcp — 引擎端：使用 Stockfish 或 Leela 进行分析并给出最佳着法。

许可证

MIT — 详见 LICENSE。