チェスコーチエージェント — MCP統合課題

チェスゲームの完成済みリンク（lichess.org）を受け取り、Playwright MCPを通じてゲームを取得し、ローカルのStockfishとカスタムチェスミスコーチMCPサーバーを使って分析し、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では .cmd シムではなく claude.exe でなければならない）

• 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' が発生します。

python scripts/prepare_puzzle_dataset.py

設定

.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パズル）はリポジトリに同梱されているため、カスタムサーバーは実行時にネットワークアクセスを必要としません。完全な6M行のデータベースから再生成するには:

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

実行 — 2つの独立したプロセス

カスタムMCPサーバーのスタンドアロン実行（デモ/防御中にプロセス分離を証明するために使用。エージェントはstdio経由で独自のインスタンスを起動します）:

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

スクリプト化されたスタンドアロン実行（ハンドシェイク、ツール一覧取得、ツールごとに1回の呼び出し、さらに不正入力エラーケース）:

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

エージェント — CLI（デモ/防御用に推奨。MCP接続とツール呼び出しがターミナルに表示されます）:

オプション: --username <name> はPGNヘッダーからプレイヤーの色を選択します。--color white|black は強制的に指定します。

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

エージェント — Web UI（日常使用に推奨）:

http://localhost:8501 のページを開き、ゲームリンクを貼り付け、必要に応じてユーザー名/色を設定し、Analyzeをクリックしてライブ進行を確認します（MCP接続ステータス、各ツール呼び出し）。結果は以下のように表示されます:

• 完全な散文形式のトレーニングプランレポート;

• 重要な局面ごとに1つの大きなステップスルーボード（chess_coach_agent/board_render.py で生成、chess.svg に基づく、◀ ▶ でナビゲート。小さなサムネイルの羅列ではありません）: まず実際に指した手（🔴）、次にエンジンのプランを手順ごとに表示（🟢）— 各ミスには、エージェントが自分で書いた短い人間向けの解説（💡）が付きます（system_prompt.py の指示に従い、UIが抽出して move-notes ブロックとして表示）。プランが何を達成するのか、そして実際の手が具体的に何を悪くしたのかを、センチペアの数字だけでなく説明します;

• generate_puzzle_from_position が有効なパズルを生成した場合、その強制勝利手順も同じステップスルー形式で表示;

• ボーナスとして smartsearch 接続が有効な場合、リソースライブラリのセマンティック検索による「さらに詳しく」セクション（下記参照）。

ボードとパズルのデータは、analyze_game / generate_puzzle_from_position ツールの結果をメッセージストリームから直接取得したものです — 散文レポートから再導出されるものはありません。両方のエントリポイントは同じセッションドライバー（chess_coach_agent/core.py）を共有しており、Web UIはその上に表示レイヤーを追加するだけで、独立した実装ではありません。

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

ボーナス: リソースライブラリのセマンティック検索（4つ目のMCP接続）

このプロジェクトは、必須の既存サーバー＋カスタムサーバーに加えて、4つ目のオプションのMCP接続を配線しています: 150エントリの学習リソースライブラリ（data/study_resources.json）とトレーニングジャーナルに対するローカルセマンティック検索です。これは、コミュニティ製の smart-connections-mcp サーバーをベンダリングし、ローカルパッチを適用したものです。純粋に補助的な機能です — エージェントは依然として必須の決定的ツール coach.recommend_study_resources を主要な推薦経路として使用し、セマンティック検索は正確なテーマタグではなく意味に基づいて「さらに詳しく」の結果をいくつか追加するだけです。何が見つかり、何にパッチを当て、何を検証したか（上流パッケージの実際のバグ2件）については third_party/smart-connections-mcp/PATCH_NOTES.md を、なぜこれが必須ツールの1つではなくオプションなのかの設計上の根拠については docs/design_rationale.md を参照してください。

.venv/Scripts/python.exe -m pytest

ドキュメント

• docs/tool_contracts.md — 使用されている既存サーバーに加えて、4つのカスタムツールすべての完全なPart C契約

• docs/design_rationale.md — 各サーバー/ツールの選択理由、トレードオフ、制限事項

• docs/demo_script.md — 課題の必須デモステップに対応した防御チェックリスト

GXP10

テスト

移動分類の閾値、パズルフィルタリング、リソースランキングをカバー（純粋なロジックのみ。エンジンやネットワークは不要）。

GXP11

セキュリティ / 運用上の注意

• リポジトリに秘密情報はありません。Obsidian APIキーは .env（gitignore済み）にのみ存在します。

• カスタムサーバーは実行時にローカルデータのみを使用します（Stockfish + CSV + JSON）。

• Playwrightは公開ページに対して読み取り専用で使用。ログインもフォーム入力もありません。

• レート制限: エージェントは実行ごとにlichess.orgに対して約1回のページ読み込みを行います。データセットスクリプトはdatabase.lichess.orgから静的ファイルを1回ダウンロードします。