jobhunt

jobhunt

jobhunt は、企業の採用サイトから求人情報と企業プロフィールを収集するホスト型 Jobven MCP サーバーへの、小規模なローカルブリッジです。これを通じて、職種名や 説明文のフレーズ、リモート勤務の種類、経験レベル、雇用形態、スキル、業界、言語、勤務地、 給与範囲、ビザスポンサーの有無、掲載日など、幅広い条件で求人を検索できます。また、 個別の求人情報を選んで全文を読む、企業名で検索する、特定の企業プロフィールを開く、 受信側をテストするためのサンプル Webhook 配信を取得するといったこともできます。

このパッケージ自体は何も検索しません。ライブエンドポイントから取得した内容そのままの ツール一覧をローカルで返し、各ツール呼び出しを上流に転送して、返された内容を変更せずに 返します。取得した説明によると、検索で返される求人、および個別の求人や企業の検索は、 ご自身の Jobven アカウントの月間利用枠にカウントされます。一方、企業検索は無料です。 このパッケージでは、以下の 5 つの呼び出しと、何も送信せず実際の署名も行わないサンプル Webhook の例を通じた読み取りのみが可能です。求人への応募、応募書類の送信、メッセージの送信、 チェックアウトの開始、キーの生成はできません。

ツール

• search_jobs — Jobven の求人情報を、GET /v1/public/jobs の フィルターを使って検索します。デフォルトで求人情報を 10 件（最大 25 件）返し、 各説明のプレーンテキストの抜粋も含まれます。全文は get_job で取得できます。 次のページを取得するには、同じフィルターを指定して nextCursor を cursor として 渡します。返された求人情報は、それぞれ月間利用枠にカウントされます。すべての引数は オプションです。q（タイトルの単語。順不同の AND 検索、完全一致のフレーズは "double quotes" で指定、OR でいずれかを指定、先頭の - で除外。 大文字と小文字は区別されません。説明文は検索しません）、descriptionQuery （説明文中の単語全体に一致するフレーズ。文字列どおりに一致し、大文字と小文字は 区別されません。処理が遅いため、postedAfter との併用を推奨します）、 remoteType（onsite、remote、hybrid、 flexible）、experienceLevel（entry、mid、 senior、lead、executive）、employmentType （full_time、part_time、contract、internship、 seasonal、volunteer、temporary、per_diem、 other）、skills、industry、language（ISO 639-1 コード）、location、country（ISO 3166-1 alpha-2。XX は勤務地が指定されていない求人に一致します）、 state、city、minSalary、maxSalary、 salaryCurrency（ISO 4217 コード）、hasVisaSponsorship、 hasRelocation、status（active がデフォルト、または closed）、postedAfter、postedBefore、 listedAfter（Unix 秒）、sortBy（postedAt、 listedAt、title、company）、order（ASC または DESC。デフォルトは DESC）、includeTotal、cursor、 limit（1～25。デフォルトは 10）。
• get_job — id で Jobven の求人情報を 1 件取得し、説明文の全文を返します （GET /v1/public/jobs/{id}）。必須：id（search_jobs で取得した 求人 ID。UUID 形式）。オプション：descriptionFormat（plain が デフォルト、または markdown）。月間利用枠に求人情報 1 件として カウントされます。
• search_companies — Jobven が求人情報を収集している雇用主を、名前で検索します （GET /v1/public/companies）。id、name、website を返します。 プロフィールは get_company で取得できます。無料：企業検索は利用枠に カウントされません。すべての引数はオプションです。search（名前にこの文字列を 含む）、status（active または inactive。未指定の場合は両方）、 isVerified、sortBy（name、foundedYear、 totalJobsPosted、activeJobsCount、createdAt）、 sortOrder（ASC または DESC）、page（1 から開始）、 limit（1～25。デフォルトは 10）。
• get_company — id で雇用主 1 社のプロフィールを取得します （GET /v1/public/company-profiles/{id}）。事業内容、業界、規模、 設立年、本社、ソーシャルリンクが含まれます。必須：id （search_companies で取得した企業 ID）。月間利用枠に 1 件として カウントされます。
• webhook_example — 1 つのイベントに対する Jobven webhook 配信のサンプルです。 受信側が受け取るものとまったく同じ、生のボディとヘッダーを、サンプルシークレットで 署名したものと、Webhook ドキュメントにある署名検証コードを TypeScript、Python、 または Go で返します。検証コードはサンプルを受け入れるため、受信側をエンドツーエンドで テストできます。API 呼び出し不要、キー不要、無料です。必須：event （job.created、job.updated、job.closed、 job.deleted）および language（typescript、 python、go）。

設定

• JOBVEN_MCP_URL（オプション）— 上流エンドポイントを上書きします。デフォルトは https://api.jobven.com/mcp です。 （この上書きフックは、この再構築で独自に明記したものです。）
• JOBVEN_API_KEY（オプション）— 設定すると、呼び出し元自身の Jobven API キーを X-API-Key: <value> ヘッダーに含めて、すべての上流リクエストを送信します。未設定の 場合、キーのヘッダーは送信されません。（ヘッダー名は、必須のシークレット X-API-Key ヘッダーを宣言する元のレジストリ記録によって固定されています。この記録では パッケージの環境変数名は指定されていないため、この環境変数からキーを転送する処理は 再構築で明記したものです。元のインターフェースはキーなしの状態で取得されました。）

転送の仕組み

最初のツール呼び出しで、クライアントは上流とのストリーミング可能な HTTP セッションを開きます。JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name jobhunt）、続いて notifications/initialized 通知、その後、呼び出し元の引数を変更せずに含む tools/call リクエストを送信します。上流が Mcp-Session-Id ヘッダーを付けて initialize に応答すると、その値はセッションの後続のすべてのリクエストに 付与され、プロセスの存続期間中、セッションは再利用されます。 応答はプレーンな JSON またはサーバー送信イベントとして届く場合があり、 どちらも読み取られます。

成功した上流の結果は、上流が設定した isError フラグも含めて、 そのまま返されます。失敗 — JSON-RPC エラー、2xx 以外のステータス、 読み取り不能な応答、または完了できないリクエスト — は、 テキストが jobhunt error: で始まる isError 結果として返されます （この表現は、この再構築で独自に付けたラベルです）。

CLI

各ツールは、JSON 引数文字列を受け取るサブコマンドとしても利用できます。

npx @reneturcios/jobhunt search_jobs '{"q":"typescript","remoteType":["remote"]}'
npx @reneturcios/jobhunt get_job '{"id":"00000000-0000-0000-0000-000000000000"}'
npx @reneturcios/jobhunt search_companies '{"search":"acme"}'
npx @reneturcios/jobhunt get_company '{"id":42}'
npx @reneturcios/jobhunt webhook_example '{"event":"job.created","language":"python"}'
npx @reneturcios/jobhunt --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/jobhunt mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "jobhunt": {
      "command": "npx",
      "args": ["-y", "@reneturcios/jobhunt", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/jobhunt
docker run --rm ghcr.io/cloudcorprecords/jobhunt --version

コンテナのデフォルトコマンドは mcp なので、最初の形式は stdio MCP サーバーです。それ以外の引数は、通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化された JSON-RPC 上流に対して実行されます。実際のネットワーク呼び出しはありません。

ライセンス

MIT — LICENSE を参照してください。