Chess Coach Agent — MCP 集成作业

一个智能体，接收已结束棋局（lichess.org）的链接，通过 Playwright MCP 获取棋局，通过自定义 Chess Mistake Coach MCP 服务器用本地 Stockfish 进行分析，通过 Obsidian MCP 读写玩家的训练日志，并生成个性化训练计划：分类错误、匹配的谜题以及学习资源推荐。

Claude Agent SDK agent
 ├── playwright   MCP (existing #1, stdio via npx)  → fetch game PGN from the link
 ├── obsidian     MCP (existing #2, http, plugin)   → read/write training journal
 ├── coach        MCP (custom, stdio, this repo)    → analyze_game, find_training_puzzles,
 │                                                     recommend_study_resources,
 │                                                     generate_puzzle_from_position
 └── smartsearch  MCP (bonus #4, stdio, vendored)   → semantic search over the vault's
                                                        150-resource library (optional —
                                                        see "Bonus" section below)

前置条件

• Python 3.11+

• Node.js 18+（用于 Playwright MCP：npx @playwright/mcp）

• 原生安装 Claude Code CLI（Claude Agent SDK 会启动它；在 Windows 上必须是 claude.exe，而不是 npm 的 .cmd 垫片）

• Stockfish 二进制文件 — 从 https://stockfishchess.org/download/ 下载

• Obsidian 桌面应用，并安装 Local REST API 社区插件（coddingtonbear/obsidian-local-rest-api，已在 v5.1.0 上测试）

• 用于 Claude Agent SDK 的 Anthropic API 密钥（或 Claude 订阅登录）

安装

python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"          # Windows
npx --yes playwright install chromium          # browser for Playwright MCP

以下所有命令都显式使用 .venv/Scripts/python.exe，而不是裸的 python/streamlit，因此无论 venv 是否已在 shell 中激活都能正常工作——裸的 streamlit run ... 会拾取 PATH 中排在最前面的任何 Streamlit，这通常不是本项目的 venv，并且缺少 claude-agent-sdk，会导致 ModuleNotFoundError: No module named 'claude_agent_sdk'。

配置

将 .env.example 复制为 .env 并填写：

Obsidian 设置： 打开（或创建）一个专用的演示 vault，安装并启用 Local REST API 社区插件，在插件设置中启用其非加密 HTTP 服务器（端口 27123），并将 API 密钥复制到 .env 中。一个包含 Player Profile.md 和 TrainingLog/ 文件夹的现成演示 vault 在 docs/demo_script.md 中有描述。

数据集： data/puzzles_subset.csv（从 CC0 Lichess 谜题数据库中筛选出的 1,249 个谜题）随仓库一起提供，因此自定义服务器在运行时不需要网络访问。要从完整的 600 万行数据库重新生成它：

python scripts/prepare_puzzle_dataset.py

运行 — 两个独立进程

自定义 MCP 服务器独立运行（在答辩中用于证明进程分离；智能体也会通过 stdio 生成自己的实例）：

.venv/Scripts/python.exe -m chess_coach_mcp.server

脚本化的独立验证（握手、工具发现、每个工具调用一次，外加一个无效输入错误用例）：

.venv/Scripts/python.exe scripts/smoke_test_server.py

智能体 — CLI（推荐用于答辩/演示，因为 MCP 连接和工具调用在终端中可见）：

.venv/Scripts/python.exe -m chess_coach_agent.cli --game-url "https://lichess.org/787zsVup" --username aanreitaylor

选项：--username <name> 从 PGN 头部选择你的执子颜色；--color white|black 强制指定。

智能体 — Web 界面（推荐日常使用）：

.venv/Scripts/python.exe -m streamlit run chess_coach_agent/webapp.py

打开 http://localhost:8501 页面 — 粘贴棋局链接，可选设置用户名/执子颜色，点击 Analyze，并在结果渲染之前观看实时进度（MCP 连接状态、每次工具调用）：

• 完整的散文式训练计划报告；

• 每个关键时刻一个大型逐步棋盘（chess_coach_agent/board_render.py，基于 chess.svg 构建，用 ◀ ▶ 导航，而不是一排小缩略图）：首先是你实际走的棋（🔴），然后是引擎的计划逐步推进（🟢）——每个错误还附带一段简短的人工解读（💡），由智能体自己撰写（其响应中的一个 move-notes 块，由 UI 提取——参见 system_prompt.py），解释该计划达成了什么以及所走之棋具体差在哪里，而不仅仅是一个厘兵数值；

• 如果 generate_puzzle_from_position 生成了合格的谜题，则对其强制获胜变例采用同样的逐步处理；

• 如果可选的 smartsearch 连接可用，则显示一个简短的"更多探索"部分，来自对资源库的语义搜索（见下文）。

棋盘和谜题数据直接来自从消息流中捕获的 analyze_game / generate_puzzle_from_position 工具结果——不会从散文式报告中重新推导。两个入口共享同一个会话驱动程序（chess_coach_agent/core.py）；Web 界面纯粹是其上的显示层，而不是单独的实现。

加分项：对资源库的语义搜索（第 4 个 MCP 连接）

除了作业要求的现有 + 自定义服务器之外，本项目还接入了第四个可选的 MCP 连接：对 150 条学习资源库（data/study_resources.json）和训练日志的本地语义搜索，通过社区 smart-connections-mcp 服务器的本地修补（vendored）构建实现。这纯粹是补充性的——智能体仍然使用必需的、确定性的 coach.recommend_study_resources 工具作为主要推荐路径；语义搜索只是额外添加几条"你可能还喜欢"的结果，这些结果按含义而非精确主题标签匹配。参见 third_party/smart-connections-mcp/PATCH_NOTES.md 了解发现、修补和验证的内容（上游包中的两个真实 bug），以及 docs/design_rationale.md 了解为什么这是可选的而不是评分所需的工具之一。

一次性设置（在 Obsidian + Smart Connections 社区插件安装完毕且 vault 至少打开过一次之后）：

cd third_party/smart-connections-mcp
npm install
npx tsc
cd ../..
.venv/Scripts/python.exe scripts/build_smartsearch_index.py

如果此构建步骤尚未运行，smartsearch 只会从智能体的 MCP 连接中被省略（不会显示为"失败"）——其他一切仍然正常工作。

文档

• docs/tool_contracts.md — 所有 4 个自定义工具 + 所用现有服务器工具的完整 Part C 契约

• docs/design_rationale.md — 每个服务器/工具的原因、权衡、局限性

• docs/demo_script.md — 映射到作业所需演示步骤的答辩检查清单

测试

.venv/Scripts/python.exe -m pytest

涵盖走棋分类阈值、谜题筛选和资源排序（纯逻辑；不需要引擎或网络）。

安全 / 运维说明

• 仓库中无密钥：Obsidian API 密钥只存在于 .env 中（已被 gitignore）。

• 自定义服务器在运行时仅使用本地数据（Stockfish + CSV + JSON）。

• Playwright 仅对公共页面进行只读使用；无登录、无表单输入。

• 速率限制：智能体每次运行对 lichess.org 约加载 1 次页面；数据集脚本从 database.lichess.org 下载一个静态文件。