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

아래의 모든 명령은 단순 python/streamlit 대신 .venv/Scripts/python.exe를 명시적으로 사용하므로, 셸에서 venv가 활성화되어 있든 아니든 작동합니다. 단순 streamlit run ...은 PATH에서 가장 먼저 발견되는 Streamlit을 사용하게 되는데, 이는 보통 이 프로젝트의 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(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은 강제로 지정합니다.

에이전트 — 웹 UI (일상 사용에 권장):

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

http://localhost:8501에서 페이지가 열립니다 — 게임 링크를 붙여넣고, 선택적으로 사용자 이름/색상을 설정하고, 분석을 클릭하고, 결과가 아래에 렌더링되기 전에 실시간 진행 상황(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)를 공유합니다. 웹 UI는 그 위의 순수한 표시 계층일 뿐, 별도의 구현이 아닙니다.

보너스: 리소스 라이브러리에 대한 의미론적 검색 (4번째 MCP 연결)

과제에서 요구하는 기존 + 커스텀 서버 외에도, 이 프로젝트는 네 번째, 선택적 MCP 연결을 구성합니다: 150개 항목의 학습 리소스 라이브러리(data/study_resources.json)와 훈련 일지에 대한 로컬 의미론적 검색으로, 벤더링되고 로컬 패치된 커뮤니티 smart-connections-mcp 서버 빌드를 통해 제공됩니다. 이는 순전히 보조적인 기능입니다 — 에이전트는 여전히 필수적이고 결정적인 coach.recommend_study_resources 도구를 기본 추천 경로로 사용합니다. 의미론적 검색은 정확한 테마 태그가 아닌 의미로 찾은 몇 가지 "이것도 좋아할 수 있습니다" 결과만 추가합니다. 발견, 패치, 검증된 내용(업스트림 패키지의 실제 버그 2개)은 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 — 4개의 커스텀 도구 + 사용된 기존 서버 도구에 대한 전체 파트 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에서 정적 파일 하나를 다운로드합니다.