Sistema de emparejamiento de reclutamiento basado en MCP

Convierte las herramientas de sistema de archivos del Hito 1 en un servidor MCP (Model Context Protocol) real y refactoriza el agente de emparejamiento LangGraph para consumirlo (más un segundo servidor MCP) como cliente, en lugar de llamar directamente a funciones locales de Python.

Estructura del proyecto

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

Parte A — filesystem_mcp_server.py

• Construido sobre el SDK oficial de Python mcp de Anthropic: un servidor JSON-RPC 2.0 real sobre stdio, no un protocolo hecho a mano.

• Expone las operaciones del Hito 1 como herramientas MCP: list_resumes, read_resume, read_job_description, save_report.

• Expone currículums/descripciones de trabajo como recursos MCP (resources/list, resources/read) con URIs resume://<file> y jd://<file>, para que cualquier cliente MCP pueda explorar el conjunto sin conocer los nombres de las herramientas.

• Nuevas capacidades específicas de MCP:

  • watch_directory(seconds, target) — sondea una carpeta durante hasta 120 s e informa de cualquier archivo que aparezca, para detectar currículums recién subidos.

  • batch_process(candidate_ids, operation) — ejecuta read / word_count / validate en hasta 50 archivos en una sola ida y vuelta en lugar de una llamada por archivo, y permanece resiliente (los errores por archivo se recogen en un mapa errors{} en lugar de fallar todo el lote).

• El manejo de errores utiliza códigos de error JSON-RPC distintos (ERR_NOT_FOUND, ERR_INVALID_PARAMS, ERR_FORBIDDEN, ERR_BATCH_TOO_LARGE, además del respaldo de error interno -32603 del propio SDK); consulte docs/workflow_diagram.md §5.

• La dataclass ServerConfig centraliza directorios, extensiones permitidas, límites de lote y temporización de vigilancia; cada ruta se puede sobrescribir mediante las variables de entorno FS_MCP_RESUME_DIR / FS_MCP_JD_DIR / FS_MCP_REPORT_DIR, y cada acceso a archivos está aislado con _safe_join() contra el recorrido de rutas.

Pruebe los manejadores directamente (sin necesidad de cliente):

python mcp_servers/filesystem_mcp_server.py --selftest

Parte B — matching_agent.py

• Todas las llamadas directas a os.listdir/open() han desaparecido. Al iniciarse, el agente crea un MultiServerMCPClient apuntando a dos servidores MCP y descubre sus herramientas en tiempo de ejecución; ninguna herramienta se importa de forma fija.

• Cada nodo de LangGraph llama a herramientas MCP en lugar de funciones locales:

• Bonus multi-MCP: search_resumes y todo lo relacionado con el sistema de archivos provienen de dos procesos/sesiones de servidor stdio independientes, lo que demuestra que el agente no está atado a un único servidor MCP.

• Si ANTHROPIC_API_KEY no está configurada, extract_requirements recurre a un analizador de descripciones de trabajo basado en expresiones regulares para que todo el flujo siga ejecutándose de extremo a extremo sin acceso a la red (útil para calificación/CI).

Ejecútelo:

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

Diagramas

Consulte docs/workflow_diagram.md para:

1. Arquitectura del sistema (agente + 2 servidores MCP)

2. Máquina de estados del agente

3. Diagrama de secuencia JSON-RPC 2.0 para batch_process

4. Diagrama de secuencia de la ruta de errores

5. Tabla de referencia de códigos de error

Pruebas

tests/test_scenarios.py — 7 escenarios, ejecutar directamente o mediante pytest:

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

1. test_discovery — protocolo de enlace JSON-RPC + tools/list + resources/list

2. test_resource_read — resources/read en resume://cand_001.txt

3. test_error_handling_not_found — leer un currículum inexistente devuelve un resultado JSON-RPC adecuado con isError=true

4. test_error_handling_invalid_batch — se rechaza candidate_ids vacío

5. test_batch_process_efficiency — todos los currículums procesados en 1 llamada

6. test_watch_directory_detects_new_file — se detecta e informa un archivo creado durante la vigilancia

7. test_multi_mcp_via_agent — ejecución completa de LangGraph que extrae herramientas de ambos servidores MCP y produce un informe guardado

Los 7 pasan actualmente en este entorno.

Configuración

pip install -r requirements.txt

Video de demostración

No puedo grabar ni renderizar un archivo de video real en este entorno. La ejecución de tests/test_scenarios.py y la ejecución de matching_agent.py anteriores son las secuencias exactas a capturar: grabe la pantalla de python tests/test_scenarios.py seguido de python matching_agent.py --jd sample_jd.txt con, por ejemplo, OBS, QuickTime o Loom para el video de entrega de 5 a 6 minutos. Sugerencias para la narración: (1) mostrar filesystem_mcp_server.py --selftest, (2) mostrar el intercambio JSON-RPC sin procesar por stdio, (3) recorrer docs/workflow_diagram.md, (4) ejecutar matching_agent.py y narrar cada llamada MCP en el registro de razonamiento, (5) abrir el informe generado reports/match_report.md.