基于 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

• 基于 Anthropic 官方 mcp Python SDK 构建 — 一个通过 stdio 运行的真正的 JSON-RPC 2.0 服务器，而非手写协议。

• 将 Milestone-1 的操作暴露为 MCP 工具：list_resumes、read_resume、read_job_description、save_report。

• 将简历/职位描述暴露为 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

第 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 — 完整的 LangGraph 运行，从两个 MCP 服务器拉取工具，生成已保存的报告

目前所有 7 个测试在此环境中均通过。

设置

pip install -r requirements.txt

演示视频

我无法在此环境中录制或渲染实际的视频文件。上面的 tests/test_scenarios.py 运行和 matching_agent.py 运行正是需要录制的确切序列 — 使用例如 OBS、QuickTime 或 Loom 屏幕录制 python tests/test_scenarios.py，然后录制 python matching_agent.py --jd sample_jd.txt，用于 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。