MCP-basiertes Recruitment-Matching-System

Konvertiert die Dateisystem-Tools aus Meilenstein 1 in einen echten MCP-Server (Model Context Protocol) und refaktoriert den LangGraph-Matching-Agenten so, dass er diesen (plus einen zweiten MCP-Server) als Client konsumiert, anstatt lokale Python-Funktionen direkt aufzurufen.

Projektstruktur

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

Teil A — filesystem_mcp_server.py

• Basierend auf dem offiziellen mcp Python SDK von Anthropic – ein echter JSON-RPC-2.0-Server über stdio, kein handgebautes Protokoll.

• Stellt die Operationen aus Meilenstein 1 als MCP-Tools bereit: list_resumes, read_resume, read_job_description, save_report.

• Stellt Lebensläufe und Stellenbeschreibungen als MCP-Ressourcen bereit (resources/list, resources/read) mit resume://<file>- und jd://<file>-URIs, sodass jeder MCP-Client den Pool durchsuchen kann, ohne die Tool-Namen zu kennen.

• Neue MCP-spezifische Fähigkeiten:

  • watch_directory(seconds, target) – pollt einen Ordner bis zu 120 Sekunden lang und meldet alle neu erschienenen Dateien, um frisch hochgeladene Lebensläufe zu erkennen.

  • batch_process(candidate_ids, operation) – führt read / word_count / validate über bis zu 50 Dateien in einem Round Trip aus, statt eines Aufrufs pro Datei, und bleibt robust (Fehler pro Datei werden in einer errors{}-Map gesammelt, statt den gesamten Batch fehlschlagen zu lassen).

• Fehlerbehandlung verwendet eindeutige JSON-RPC-Fehlercodes (ERR_NOT_FOUND, ERR_INVALID_PARAMS, ERR_FORBIDDEN, ERR_BATCH_TOO_LARGE sowie den eigenen -32603-Internal-Error-Fallback des SDKs) – siehe docs/workflow_diagram.md §5.

• Die ServerConfig-Dataclass zentralisiert Verzeichnisse, erlaubte Erweiterungen, Batch-Limits und Watch-Timing; jeder Pfad ist über die Umgebungsvariablen FS_MCP_RESUME_DIR / FS_MCP_JD_DIR / FS_MCP_REPORT_DIR überschreibbar, und jeder Dateizugriff wird mit _safe_join() gegen Path Traversal abgesichert.

Smoke-Test der Handler direkt (kein Client nötig):

python mcp_servers/filesystem_mcp_server.py --selftest

Teil B — matching_agent.py

• Alle direkten os.listdir/open()-Aufrufe sind entfernt. Beim Start erstellt der Agent einen MultiServerMCPClient, der auf zwei MCP-Server zeigt, und entdeckt deren Tools zur Laufzeit – kein Tool wird hart importiert.

• Jeder LangGraph-Knoten ruft MCP-Tools auf, statt lokale Funktionen zu verwenden:

  Knoten	Verwendetes MCP-Tool
  parse_jd	filesystem.list_resumes
  extract_requirements	(LLM oder heuristischer Fallback ohne API-Key)
  search_resumes	rag.search_resumes
  rank_candidates	filesystem.batch_process (1 Aufruf, nicht N)
  generate_report	filesystem.save_report

• Bonus Multi-MCP: search_resumes und alles Dateisystembezogene stammen aus zwei unabhängigen stdio-Serverprozessen/-Sessions, was beweist, dass der Agent nicht an einen einzelnen MCP-Server gebunden ist.

• Wenn ANTHROPIC_API_KEY nicht gesetzt ist, fällt extract_requirements auf einen regexbasierten JD-Parser zurück, sodass die gesamte Pipeline ohne Netzwerkzugriff Ende-zu-Ende läuft (nützlich für Bewertung/CI).

Ausführen:

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

Diagramme

Siehe docs/workflow_diagram.md für:

1. Systemarchitektur (Agent + 2 MCP-Server)

2. Agent-Zustandsmaschine

3. JSON-RPC-2.0-Sequenzdiagramm für batch_process

4. Fehlerpfad-Sequenzdiagramm

5. Fehlercode-Referenztabelle

Tests

tests/test_scenarios.py – 7 Szenarien, direkt oder über pytest ausführbar:

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

1. test_discovery – JSON-RPC-Handshake + tools/list + resources/list

2. test_resource_read – resources/read auf resume://cand_001.txt

3. test_error_handling_not_found – Lesen eines fehlenden Lebenslaufs liefert ein korrektes isError=true-JSON-RPC-Ergebnis

4. test_error_handling_invalid_batch – leere candidate_ids werden abgelehnt

5. test_batch_process_efficiency – alle Lebensläufe werden in 1 Aufruf verarbeitet

6. test_watch_directory_detects_new_file – eine während des Watch erstellte Datei wird erkannt und gemeldet

7. test_multi_mcp_via_agent – vollständiger LangGraph-Lauf, der Tools von beiden MCP-Servern bezieht und einen gespeicherten Bericht erzeugt

Alle 7 bestehen derzeit in dieser Umgebung.

Setup

pip install -r requirements.txt

Demo-Video

Ich kann in dieser Umgebung keine echte Videodatei aufnehmen oder rendern. Der Lauf von tests/test_scenarios.py und der Lauf von matching_agent.py oben sind die exakten Sequenzen, die aufgenommen werden sollen – Bildschirmaufnahme von python tests/test_scenarios.py gefolgt von python matching_agent.py --jd sample_jd.txt mit z. B. OBS, QuickTime oder Loom für das 5–6-minütige Einreichungsvideo. Vorgeschlagene Erzählabschnitte: (1) filesystem_mcp_server.py --selftest zeigen, (2) den rohen stdio-JSON-RPC-Round-Trip zeigen, (3) docs/workflow_diagram.md durchgehen, (4) matching_agent.py ausführen und jeden MCP-Aufruf im Reasoning-Log kommentieren, (5) den generierten reports/match_report.md öffnen.