MCPベースの採用マッチングシステム

Milestone-1のファイルシステムツールを実際のMCP（Model Context Protocol）サーバーに変換し、LangGraphマッチングエージェントを、ローカルのPython関数を直接呼び出すのではなく、クライアントとして（2つ目のMCPサーバーも含めて）利用するようにリファクタリングします。

プロジェクト構成

mcp_recruitment_project/
├── mcp_servers/
│   ├── filesystem_mcp_server.py   # Part A — main deliverable
│   └── rag_mcp_server.py          # Part B.2 bonus — 2nd MCP server
├── matching_agent.py              # Part B — refactored LangGraph agent
├── state.py                       # LangGraph agent state schema
├── data/
│   ├── resumes/                   # cand_001.txt ... cand_005.txt
│   └── job_descriptions/          # sample_jd.txt
├── reports/                       # generate_report() output lands here
├── docs/
│   └── workflow_diagram.md        # state machine / sequence diagrams
├── tests/
│   └── test_scenarios.py          # 7 automated test scenarios
└── requirements.txt

Related MCP server: File Server MCP

パートA — filesystem_mcp_server.py

• Anthropic公式のmcp Python SDK上に構築 — 手作りのプロトコルではなく、stdio上の本格的なJSON-RPC 2.0サーバーです。

• Milestone-1の操作をMCPツールとして公開します：list_resumes、read_resume、read_job_description、save_report。

• 履歴書/JDをMCPリソース（resources/list、resources/read）として公開し、resume://<file>およびjd://<file> URIを使用するため、どのMCPクライアントでもツール名を知らなくてもプールを閲覧できます。

• 新しいMCP固有の機能：

  • watch_directory(seconds, target) — フォルダを最大120秒間ポーリングし、出現したファイルを報告します。新しくアップロードされた履歴書を検出するためです。

  • batch_process(candidate_ids, operation) — ファイルごとに1回呼び出すのではなく、最大50ファイルに対してread / word_count / validateを1回のラウンドトリップで実行し、耐障害性を維持します（ファイルごとのエラーはバッチ全体を失敗させる代わりにerrors{}マップに収集されます）。

• エラー処理は、明確なJSON-RPCエラーコード（ERR_NOT_FOUND、ERR_INVALID_PARAMS、ERR_FORBIDDEN、ERR_BATCH_TOO_LARGE、およびSDK独自の-32603内部エラーフォールバック）を使用します — docs/workflow_diagram.md §5を参照してください。

• ServerConfigデータクラスは、ディレクトリ、許可された拡張子、バッチ制限、ウォッチタイミングを一元管理します。すべてのパスはFS_MCP_RESUME_DIR / FS_MCP_JD_DIR / FS_MCP_REPORT_DIR環境変数で上書きでき、すべてのファイルアクセスはパストラバーサルに対して_safe_join()でサンドボックス化されます。

ハンドラーを直接スモークテストします（クライアントは不要）：

python mcp_servers/filesystem_mcp_server.py --selftest

パートB — matching_agent.py

• 直接のos.listdir/open()呼び出しはすべてなくなりました。起動時にエージェントは2つのMCPサーバーを指すMultiServerMCPClientを作成し、実行時にツールを発見します — ツールはハードインポートされません。

• 各LangGraphノードはローカル関数の代わりにMCPツールを呼び出します：

• ボーナス マルチMCP: search_resumesとファイルシステム関連のすべては、2つの独立したstdioサーバープロセス/セッションから提供され、エージェントが単一のMCPサーバーに縛られていないことを証明します。

• ANTHROPIC_API_KEYが設定されていない場合、extract_requirementsは正規表現ベースのJDパーサーにフォールバックするため、ネットワークアクセスなしでもパイプライン全体がエンドツーエンドで実行されます（採点/CIに便利です）。

実行：

export ANTHROPIC_API_KEY=sk-...   # optional; heuristic fallback works without it
python matching_agent.py --jd sample_jd.txt

図

docs/workflow_diagram.mdを参照：

1. システムアーキテクチャ（エージェント + 2つのMCPサーバー）

2. エージェント状態機械

3. batch_processのJSON-RPC 2.0シーケンス図

4. エラーパスシーケンス図

5. エラーコード参照表

テスト

tests/test_scenarios.py — 7つのシナリオ、直接またはpytest経由で実行：

python tests/test_scenarios.py
# or
python -m pytest tests/test_scenarios.py -v

1. test_discovery — JSON-RPCハンドシェイク + tools/list + resources/list

2. test_resource_read — resume://cand_001.txtに対するresources/read

3. test_error_handling_not_found — 存在しない履歴書を読むと、適切なisError=true JSON-RPC結果が返されます

4. test_error_handling_invalid_batch — 空のcandidate_idsが拒否されます

5. test_batch_process_efficiency — すべての履歴書が1回の呼び出しで処理されます

6. test_watch_directory_detects_new_file — 監視中に作成されたファイルが検出され報告されます

7. test_multi_mcp_via_agent — 両方のMCPサーバーからツールを取得する完全なLangGraph実行で、保存されたレポートを生成します

現在、この環境では7つすべてが成功しています。

セットアップ

pip install -r requirements.txt

デモビデオ

この環境では実際のビデオファイルを録画またはレンダリングできません。上記のtests/test_scenarios.pyの実行とmatching_agent.pyの実行が、キャプチャする正確なシーケンスです — 5〜6分の提出ビデオのために、python tests/test_scenarios.py、続いてpython matching_agent.py --jd sample_jd.txtを、例えばOBS、QuickTime、Loomなどで画面録画してください。推奨ナレーションの流れ：(1) filesystem_mcp_server.py --selftestを表示、(2) 生のstdio JSON-RPCラウンドトリップを表示、(3) docs/workflow_diagram.mdを順に説明、(4) matching_agent.pyを実行し、推論ログ内の各MCP呼び出しをナレーション、(5) 生成されたreports/match_report.mdを開く。