Sweepy MCP 工具参考
server.py 中的 MCP 服务器提供十二个工具。MCP 集成 页面介绍注册方法与常见流程。本页列出每个签名，便于你在助手运行前预判调用的行为。
响应载荷
每个工具在文本内容块中返回 JSON 字符串。成功载荷以 "status": "ok" 开头。失败载荷以 "status": "error" 开头，并包含说明原因的 message。扫描失败时还会报告 job_id 和 sweep_status: "failed"。
行为提示
Sweepy 为每个工具声明四个 MCP 注解。兼容的主机会在调用工具前读取这些提示。
| 提示 | 含义 |
|---|---|
readOnlyHint | 该调用不持久保存更改。 |
destructiveHint | 该调用可能覆盖或删除文件、配置文件或历史记录。 |
idempotentHint | 重复相同调用会达到相同的最终状态。 |
openWorldHint | 该调用会触及本机之外的资源。 |
| 工具 | 只读 | 破坏性 | 幂等 | 开放世界 |
|---|---|---|---|---|
create_profile | 否 | 是 | 是 | 否 |
run_sweep | 否 | 是 | 否 | 是 |
get_sweep_status | 否 | 否 | 是 | 否 |
get_jobs | 否 | 否 | 是 | 否 |
submit_judgments | 否 | 是 | 是 | 否 |
import_jobs | 否 | 是 | 是 | 是 |
render_report | 否 | 是 | 是 | 否 |
get_results | 是 | 否 | 是 | 否 |
export_report | 否 | 是 | 是 | 否 |
clear_history | 否 | 是 | 是 | 否 |
convert_document | 否 | 是 | 是 | 否 |
convert_docx | 否 | 是 | 是 | 否 |
配置文件与扫描工具
create_profile
校验每个已启用的引擎，然后写入配置文件 YAML。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | 必需 | 写入配置文件的姓名。 |
titles | string array | 必需 | 目标职位名称，例如 ["Technical Writer", "UX Writer"]。 |
location | string | 必需 | 目标地点，例如 "New York, NY"。 |
resume_path | string | 必需 | PDF 或 DOCX 简历的路径。 |
remote_only | boolean | false | 将结果限制为 100% 远程职位。 |
include_hybrid | boolean | true | 在结果中保留混合办公职位。 |
min_salary | integer | 0 | 最低年度基本薪资。零表示不设下限。 |
must_have_skills | string array | null | 提升匹配的技能词条。 |
synonyms | array of arrays | null | 可互换词条分组，例如 [["docs-as-code", "documentation as code"]]。 |
platforms | object | null | 合并到配置文件 platforms 区块的平台开关。 |
sources_config | object | null | 合并到 sources 区块的引擎选择。写入前会校验每个引擎。 |
cache_config | object | null | 缓存设置：enabled 和 ttl_seconds。 |
orchestrator_config | object | null | 超时与断路器设置。 |
history_config | object | null | 控制扫描跳过哪些职位的跨运行设置。 |
job_tracking | boolean | true | 在 CSV 中加入求职跟踪列，并延续此前的取值。 |
assessment | string | "agent" | 报告门控。agent 在任何卡片仅有关键词重合度时阻止生成报告。keyword 允许仅含关键词的报告。 |
output_filename | string | null | 自定义 YAML 路径。默认为 profiles/{name}_{title}.yaml。Sweepy 会把两部分转为小写，并把每个非字母数字字符替换为 _。 |
orchestrator_config 接受 timeout_per_source_seconds，以及包含 failure_threshold 和 cooldown_seconds 的 circuit_breaker 对象。
history_config 接受 enabled、retention_days、match 和 path。retention_days 默认为 4，match 接受 url 或 url+role，path 默认为 ~/.sweepy/history.db。
返回 profile_path、enabled_engines 和 engines_not_enabled。
run_sweep
启动五阶段流水线并返回确定性的关键词重合度分数。它不调用 LLM 评估。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
profile_path | string | null | 配置文件 YAML 的路径。省略时，Sweepy 使用最近保存的配置文件，然后使用磁盘上第一个常规配置文件：profiles/custom_profile.yaml、profiles/paralegal_nyc.yaml 或 config.sample.yaml。 |
deduplicate | boolean | true | 本次运行中合并重复 URL 以及来自不同网站的相同职位。 |
include_seen | boolean | false | 报告此前扫描过的职位并刷新其历史记录。 |
wait_seconds | integer | 45 | 返回进度前的最长阻塞等待时间。限制在 0 到 600 之间。 |
实际扫描常常超过客户端超时时间。流水线通过后台线程运行来应对这一间隔。返回 sweep_status: "running" 的调用会带上 job_id。把该 ID 传给 get_sweep_status，直到状态显示 completed。
使用相同配置文件和参数的第二次调用会挂接正在运行的作业，而不是再启动一个。服务器进程必须保持运行。扫描作业 ID 保存在内存中，重启后清除。
返回三种载荷之一：
- 运行中：
sweep_status、job_id、含step、total和label的progress，以及elapsed_seconds、debug_log和message。 - 已完成：
sweep_status、job_id、discovered_count、new_count、previously_seen_count、active_count、top_match、top_roles、reports、job_ids、card_count、assessed_count、assessment_mode、assessment_required、skipped_sources、elapsed_seconds、debug_log和message。top_roles保存前五个职位。 - 失败：
status: "error"、message、job_id和sweep_status: "failed"。
配置文件路径缺失或无法读取时，会在作业启动前失败。该错误不含 job_id。
当发现的职位全部为重复项时，previously_seen_count 报告总数，active_count 为零。把 include_seen 设为 true 调用 run_sweep 即可查看这些职位。
get_sweep_status
等待 run_sweep 启动的扫描并报告其进度。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
job_id | string | null | 来自 run_sweep 的扫描 ID。默认为最近的作业。 |
wait_seconds | integer | 45 | 返回进度前的最长阻塞等待时间。限制在 0 到 600 之间。 |
每次响应返回与对应 run_sweep 结果相同的字段。job_id 缺失或未知时，返回指向 run_sweep 的错误。
扫描结束后，卡片也会载入实时会话，因此状态显示 completed 后，get_jobs、submit_judgments 和 render_report 即可使用。
get_jobs
返回当前会话中的卡片记录，按关键词重合度或已提交的匹配分数排序。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
profile_stem | string | null | 用于加载已保存会话的配置文件标识，例如 pedro_writer。 |
results_dir | string | "results" | 存放 report_session.json 的文件夹。 |
limit | integer | null | 返回的卡片数量。省略则返回全部卡片。Sweepy 强制最小值为一。 |
返回 count 和 jobs。扫描运行期间，载荷会附加 sweep_status、running_job_id、progress，以及提示卡片早于该次扫描的 message。
submit_judgments
把助手的评估合并到单张卡片或整批卡片。只有非空字段会改变。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
job_id | string | null | 来自 run_sweep 或 get_jobs 的稳定卡片 ID。除非传入 judgments，否则必需。 |
match_pct | integer | null | 0 到 100 的匹配度。提供后卡片标签变为 MATCH。 |
resume_track | string | null | 在卡片上显示的简历轨道。 |
resume_color | string | null | 该轨道的徽标颜色。 |
domain | string | null | 卡片上显示的职位领域。 |
summary | string | null | 卡片摘要文本。 |
requirements | string | null | 任职要求文本。 |
alignment | string | null | 把简历证据与职位联系起来的说明。 |
has_extended_response | boolean | null | 标记需要书面应答的职位。 |
app_format | string | null | 申请格式，例如门户网站或电子邮件。 |
comp | string | null | 薪资行。 |
benefits | string | null | 福利行。 |
page_theme | string | null | 卡片主题覆盖值。 |
judgments | array | null | 评估对象列表，每项包含 job_id 以及上述任一字段。不要与 job_id 同时使用。 |
把合并后的卡片作为 job 返回。批量调用返回 applied、jobs 和 rejected，其中 rejected 列出会话中找不到对应 ID 的条目。
import_jobs
添加独立调研发现并核实过的职位。Sweepy 默认不会再次确认。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
jobs_json | string | 必需 | 卡片记录的 JSON 数组。 |
validate | boolean | false | 导入前用链接检查器逐个处理 URL。 |
返回 imported 和 skipped。限流或机器人防护响应按未验证处理，不能证明职位已失效。
render_report
由当前会话渲染卡片 PDF。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
profile_stem | string | null | 用于加载已保存会话的配置文件标识。 |
results_dir | string | "results" | 默认输出和已保存会话所在的文件夹。 |
output_filename | string | null | 明确的 PDF 路径。必须位于工作区内。 |
playbook | string | "" | 纯文本策略说明。Sweepy 会转义 & 和尖括号，并把 **bold** 渲染为粗体。换行转为行分隔。Sweepy 将该文本随会话保存，因此后续不带该参数的调用会复用已保存文本。取值为空且没有已保存文本时，生成确定性的策略指南。 |
返回 pdf_report、pages、card_count 和 playbook_saved。
配置文件默认为 report.assessment: "agent"，只要有任何卡片仅有关键词重合度，就会阻止渲染。错误信息列出 unassessed_job_ids 和 unassessed_titles，便于助手知道需要评估哪些卡片。设置 report.assessment: "keyword" 可允许混合报告，或设置 SWEEPY_REQUIRE_JUDGMENTS=1 把该门控应用到所有配置文件和 export_report。
结果与历史工具
get_results
从磁盘读取最新的扫描 JSON。它从不重新执行发现或评分。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
profile_stem | string | null | 用于筛选结果文件的配置文件标识。省略则读取最新的结果文件。 |
results_dir | string | "results" | 存放结果文件的文件夹。 |
limit | integer | 10 | 返回的头部职位数量。限制在 1 到 100 之间。 |
返回 result_file、pdf_report、csv_report、total_roles 和 top_roles。每个职位包含 title、company、location、match_score、match_kind、resume_track、domain、url 和 playbook。
标记为 KEYWORD OVERLAP 的分数是确定性的初筛值。把它们作为匹配结果呈现之前，请先使用 get_jobs 和 submit_judgments。
export_report
从已有的扫描 JSON 重建报告文件。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
json_source | string | null | 扫描 JSON 的路径。优先于 profile_stem。 |
profile_stem | string | null | 用于查找最新匹配 JSON 的配置文件标识。 |
results_dir | string | "results" | 存放结果文件的文件夹。 |
formats | string array | ["pdf"] | 输出格式：pdf、png、csv 或 json。 |
candidate_name | string | "Job Seeker" | PDF 页眉中的姓名。 |
output_dir | string | null | 输出文件夹。默认为包含源 JSON 的文件夹。 |
job_tracking | boolean | null | 在 CSV 导出中加入求职跟踪列。留空则遵循配置文件的 export.tracking 设置。 |
返回 source_file、roles_exported、generated 和 errors。请求包含相应格式时，generated 对象保存 pdf、pdf_pages、png、csv、csv_rows 和 json。请求 PNG 时会先渲染 PDF。JSON 输出写入 {stem}_export.json，因此绝不会覆盖作为其输入的扫描文件。
clear_history
清除已报告的职位记录，使下次扫描可以再次报告它们。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
profile_path | string | null | 配置文件 YAML 的路径。 |
profile_stem | string | null | 配置文件标识，例如 pedro_writer。 |
返回 scope、cleared 和 remaining。历史记录按配置文件区分。扫描后不带任何参数调用该工具，可清除该次扫描所用配置文件的记录。该回退方式从运行中的服务器读取状态，因此重启后请传入 profile_path 或 profile_stem。
文档转换工具
convert_document
将 .docx、.doc、.txt、.md 或 .pdf 转换为 PDF。PDF 源文件原样传递。旧版 .doc 文件需要 Microsoft Word。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
document_path | string | 必需 | 待转换文件的路径。 |
pdf_path | string | null | 输出路径。默认为源文件所在文件夹。 |
返回 pdf_path 和 source_path。
convert_docx
用 python-docx 和 reportlab 将 DOCX 简历转换为 PDF。有 Microsoft Word 可用时，回退到 docx2pdf。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
docx_path | string | 必需 | .docx 文件的路径。 |
pdf_path | string | null | 输出路径。默认为 DOCX 所在文件夹。 |
返回 pdf_path。
写入路径
写入类工具把输出限制在 Sweepy 文件夹内。在把 SWEEPY_ALLOW_EXTERNAL_WRITES 设为 1 之前，指向该文件夹之外的目标会失败。读取类工具可访问进程能够打开的任何路径。