resume-mcp-server

resume-mcp-server 是一个 MCP（Model Context Protocol）服务器，旨在为 Claude 或其他 MCP 客户端提供对本地简历文件集合的结构化、可搜索访问。求职者常积累大量文档：针对不同职位定制的多个简历版本、求职信草稿、推荐人信息等，手动查找和利用非常繁琐。将该服务器指向简历文件夹后，AI 就能直接回答问题，例如“我的哪份简历突出了 Kubernetes 经验？”、“我在后端职位中列出了哪些成就？”或“根据我在 Acme Corp 的工作起草一封求职信”，无需手动粘贴内容。

主要能力：

• 多格式解析：解析 .docx、.pdf、.md、.txt 文档为结构化数据，包括联系人信息、工作经历、教育背景、技能和副业项目。
• 自动去重：通过邮箱或姓名匹配同一人的多份简历（如同一份简历的 .docx 和 .pdf），合并为信息最丰富的副本，避免搜索和分析结果被重复项干扰。
• 自动热重载：文件系统监视器在文档更改时立即重新索引，无需重启服务器。
• 文档类型推断：根据文件名模式自动分类为 resume、cover_letter、application_material 或 other，可通过环境变量按类别覆盖。
• 全文与结构化搜索：使用 search_resumes 搜索整个文档，或通过带作用域的 query、technology 或 competency 参数过滤任意实体类型（技能、工作经历、成就、副业项目、教育）。
• 三种搜索模式：and、or 和 regex 匹配，在所有接受类似查询参数的工具中一致可用。
• 统一分页：所有列表式工具返回相同的 total_count / items / has_more / next_offset / message 封装，limit / offset 经过验证，上限为 200 条。
• 统一错误形状：所有失败返回 {"error": "..."}，调用方只需检查一种形状。
• 集合分析：get_collection_stats 和 get_skill_frequency 提供聚合计数和跨简历技能热度。
• ATS 风格职位匹配排名：list_ranked_resumes 根据粘贴的职位描述对每份简历评分（模糊技能匹配加关键词覆盖），并按最佳匹配优先排序；匹配严格度和分数权重可按调用调整。
• 只读且安全：所有工具标注 readOnlyHint / idempotentHint / openWorldHint: false，不会修改文件或访问本地文档集合之外。
• 灵活部署：支持 stdio 或 HTTP 运行，可独立运行或通过 Docker/Docker Compose 部署，支持 CORS，通过环境变量或 .env 文件配置。

使用方式： 快速尝试（使用内置示例简历）和连接 Claude Code 的命令在资料中给出。 Docker 部署（推荐）：

1. 设置简历目录：复制示例环境文件并设置文档路径。
2. 可选：同步镜像版本，用当前 pyproject.toml 版本标记镜像。
3. 构建并启动，服务器将在 http://localhost:8001/mcp 可用。
4. 连接 AI 客户端，如 Claude Desktop（macOS 上 ~/Library/Application Support/Claude/claude_desktop_config.json）、VS Code（.vscode/mcp.json），或全局添加到 ~/.claude.json。 也可直接运行镜像，无需 Compose，用于使用 stdio 传输的 MCP 客户端（包括 Glama.ai 和 Claude Desktop）。 开发环境： 本地运行或不用 Docker 运行服务器，可创建 .env 文件，然后运行 resume-mcp-server，.env 会自动加载。Shell 环境变量或 MCP 客户端设置的变量始终优先于 .env。 连接 AI 客户端（stdio）：Claude Desktop 配置中，若 resume-mcp-server 不在 PATH 中，使用完整路径（如 ~/.venv/bin/resume-mcp-server）。

配置：

• 每个 DOC_TYPE_PATTERN_* 变量替换该类别的默认正则（文件名按顺序匹配：resume、cover letter、application material，其余归为 other）。未设置则保留默认；无效正则被忽略并使用默认。
• 服务器启动时递归扫描 RESUME_DIR，文件更改时自动重新加载。
• 文档类型推断基于文件名，三种正则可通过 DOC_TYPE_PATTERN_RESUME、DOC_TYPE_PATTERN_COVER_LETTER、DOC_TYPE_PATTERN_APPLICATION_MATERIAL 覆盖。

搜索行为：

• 大多数接受 query（或 technology / competency）参数的工具按空白拆分，并通过可选 mode 参数支持 and、or、regex 三种匹配模式。
• 多字段注意：对于搜索多个字段（公司名、职位名称、成就文本等）的工具，AND 模式要求所有词出现在同一字段，而非跨字段。需要更宽松的跨字段匹配时使用 OR 模式。Regex 模式也按字段匹配。
• 单字查询在 and / or 模式下行为相同。
• search_resumes_by_skill 接受单个技能字符串或技能列表。对于列表，mode 兼作控制：要求简历匹配列表中每个技能（"and"）或任意技能（"or"）；"regex" 模式以 OR 语义组合多个技能。
• 空查询或空技能列表返回 {"error": "..."} 而非空结果，以区分调用错误和合法的零匹配搜索。
• 所有 list_* 工具（以及 search_resumes / search_resumes_by_skill）接受 limit 和 offset 参数，返回一致的封装：total_count 是切片前的完整匹配数；has_more 和 next_offset 直接指示是否继续分页；message 以自然语言重申。当没有更多时，has_more 为 false，next_offset 为 null，message 为 "All N results shown."。
• limit 必须大于 0，offset 必须为 0 或更大，否则返回 {"error": "..."}。offset 超出总结果数不是错误，而是有效的“超出末尾”分页（items: [], has_more: false）。
• 上限和默认值：limit 无论请求多少都会被静默限制为 200；如果请求更多，响应仍会返回（不是错误），但 message 前缀为 "Requested limit N capped to 200."。默认 limit 因工具而异，对于更重、深度嵌套的响应通常更低。

错误处理：

• 每个工具返回字典。失败时字典精确为 {"error": "<message>"}，这是 API 中唯一的失败形状，调用方只需检查 "error" 键。覆盖：未找到 ID、resume_id 过滤器不匹配任何简历、无效正则模式、无效 limit / offset 值。resume_id 过滤器匹配简历但子记录为零（例如 list_work_experiences(resume_id=<valid>) 对没有工作历史的人）不是错误，返回空 items 列表。
• get_resume 的成功形状为 {"text": "..."}，使成功和失败都是字典，可通过键区分。

工具： 共暴露 20 个工具，覆盖全文搜索、技能查找、公司和角色查询、成就挖掘、教育搜索、ATS 风格职位匹配排名、集合分析等。每个工具都是只读的（readOnlyHint: true），不会修改状态或访问本地文档集合之外（openWorldHint: false）。完整参数表和返回形状见 docs/TOOLS.md。

适用场景：

• 求职者管理多个简历版本和求职信，快速查找特定技能或成就。
• 根据职位描述自动排名简历。
• 分析技能频率和集合统计。
• 起草求职信时引用特定工作经历。

限制：

• 仅支持 .docx、.pdf、.md、.txt 格式。
• 依赖 MCP 客户端（如 Claude）连接使用。
• 其他未在资料中提及的限制暂未提供。