Sweepy MCP ツールリファレンス

server.py の MCP サーバーは 12 のツールを公開します。MCP 連携のページで登録と一般的な流れを説明しています。このページはすべてのシグネチャを一覧するため、アシスタントが実行する前に呼び出しの動作を予測できます。

応答のペイロード

各ツールは、テキストのコンテンツブロックの中に JSON 文字列を返します。成功のペイロードは "status": "ok" で始まります。失敗のペイロードは "status": "error" で始まり、原因を説明する message を含みます。失敗したスイープは job_id と sweep_status: "failed" も報告します。

動作のヒント

Sweepy はすべてのツールに 4 つの 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	年収の下限です。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

5 段階のパイプラインを開始し、決定的なキーワードの重複のスコアを返します。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 が含まれます。ステータスが completed になるまで、その id を get_sweep_status に渡します。

同じプロファイルと同じフラグでの 2 回目の呼び出しは、別のジョブを開始せずに実行中のジョブに接続します。サーバーのプロセスは動き続ける必要があります。スイープのジョブ ID はメモリに置かれるため、再起動すると消えます。

3 つのペイロードのいずれかを返します。

• 実行中: 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 は最初の 5 件の求人を保持します。
• 失敗: status: "error"、message、job_id、sweep_status: "failed" です。

プロファイルのパスがない場合や読み取れない場合は、ジョブが始まる前に失敗します。そのエラーに job_id はありません。

検出した求人がすべて再掲載の場合は、previously_seen_count が総数を報告し、active_count は 0 を報告します。それらを確認するには、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 は最小 1 を適用します。

count と jobs を返します。スイープの実行中は、ペイロードに sweep_status、running_job_id、progress、およびカードがそのスイープより前のものだと警告する message が加わります。

submit_judgments

アシスタントの評価を 1 枚のカードまたは一括で統合します。null でないフィールドだけが変わります。

パラメーター	型	既定値	説明
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" を設定するか、すべてのプロファイルと export_report に条件を適用するには SWEEPY_REQUIRE_JUDGMENTS=1 を設定します。

結果と履歴のツール

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 と表示されたスコアは、決定的な 1 次評価の値です。マッチとして提示する前に 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 に設定するまで失敗します。読み取りは、プロセスが開けるパスならどこでも受け付けます。