MCP で AI アシスタントから Sweepy を実行する

AI アシスタントに Sweepy を動かしてもらえます。希望の職種を伝えると、アシスタントがターミナルでのコマンド入力を求める代わりに、あなたに代わって Sweepy を呼び出します。

この接続には **Model Context Protocol（MCP）**を使います。MCP は、AI アシスタントがパソコンにインストールされたツールを使えるようにする共通の言葉です。Sweepy には server.py に MCP サーバーが組み込まれています。stdio トランスポートで動作するため、クライアントとローカルで通信し、ネットワークポートを開きません。

注記

MCP は任意です。Sweepy は AI アシスタントなしでもターミナルのコマンドだけで完全に動作します。サーバーは同じエンジンの上に対話の層を追加します。加えて、Sweepy がすでに行う決定的な採点と絞り込みに、モデルの判断と知性を加えます。

接続する前に

インストールを済ませ、Python と Sweepy の依存パッケージを用意します。mcp と anyio のパッケージは requirements.txt に含まれています。
server.py の絶対パスを控えます。このパスをクライアントの設定に貼り付けます。
MCP の設定を変えたら、AI クライアントを再起動します。

利用できるツール

Sweepy はアシスタントに 12 のツールを公開します。各ツールは JSON のペイロードを返し、読み取り専用、破壊的、冪等、外部世界に開かれた操作かどうかのヒントを宣言します。

ツール	動作
`create_profile`	PDF または DOCX の履歴書から YAML プロファイルを組み立て、検証し、保存します。
`run_sweep`	5 段階のパイプラインをバックグラウンドで実行し、決定的なカードを保存します。
`get_sweep_status`	実行中のスイープを待ち、進捗を報告します。
`get_jobs`	現在のセッションが保持するカードをスコア順で返します。
`submit_judgments`	カードの決定的な項目を、アシスタントの判定で置き換えます。
`import_jobs`	アシスタントが別の場所で検証した求人を追加します。
`render_report`	現在のセッションからカードの PDF を生成します。
`get_results`	直近のスイープ結果をディスクから読み取ります。
`export_report`	既存のスイープから PDF、PNG、CSV、JSON のファイルを組み直します。
`clear_history`	1 つのプロファイルの報告済み求人を忘れます。
`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 は 2 つのエンジンを選びます。

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

単発の流れとハイブリッドの流れ

Sweepy には 2 つの進め方があります。アシスタントにどこまで判断させるかに合わせて選んでください。

単発の流れ。 アシスタントがすべてを設定して実行し、エンジンが履歴書のキーワードの重複で各求人を採点します。

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 全体を生成します。

各カードには 2 つのスコアのラベルのどちらかが付きます。

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 にあります。」
「ライターのプロファイルでスイープを実行し、上位 5 件のマッチを見せて。」
「最後の pedro_writer のスイープから PDF を再生成して、デスクトップに保存して。」
「path/to/notes.md を元のファイルの隣に PDF として変換して。」

Sweepy フォルダーの外への書き込み

書き込みを行うすべてのツールは、既定で Sweepy フォルダーの中にとどまります。環境変数 SWEEPY_ALLOW_EXTERNAL_WRITES を 1 に設定するまで、デスクトップへの保存依頼は失敗します。

VS Code に接続する

VS Code は追加の拡張機能なしで MCP サーバーに接続します。

コマンドパレットを開き、MCP: Add Server を実行します。
Command (stdio) を選び、コマンドに python を入力します。引数に server.py の絶対パスを追加します。
サーバーの名前を sweepy にし、設定の保存先を選びます。
チャットパネルに 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 サーバーを登録し、ツールを再起動します。スキルは 3 つの中核の流れを説明します。

新しい取得を始めるには 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

1 つのプロンプトですべてを設定する

このプロンプトをコピーし、AI のコマンドラインセッションや IDE のチャットに貼り付けます。

このマシンに Sweepy を設定してください。次の手順を順に実行してください。

Sweepy のリポジトリを複製するかダウンロードします。
リポジトリのルートで `pip install -r requirements.txt` を実行します。
MCP の設定に `server.py` を stdio サーバーとして登録します。コマンドは `python`、引数は `server.py` を指すようにします。
`skills/sweepy` フォルダーを CLI のスキルディレクトリにコピーします。

さらにプロンプトのパターンを学ぶ

リポジトリの AGENTS.md は、ツールの順序、ツールごとの指針、プロンプトのパターンを説明しています。このページの流れより深い自動化が必要な場合は、そちらを読んでください。

接続する前に​

利用できるツール​

求人検索エンジンを選ぶ​

単発の流れとハイブリッドの流れ​

スイープの結果を検証して補う​

Antigravity または Claude Desktop に接続する​

VS Code に接続する​

/sweepy スキルをインストールする​

1 つのプロンプトですべてを設定する​

さらにプロンプトのパターンを学ぶ​