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

Part 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) — 최대 50개 파일에 대해 read / word_count / validate를 파일당 한 번 호출하는 대신 한 번의 왕복으로 실행하며, 탄력적으로 동작 (파일별 오류는 전체 배치를 실패시키는 대신 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

Part B — matching_agent.py

• 모든 직접 os.listdir/open() 호출 제거. 시작 시 에이전트는 두 개의 MCP 서버를 가리키는 MultiServerMCPClient를 생성하고 런타임에 도구를 발견 — 하드 임포트된 도구 없음.

• 각 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

• 보너스 멀티-MCP: search_resumes와 파일시스템 관련 모든 것은 두 개의 독립적인 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 실행이 캡처할 정확한 시퀀스입니다 — 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) 원시 stdio JSON-RPC 왕복 표시, (3) docs/workflow_diagram.md 살펴보기, (4) matching_agent.py 실행 및 추론 로그의 각 MCP 호출 내레이션, (5) 생성된 reports/match_report.md 열기.