Chess Coach Agent — MCP-Integrationsaufgabe

Ein Agent, der einen Link zu einer beendeten Schachpartie (lichess.org) entgegennimmt, die Partie über Playwright MCP abruft, sie mit einem lokalen Stockfish über einen eigenen Chess Mistake Coach MCP-Server analysiert, das Trainingsjournal des Spielers über Obsidian MCP liest/schreibt und einen personalisierten Trainingsplan erstellt: klassifizierte Fehler, passende Taktikaufgaben und Empfehlungen für Lernressourcen.

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)

Voraussetzungen

• Python 3.11+

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

• Claude Code CLI nativ installiert (das Claude Agent SDK startet sie; unter Windows muss es eine claude.exe sein, nicht der npm-.cmd-Shim)

• Stockfish-Binärdatei — herunterladen von https://stockfishchess.org/download/

• Obsidian-Desktop-App mit dem Community-Plugin Local REST API (coddingtonbear/obsidian-local-rest-api, getestet mit v5.1.0)

• Ein Anthropic-API-Schlüssel (oder die Anmeldung über ein Claude-Abonnement) für das Claude Agent SDK

Installation

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

Alle untenstehenden Befehle verwenden explizit .venv/Scripts/python.exe statt eines bloßen python/streamlit, damit sie funktionieren, egal ob die venv in deiner Shell aktiviert ist oder nicht — ein bloßes streamlit run ... würde das Streamlit verwenden, das zuerst in deinem PATH steht, was normalerweise nicht die venv dieses Projekts ist und dem claude-agent-sdk fehlt, was ModuleNotFoundError: No module named 'claude_agent_sdk' verursacht.

Konfiguration

Kopiere .env.example nach .env und fülle Folgendes aus:

Obsidian-Einrichtung: Öffne (oder erstelle) einen dedizierten Demo-Vault, installiere und aktiviere das Community-Plugin Local REST API, aktiviere in den Plugin-Einstellungen dessen nicht verschlüsselten HTTP-Server (Port 27123) und kopiere den API-Schlüssel in .env. Ein fertiger Demo-Vault mit einer Player Profile.md und einem TrainingLog/-Ordner wird in docs/demo_script.md beschrieben.

Datensatz: data/puzzles_subset.csv (1.249 Taktikaufgaben, gefiltert aus der CC0-Lichess-Taktikdatenbank) ist im Repository enthalten, sodass der eigene Server zur Laufzeit keinen Netzwerkzugriff benötigt. Um ihn aus der vollständigen Datenbank mit 6 Millionen Zeilen neu zu erzeugen:

python scripts/prepare_puzzle_dataset.py

Ausführen — zwei unabhängige Prozesse

Eigener MCP-Server im Standalone-Betrieb (wird während der Verteidigung verwendet, um die Prozesstrennung zu belegen; der Agent startet seine eigene Instanz zusätzlich über stdio):

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

Skriptgestützter Standalone-Nachweis (Handshake, Tool-Erkennung, ein Aufruf pro Tool sowie ein Fehlerfall mit ungültiger Eingabe):

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

Agent — CLI (für Verteidigung/Demo empfohlen, da MCP-Verbindungen und Tool-Aufrufe im Terminal sichtbar sind):

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

Optionen: --username <name> ermittelt deine Farbe aus den PGN-Headern; --color white|black erzwingt sie.

Agent — Web-UI (für den täglichen Gebrauch empfohlen):

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

Öffnet eine Seite unter http://localhost:8501 — füge einen Partielink ein, setze optional deinen Benutzernamen/deine Farbe, klicke auf Analysieren und beobachte den Live-Fortschritt (MCP-Verbindungsstatus, jeder Tool-Aufruf), bevor die Ergebnisse darunter gerendert werden:

• den vollständigen Trainingsplan-Bericht als Fließtext;

• ein großes Schritt-für-Schritt-Brett pro kritischem Moment (chess_coach_agent/board_render.py, basierend auf chess.svg, navigiert mit ◀ ▶ statt einer Reihe winziger Vorschaubilder): zuerst den Zug, den du tatsächlich gespielt hast (🔴), dann den Plan der Engine, Zug für Zug fortgesetzt (🟢) — jeder Fehler enthält außerdem eine kurze menschliche Interpretation (💡), die der Agent selbst verfasst (ein move-notes-Block in seiner Antwort, der von der UI extrahiert wird — siehe system_prompt.py) und die erklärt, was der Plan erreicht und was an dem gespielten Zug konkret schlechter war, nicht nur eine Centipawn-Zahl;

• falls generate_puzzle_from_position eine qualifizierende Taktikaufgabe erzeugt hat, dieselbe Schritt-für-Schritt-Behandlung für ihre forcierte Gewinnfortsetzung;

• falls die optionale smartsearch-Verbindung aktiv ist, einen kurzen Bereich „Mehr zum Entdecken“ aus der semantischen Suche über die Ressourcenbibliothek (siehe unten).

Brett- und Taktikdaten stammen direkt aus den Tool-Ergebnissen von analyze_game / generate_puzzle_from_position, die aus dem Nachrichtenstrom erfasst werden — nichts wird aus dem Fließtextbericht neu abgeleitet. Beide Einstiegspunkte nutzen denselben Session-Treiber (chess_coach_agent/core.py); die Web-UI ist lediglich eine Anzeigeschicht darüber, keine separate Implementierung.

Bonus: semantische Suche über die Ressourcenbibliothek (4. MCP-Verbindung)

Über die für die Aufgabe geforderten vorhandenen + eigenen Server hinaus richtet dieses Projekt eine vierte, optionale MCP-Verbindung ein: lokale semantische Suche über die Ressourcenbibliothek mit 150 Einträgen (data/study_resources.json) und das Trainingsjournal, über einen vendored, lokal gepatchten Build des Community-Servers smart-connections-mcp. Er ist rein ergänzend — der Agent nutzt weiterhin das geforderte, deterministische Tool coach.recommend_study_resources als primären Empfehlungspfad; die semantische Suche fügt lediglich ein paar „Das könnte dir auch gefallen“-Ergebnisse hinzu, die über die Bedeutung statt über exakte Themen-Tags gefunden werden. Siehe third_party/smart-connections-mcp/PATCH_NOTES.md für das, was gefunden, gepatcht und verifiziert wurde (zwei echte Bugs im Upstream-Paket), sowie docs/design_rationale.md dafür, warum dies optional ist und nicht zu den bewerteten Pflicht-Tools gehört.

Einmalige Einrichtung (nachdem Obsidian + das Community-Plugin Smart Connections installiert wurden und der Vault mindestens einmal geöffnet wurde):

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

Wenn dieser Build-Schritt nicht ausgeführt wurde, wird smartsearch einfach aus den MCP-Verbindungen des Agenten ausgelassen (nicht als „fehlgeschlagen“ angezeigt) — alles andere funktioniert weiterhin.

Dokumentation

• docs/tool_contracts.md — vollständige Part-C-Verträge für alle 4 eigenen Tools + die verwendeten Tools des vorhandenen Servers

• docs/design_rationale.md — warum jeder Server/jedes Tool, Abwägungen, Einschränkungen

• docs/demo_script.md — Verteidigungs-Checkliste, abgebildet auf die geforderten Demo-Schritte der Aufgabe

Tests

.venv/Scripts/python.exe -m pytest

Deckt die Schwellenwerte der Zugklassifizierung, die Filterung von Taktikaufgaben und das Ranking der Ressourcen ab (reine Logik; keine Engine und kein Netzwerk nötig).

Sicherheit / Betriebshinweise

• Keine Geheimnisse im Repository: Der Obsidian-API-Schlüssel liegt nur in .env (per .gitignore ignoriert).

• Der eigene Server verwendet zur Laufzeit ausschließlich lokale Daten (Stockfish + CSV + JSON).

• Playwright wird nur lesend gegen öffentliche Seiten verwendet; keine Logins, keine Formulareingaben.

• Ratenbegrenzung: Der Agent lädt pro Lauf ~1 Seite von lichess.org; das Datensatz-Skript lädt eine einzige statische Datei von database.lichess.org herunter.