Chess Coach Agent — Задание по интеграции MCP

Агент, который принимает ссылку на завершённую шахматную партию (lichess.org), загружает партию через Playwright MCP, анализирует её локальным Stockfish через кастомный MCP-сервер Chess Mistake Coach, читает/записывает тренировочный журнал игрока через 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)

• CLI Claude Code, установленный нативно (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)

• API-ключ Anthropic (или вход через подписку Claude) для Claude Agent SDK

Установка

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 в вашей оболочке — голый streamlit run ... подхватит тот Streamlit, который первый в вашем PATH, а это обычно не venv этого проекта, и в нём нет claude-agent-sdk, из-за чего возникает ModuleNotFoundError: No module named 'claude_agent_sdk'.

Конфигурация

Скопируйте .env.example в .env и заполните:

Настройка Obsidian: откройте (или создайте) выделенное демо-хранилище, установите и включите плагин сообщества Local REST API, включите его незашифрованный HTTP-сервер (порт 27123) в настройках плагина и скопируйте API-ключ в .env. Готовое демо-хранилище с Player Profile.md и папкой TrainingLog/ описано в docs/demo_script.md.

Набор данных: data/puzzles_subset.csv (1 249 задач, отфильтрованных из базы задач Lichess с лицензией CC0) поставляется в репозитории, поэтому кастомному серверу не нужен сетевой доступ во время работы. Чтобы перегенерировать его из полной базы на 6 млн строк:

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 <имя> выбирает ваш цвет из заголовков PGN; --color white|black принудительно задаёт его.

Агент — веб-интерфейс (рекомендуется для повседневного использования):

.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 в его ответе, извлекаемый интерфейсом — см. system_prompt.py), объясняющей, чего достигает план и что конкретно было хуже в сыгранном ходе, а не просто число центипешек;

• если generate_puzzle_from_position сгенерировал подходящую задачу — то же пошаговое представление для её форсированной выигрышной линии;

• если дополнительное подключение smartsearch активно — короткий раздел «More to explore» из семантического поиска по библиотеке ресурсов (см. ниже).

Данные доски и задач берутся напрямую из результатов инструментов analyze_game / generate_puzzle_from_position, перехваченных из потока сообщений — ничего не пересчитывается из текстового отчёта. Обе точки входа используют один и тот же драйвер сессии (chess_coach_agent/core.py); веб-интерфейс — это чисто слой отображения поверх него, а не отдельная реализация.

Бонус: семантический поиск по библиотеке ресурсов (4-е MCP-подключение)

Помимо обязательных для задания существующего и кастомного серверов, этот проект подключает четвёртое, опциональное MCP-подключение: локальный семантический поиск по библиотеке из 150 учебных ресурсов (data/study_resources.json) и тренировочному журналу, через вендоренную, локально пропатченную сборку сервера сообщества smart-connections-mcp. Это чисто дополнительная функция — агент по-прежнему использует обязательный детерминированный инструмент coach.recommend_study_resources как основной путь рекомендаций; семантический поиск лишь добавляет несколько результатов «вам может также понравиться», найденных по смыслу, а не по точным тематическим тегам. См. third_party/smart-connections-mcp/PATCH_NOTES.md о том, что было найдено, пропатчено и проверено (два реальных бага в вышестоящем пакете), и docs/design_rationale.md о том, почему это опционально, а не один из оцениваемых обязательных инструментов.

Одноразовая настройка (после установки Obsidian + плагина сообщества Smart Connections и хотя бы одного открытия хранилища):

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 — полные контракты части C для всех 4 кастомных инструментов + используемых инструментов существующего сервера

• docs/design_rationale.md — почему каждый сервер/инструмент, компромиссы, ограничения

• docs/demo_script.md — чек-лист защиты, сопоставленный с обязательными шагами демо из задания

Тесты

.venv/Scripts/python.exe -m pytest

Покрывают пороги классификации ходов, фильтрацию задач и ранжирование ресурсов (чистая логика; движок и сеть не нужны).

Замечания по безопасности / эксплуатации

• В репозитории нет секретов: ключ Obsidian API хранится только в .env (в gitignore).

• Кастомный сервер использует только локальные данные в рантайме (Stockfish + CSV + JSON).

• Playwright используется только на чтение против публичных страниц; никаких логинов и ввода форм.

• Ограничения частоты: агент делает ~1 загрузку страницы за запуск против lichess.org; скрипт набора данных скачивает один статический файл с database.lichess.org.