跳到主要内容

通过 MCP 从 AI 助手运行 Sweepy

AI 助手可以替你运行 Sweepy。你描述想要的职位，助手便代你调用 Sweepy，无需你输入终端命令。

该连接使用模型上下文协议（MCP）。MCP 是一种共享语言，让 AI 助手使用你电脑上安装的工具。Sweepy 在 server.py 中内置 MCP 服务器。它通过 stdio 传输运行，因此只在本地与客户端通信，不开放网络端口。

备注

MCP 是可选的。Sweepy 无需任何 AI 助手，仅靠终端命令即可完整运行。服务器在同一引擎之上增加对话层，并为 Sweepy 已有的确定性评分和过滤加上模型的判断与理解能力。

连接前的准备​

  • 完成安装，确保 Python 和 Sweepy 的依赖已就位。mcp 和 anyio 包随 requirements.txt 一起安装。
  • 记下 server.py 的绝对路径。你需要把该路径粘贴到客户端配置中。
  • 更改 MCP 配置后，请重启 AI 客户端。

可用工具​

Sweepy 向助手提供十二个工具。每个工具返回 JSON 载荷，并声明只读、破坏性、幂等和开放世界等提示。

工具作用
create_profile根据 PDF 或 DOCX 简历构建、校验并保存 YAML 配置文件。
run_sweep在后台运行五阶段流水线并保存确定性卡片。
get_sweep_status等待正在运行的扫描并报告进度。
get_jobs返回当前会话中的卡片，按分数排序。
submit_judgments用助手的评估替换卡片的确定性字段。
import_jobs追加助手在其他位置核实过的职位。
render_report由当前会话渲染卡片 PDF。
get_results从磁盘读取最近的扫描结果。
export_report基于已有的扫描重建 PDF、PNG、CSV 或 JSON 文件。
clear_history清除某个配置文件已报告的职位记录。
convert_document将受支持的文档转换为 PDF。
convert_docx将 DOCX 简历转换为 PDF。

MCP 工具参考 提供更多细节，列出每个参数、默认值、载荷和行为提示。

选择职位搜索引擎​

省略 sources_config 时，create_profile 启用内置的 JobSpy 和 ATS 引擎。它还会启用已正确安装且默认值有效的可选引擎。该工具返回 enabled_engines 和 engines_not_enabled，便于你了解哪些引擎会运行、哪些仍需设置。

OpenRoles 只搜索你列出的公司招聘网站。启用前请添加公司标识。Apify 可能产生费用，是否启用由你决定。Sweepy 不会自动安装可选包。你无需为每次搜索都选择引擎。只有当某个引擎需要设置、付费服务授权或搜索约束时，才需显式选择。

显式选择引擎时请传入 sources_config。Sweepy 会保留该选择，不再添加其他引擎。以下 JSON 选择两个引擎：

{
  "enabled": ["jobspy", "openroles"],
  "openroles": {"companies": ["figma", "stripe"]}
}

一次性与混合工具流程​

Sweepy 有两种运行模式。请按你希望助手参与决策的程度选择。

一次性流程。 助手完成全部配置与运行，引擎按简历关键词重合度为每个职位评分。

create_profile -> run_sweep -> get_results -> export_report (optional)

混合有状态流程。 助手在报告渲染前逐张查看卡片并给出自己的评估。

run_sweep -> get_jobs -> submit_judgments -> render_report

客户端超时后，正在进行的扫描仍可继续。当 run_sweep 返回 sweep_status: "running" 时，用返回的 job_id 反复调用 get_sweep_status，直到状态为 completed。随后继续调用 get_jobs。

提示

生成可用的报告并不需要 LLM。仅靠 run_sweep 工具即可用确定性字段渲染完整的卡片 PDF，与终端扫描完全一致。

每张卡片显示两种分数标签之一：

  • NN% KEYWORD OVERLAP 来自确定性引擎，用于比对简历文本与每个职位。
  • NN% MATCH 来自你的助手。当你用 match_pct 值调用 submit_judgments 时出现。

核实并补充扫描结果​

把每次扫描结果当作候选集，再逐条对照职位核实。run_sweep 之后检查 skipped_sources 并报告源失败。用 get_jobs 查看职位，助手提交 LLM 评估前，先将每个职位与你的简历和明确偏好比对。

当助手具备网页或搜索工具时，让它到雇主招聘页或其 ATS 核实有希望的职位。它还可以搜索 Sweepy 遗漏的相关职位，通过 import_jobs 添加已核实且未重复的职位，并用 render_report 把这些职位纳入报告。助手不得编造职位，也不得凭猜测填补缺失的职位信息。

当主机屏蔽访问、限制请求速率或超时时，Sweepy 的 URL 检查器会把部分 URL 保留为未验证。403 或 429 并不能证明职位已失效。条件允许时，到可访问的雇主来源确认该职位，否则按未验证处理。若助手没有搜索工具，或来源仍不可访问，请说明结果可能不完整。出错后不要用未更改的设置重复扫描。

连接 Antigravity 或 Claude Desktop​

把 Sweepy 加入客户端的 MCP 配置文件。文件名依客户端而定，为 mcp_config.json 或 claude_desktop_config.json：

mcp_config.json
{
  "mcpServers": {
    "sweepy": {
      "command": "python",
      "args": [
        "/path/to/sweepy/server.py"
      ]
    }
  }
}

将 /path/to/sweepy 替换为 Sweepy 文件夹的绝对路径，然后重启客户端。注册完成后，你可以这样提出任务：

  • "为 Alex 创建一个 Sweepy 配置文件，搜索纽约的远程技术文档工程师职位。简历位于 path/to/resume.pdf。"
  • "用 writer 配置文件运行扫描，并显示前 5 个匹配结果。"
  • "用最近一次 pedro_writer 扫描重新生成 PDF，并保存到桌面。"
  • "将 path/to/notes.md 转换为 PDF，保存在原文件旁。"
写入 Sweepy 文件夹之外的路径

默认情况下，所有写入工具都限制在 Sweepy 文件夹内。在把环境变量 SWEEPY_ALLOW_EXTERNAL_WRITES 设为 1 之前，保存到桌面的请求会失败。

连接 VS Code​

VS Code 无需额外扩展即可连接 MCP 服务器：

  1. 打开命令面板并运行 MCP: Add Server。
  2. 选择 Command (stdio)，把命令设为 python，并把 server.py 的绝对路径作为参数。
  3. 将服务器命名为 sweepy，然后选择配置的保存位置。
  4. 确认聊天面板中出现 Sweepy 工具，然后在那里调用它们。

如需工作区级文件，请在项目中添加 .vscode/mcp.json。VS Code 格式使用顶层的 servers 对象：

.vscode/mcp.json
{
  "servers": {
    "sweepy": {
      "type": "stdio",
      "command": "python",
      "args": [
        "/path/to/sweepy/server.py"
      ]
    }
  }
}

安装 /sweepy 技能​

Sweepy 为 Copilot CLI、Claude Code、Antigravity 以及其他能读取技能的命令行工具提供 /sweepy 技能。把随附文件夹复制到你的工具技能目录：

终端
cp -r skills/sweepy ~/.claude/skills/sweepy   # adjust to your tool's skills path

按上一节注册 MCP 服务器，然后重启你的工具。该技能记录三个核心流程：

  • 开始新的抓取： 先调用 create_profile，再调用 run_sweep。
  • 查看抓取结果： 用 get_results 获取排名靠前的匹配和策略指南，或用 get_jobs 获取完整卡片集。
  • 将结果导出为 CSV 文件： 用 formats=["csv"] 调用 export_report。

该技能还覆盖不支持 MCP 的命令行工具的替代方案：

终端
sweepy --setup                         # interactive profile wizard
sweepy --profile profiles/your_profile.yaml
sweepy --docx resume.docx              # convert a DOCX resume to PDF
sweepy --convert notes.md              # convert any supported document to PDF

用一条提示完成全部设置​

复制以下提示，粘贴到任意 AI 命令行会话或 IDE 聊天中：

在这台机器上设置 Sweepy。按顺序完成以下步骤：

1. 克隆或下载 Sweepy 仓库。
2. 在仓库根目录运行 `pip install -r requirements.txt`。
3. 在 MCP 配置中把 `server.py` 注册为 stdio 服务器。使用 `python` 命令，并让参数指向 `server.py`。
4. 将 `skills/sweepy` 文件夹复制到 CLI 的技能目录。

了解更多提示模式​

仓库的 AGENTS.md 记录了工具调用顺序、各工具的使用指导和提示模式。若需要比本页流程更深入的自动化，请阅读它。