Система подбора кандидатов на основе MCP

Преобразует файловые инструменты из Milestone-1 в настоящий MCP-сервер (Model Context Protocol) и рефакторит агента сопоставления LangGraph, чтобы он использовал его (плюс второй MCP-сервер) в качестве клиента, вместо прямого вызова локальных функций Python.

Структура проекта

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

• Построен на официальном Python SDK mcp от Anthropic — настоящий JSON-RPC 2.0 сервер через stdio, а не самодельный протокол.

• Предоставляет операции Milestone-1 как MCP-инструменты: list_resumes, read_resume, read_job_description, save_report.

• Предоставляет резюме и описания вакансий как MCP-ресурсы (resources/list, resources/read) с URI resume://<file> и jd://<file>, чтобы любой MCP-клиент мог просматривать пул, не зная имён инструментов.

• Новые возможности, специфичные для MCP:

  • watch_directory(seconds, target) — опрашивает папку до 120 секунд и сообщает о появившихся файлах, чтобы обнаруживать только что загруженные резюме.

  • batch_process(candidate_ids, operation) — выполняет read / word_count / validate для до 50 файлов за один цикл вместо одного вызова на файл и остаётся устойчивым (ошибки по каждому файлу собираются в карту 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() удалены. При запуске агент создаёт MultiServerMCPClient, указывающий на два MCP-сервера, и обнаруживает их инструменты во время выполнения — ни один инструмент не импортируется жёстко.

• Каждый узел LangGraph вызывает MCP-инструменты вместо локальных функций:

  Узел	Используемый MCP-инструмент
  parse_jd	filesystem.list_resumes
  extract_requirements	(LLM или эвристический запасной вариант, если нет API-ключа)
  search_resumes	rag.search_resumes
  rank_candidates	filesystem.batch_process (1 вызов, а не N)
  generate_report	filesystem.save_report

• Бонус multi-MCP: search_resumes и всё, что связано с файловой системой, поступают из двух независимых процессов/сессий stdio-сервера, что доказывает: агент не привязан к одному MCP-серверу.

• Если ANTHROPIC_API_KEY не задан, extract_requirements использует запасной парсер описаний вакансий на основе регулярных выражений, так что весь конвейер по-прежнему работает от начала до конца без доступа к сети (полезно для оценки/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. Диаграмма последовательности JSON-RPC 2.0 для batch_process

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 — resources/read для resume://cand_001.txt

3. test_error_handling_not_found — чтение отсутствующего резюме возвращает корректный результат JSON-RPC с isError=true

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 — полный запуск LangGraph, извлекающий инструменты с обоих MCP-серверов и создающий сохранённый отчёт

Все 7 в настоящее время проходят в этом окружении.

Настройка

pip install -r requirements.txt

Демонстрационное видео

Я не могу записать или отрендерить реальный видеофайл в этом окружении. Запуск tests/test_scenarios.py и matching_agent.py выше — это точные последовательности для записи: запишите экран python tests/test_scenarios.py, а затем python matching_agent.py --jd sample_jd.txt с помощью, например, OBS, QuickTime или Loom для 5–6-минутного видео для сдачи. Предлагаемые моменты для озвучки: (1) покажите filesystem_mcp_server.py --selftest, (2) покажите необработанный цикл JSON-RPC через stdio, (3) пройдитесь по docs/workflow_diagram.md, (4) запустите matching_agent.py и прокомментируйте каждый вызов MCP в журнале рассуждений, (5) откройте сгенерированный reports/match_report.md.