Chess Coach Agent — Asignación de integración MCP

Un agente que toma un enlace a una partida de ajedrez terminada (lichess.org), obtiene la partida a través de Playwright MCP, la analiza con un Stockfish local mediante un servidor MCP personalizado Chess Mistake Coach, lee/escribe el diario de entrenamiento del jugador mediante Obsidian MCP, y produce un plan de entrenamiento personalizado: errores clasificados, puzzles correspondientes y recomendaciones de recursos de estudio.

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)

Requisitos previos

• Python 3.11+

• Node.js 18+ (para Playwright MCP: npx @playwright/mcp)

• CLI de Claude Code instalado de forma nativa (el Claude Agent SDK lo lanza; en Windows debe ser un claude.exe, no el shim .cmd de npm)

• Binario de Stockfish — descárgalo de https://stockfishchess.org/download/

• Aplicación de escritorio Obsidian con el plugin comunitario Local REST API (coddingtonbear/obsidian-local-rest-api, probado con v5.1.0)

• Una clave de API de Anthropic (o inicio de sesión con suscripción a Claude) para el Claude Agent SDK

Instalación

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

Todos los comandos siguientes usan .venv/Scripts/python.exe explícitamente en lugar de un python/streamlit simple, de modo que funcionen tanto si el venv está activado en tu shell como si no — un streamlit run ... simple tomará cualquier Streamlit que esté primero en tu PATH, que normalmente no es el venv de este proyecto y le falta claude-agent-sdk, lo que provoca ModuleNotFoundError: No module named 'claude_agent_sdk'.

Configuración

Copia .env.example a .env y rellena:

Configuración de Obsidian: abre (o crea) un vault de demostración dedicado, instala y habilita el plugin comunitario Local REST API, activa su servidor HTTP no cifrado (puerto 27123) en la configuración del plugin, y copia la clave de API en .env. Un vault de demostración listo con un Player Profile.md y una carpeta TrainingLog/ se describe en docs/demo_script.md.

Conjunto de datos: data/puzzles_subset.csv (1,249 puzzles filtrados de la base de datos de puzzles CC0 de Lichess) se incluye en el repositorio, por lo que el servidor personalizado no necesita acceso a la red en tiempo de ejecución. Para regenerarlo desde la base de datos completa de 6M de filas:

python scripts/prepare_puzzle_dataset.py

Ejecución — dos procesos independientes

Servidor MCP personalizado independiente (usado durante la defensa para demostrar la separación de procesos; el agente también lanza su propia instancia sobre stdio):

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

Prueba independiente con script (handshake, descubrimiento de herramientas, una llamada por herramienta, además de un caso de error de entrada no válida):

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

Agente — CLI (recomendado para la defensa/demo, ya que las conexiones MCP y las llamadas a herramientas son visibles en el terminal):

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

Opciones: --username <name> elige tu color de las cabeceras PGN; --color white|black lo fuerza.

Agente — interfaz web (recomendado para uso diario):

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

Abre una página en http://localhost:8501 — pega un enlace de partida, opcionalmente establece tu usuario/color, haz clic en Analizar y observa el progreso en vivo (estado de la conexión MCP, cada llamada de herramienta) antes de que los resultados se muestren debajo:

• el informe completo del plan de entrenamiento en texto plano;

• un tablero grande de paso a paso por momento crítico (chess_coach_agent/board_render.py, construido sobre chess.svg, navegado con ◀ ▶ en lugar de una fila de miniaturas): primero el movimiento que realmente jugaste (🔴), luego el plan del motor continuando movimiento a movimiento (🟢) — cada error también lleva una breve interpretación humana (💡) que el agente escribe por sí mismo (un bloque move-notes en su respuesta, extraído por la interfaz — ver system_prompt.py) que explica qué logra el plan y qué fue concretamente peor del movimiento jugado, no solo un número de centipawn;

• si generate_puzzle_from_position produjo un puzzle que cumple los requisitos, el mismo tratamiento de paso a paso para su línea ganadora forzada;

• si la conexión extra smartsearch está activa, una breve sección "Más para explorar" de búsqueda semántica sobre la biblioteca de recursos (ver más abajo).

Los datos del tablero y del puzzle vienen directamente de los resultados de las herramientas analyze_game / generate_puzzle_from_position capturados del flujo de mensajes — nada se re-deriva del informe en prosa. Ambos puntos de entrada comparten el mismo controlador de sesión (chess_coach_agent/core.py); la interfaz web es puramente una capa de visualización sobre él, no una implementación separada.

Extra: búsqueda semántica sobre la biblioteca de recursos (4ª conexión MCP)

Más allá de los servidores existentes + personalizados requeridos por la asignación, este proyecto conecta una cuarta conexión MCP, opcional: búsqueda semántica local sobre la biblioteca de recursos de estudio de 150 entradas (data/study_resources.json) y el diario de entrenamiento, mediante una versión localmente parcheada del servidor comunitario smart-connections-mcp. Es puramente complementaria — el agente sigue usando la herramienta requerida y determinista coach.recommend_study_resources como su vía principal de recomendación; la búsqueda semántica solo añade unos pocos resultados "también te puede gustar" encontrados por significado en lugar de etiquetas de tema exactas. Ver third_party/smart-connections-mcp/PATCH_NOTES.md para lo que se encontró, parcheó y verificó (dos errores reales en el paquete original), y docs/design_rationale.md para saber por qué esto es opcional en lugar de una de las herramientas requeridas evaluadas.

Configuración única (después de que Obsidian + el plugin comunitario Smart Connections estén instalados y el vault se haya abierto al menos una vez):

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

Si este paso de compilación no se ha ejecutado, smartsearch se omite simplemente de las conexiones MCP del agente (no se muestra como "fallido") — todo lo demás sigue funcionando.

Documentación

• docs/tool_contracts.md — contratos completos de la Parte C para las 4 herramientas personalizadas + las herramientas del servidor existentes usadas

• docs/design_rationale.md — por qué cada servidor/herramienta, compensaciones, limitaciones

• docs/demo_script.md — lista de verificación de la defensa mapeada a los pasos de demostración requeridos por la asignación

Pruebas

.venv/Scripts/python.exe -m pytest

Cubre umbrales de clasificación de movimientos, filtrado de puzzles y clasificación de recursos (lógica pura; sin motor ni red necesarios).

Notas de seguridad / operativas

• No hay secretos en el repositorio: la clave de API de Obsidian solo vive en .env (ignorado por git).

• El servidor personalizado usa solo datos locales en tiempo de ejecución (Stockfish + CSV + JSON).

• Playwright se usa solo de lectura contra páginas públicas; sin inicios de sesión, sin entrada de formularios.

• Límites de tasa: el agente hace ~1 carga de página por ejecución contra lichess.org; el script del conjunto de datos descarga un archivo estático de database.lichess.org.