H1b Job Search MCP

🚀 H1B Job Search MCP Server

このサーバーは、実際の米国労働省のLCA開示データを使用して、H-1Bの求人検索を自動化するMCP（Model Context Protocol）サーバーです。FastMCPを使用して構築されています。

🚀 ライブサーバー: https://h1b-job-search-mcp.onrender.com/mcp

✨ 主な機能

✅ サンプルではなく、実データを使用！

このサーバーは、米国労働省の公式開示ファイルから実際のH-1B申請データを直接取得します。各データセットには、数万件の実際のH-1B申請が含まれており、以下の情報があります。

• 実際の会社名（Google、Microsoft、Amazonなど）
• 実際の職種と給与
• 実際の勤務地と連絡先情報
• 承認済みの申請ステータス

データソース: https://www.dol.gov/agencies/eta/foreign-labor/performance

その他の機能

• 📊 LCAデータのダウンロード：労働省からH-1B LCA開示データを自動的にダウンロードし、キャッシュします。
• 🔍 スマート検索：職種、勤務地、賃金でH-1Bを申請する会社を絞り込めます。
• 🏢 会社分析：特定の会社の詳細なH-1B申請統計を取得できます。
• 📈 上位申請会社：申請数で上位のH-1B申請会社を一覧表示します。
• 🚫 人材派遣会社のフィルタリング：人材派遣会社を自動的に除外して、直接雇用主を見つけます。
• 📁 結果のエクスポート：絞り込んだ結果をCSV形式でエクスポートし、簡単に連絡を取ることができます。
• 💾 データキャッシュ：大きなデータセットの再ダウンロードを避けるためのインテリジェントキャッシュ機能があります。
• 🤖 複数LLMサポート：Claude、ChatGPT、Gemini、Cursor、Pokeと連携できます。

🚀 クイックスタート

詳細な使用例と自然言語プロンプトについては、使用ガイド を参照してください。

簡単な使用例

自然な会話で操作できます！askツールは日常の英語を理解します。

• "Load the latest H-1B data"（最新のH-1Bデータを読み込む）
• "Find software engineer jobs in California paying over 150k"（カリフォルニアで年収15万ドル以上のソフトウェアエンジニアの仕事を探す）
• "Tell me about Google's H-1B sponsorships"（GoogleのH-1B申請について教えて）
• "Export data scientist positions to CSV"（データサイエンティストの職種をCSV形式でエクスポートする）

💻 使用例

利用可能なMCPツール

1. load_h1b_data

労働省からH-1B LCAデータをダウンロードして読み込みます。

• パラメーター:
  • year: 会計年度（デフォルト: 2024）
  • quarter: 四半期（1 - 4、デフォルト: 4）
  • force_download: キャッシュされていても再ダウンロードを強制する

2. search_h1b_jobs

職種と勤務地でH-1Bを申請する会社を検索します。

• パラメーター:
  • job_role: 検索する職種名（例: "Software Engineer"）
  • city: 勤務都市（オプション）
  • state: 勤務州コード（オプション、例: "CA"）
  • min_wage: 最低賃金のフィルター（オプション）
  • max_results: 返す最大結果数
  • skip_agencies: 人材派遣会社をスキップする（デフォルト: true）

3. get_company_stats

特定の会社の詳細なH-1B申請統計を取得します。

• パラメーター:
  • company_name: 分析する会社名

4. get_top_sponsors

申請数で上位のH-1B申請会社を一覧表示します。

• パラメーター:
  • limit: 返す会社数
  • exclude_agencies: 人材派遣会社を除外する

5. export_results

絞り込んだH-1B検索結果をCSVファイルにエクスポートします。

• パラメーター:
  • job_role: フィルターする職種名
  • city: 都市フィルター（オプション）
  • state: 州フィルター（オプション）
  • filename: 出力ファイル名
  • max_results: エクスポートする最大結果数

6. get_available_data

利用可能なLCAデータ期間とキャッシュされたファイルを確認します。

7. ask（自然言語インターフェース） 🎯

簡単な英語でH-1B検索に話しかけることができます！

• 使用方法: 欲しい情報を日常の言葉で説明するだけです。
• 使用例:
  • "I'm a software engineer looking for jobs in the Bay Area"（私はベイエリアで仕事を探しているソフトウェアエンジニアです）
  • "Show me data scientist positions paying over 180k"（年収18万ドル以上のデータサイエンティストの職種を見せて）
  • "Which companies sponsor the most H-1B visas?"（最も多くのH-1Bビザを申請する会社はどれですか？）
  • "Tell me about Microsoft's H-1B program"（MicrosoftのH-1Bプログラムについて教えて）

📚 ドキュメント

ローカル開発

セットアップ

git clone <your-repo-url>
cd mcp-server-template
conda create -n h1b-mcp python=3.13
conda activate h1b-mcp
pip install -r requirements.txt

MCPインスペクターでテスト

# ターミナル1: サーバーを起動する
python src/server.py

# ターミナル2: インスペクターを実行する
npx @modelcontextprotocol/inspector

http://localhost:3000 を開き、"Streamable HTTP"トランスポートを使用して http://localhost:8000/mcp に接続します。

例の使用フロー

1. データの読み込み:

   Tool: load_h1b_data
   Parameters: {"year": 2024, "quarter": 4}
   

2. 求人検索:

   Tool: search_h1b_jobs
   Parameters: {
     "job_role": "Software Engineer",
     "state": "CA",
     "min_wage": 120000,
     "skip_agencies": true
   }
   

3. 会社の詳細を取得:

   Tool: get_company_stats
   Parameters: {"company_name": "Google"}
   

4. 結果のエクスポート:

   Tool: export_results
   Parameters: {
     "job_role": "Data Scientist",
     "state": "NY",
     "filename": "ny_data_scientists.csv"
   }
   

デプロイメント

オプション1: Renderにデプロイ

上の "Deploy to Render" ボタンをクリックしてください。

オプション2: 手動デプロイ

1. このリポジトリをフォークします。
2. あなたのGitHubアカウントをRenderに接続します。
3. Renderで新しいWebサービスを作成します。
4. フォークしたリポジトリを接続します。
5. Renderは自動的に render.yaml 設定を検出します。

あなたのサーバーは https://your-service-name.onrender.com/mcp で利用可能になります。

現在のデプロイ先: https://h1b-job-search-mcp.onrender.com/mcp

複数LLMサポート

このMCPサーバーは複数のLLMプラットフォームと連携します。詳細な統合手順については、docs/LLM_INTEGRATION.md を参照してください。

プラットフォーム別のクイックセットアップ

Claude Desktop

{
  "mcpServers": {
    "h1b-search": {
      "command": "python",
      "args": ["/path/to/src/server.py"]
    }
  }
}

ChatGPT/OpenAI

PORT=8000 python src/server.py でサーバーを起動し、config/openai_config.json のOpenAPIスキーマを使用します。

Google Gemini

config/gemini_config.json を使用して関数宣言で設定します。

Cursor IDE

config/cursor_config.json を .cursor/mcp-config.json に配置し、再読み込みします。

Interaction Poke

Pokeの設定で config/poke_config.json を使用します。

完全なセットアップガイド、テスト手順、トラブルシューティングについては、docs/LLM_INTEGRATION.md を参照してください。

データソース

このツールは、米国労働省の外国労働認証データセンターから公開されているLCA開示データを使用しています。データには以下が含まれます。

• 雇用主情報
• 職種と賃金
• 勤務地
• 申請ステータス
• 連絡先情報（利用可能な場合）

注意: このデータは過去のH-1B申請パターンを示しています。常に雇用主に直接現在の申請ポリシーを確認してください。

プライバシーと法的事項

• 使用するすべてのデータは米国労働省から公開されているものです。
• 個人情報や機密情報はアクセスされません。
• 雇用主に連絡する際は、責任を持って専門的に行ってください。
• 会社のコミュニケーション上の好みを尊重してください。

カスタマイズ

src/server.py を変更することで、カスタムフィルタリングロジックや追加ツールを追加できます。

@mcp.tool
def custom_analysis(parameter: str) -> dict:
    """Your custom H-1B data analysis."""
    # Your implementation here
    pass

トラブルシューティング

• データが読み込めない場合: インターネット接続を確認し、年/四半期が存在することを確認してください。
• 結果が見つからない場合: 検索条件を広げるか、異なる四半期を試してみてください。
• メモリの問題: 全データセットは大きい場合があります。pandasで nrows パラメーターを使用することを検討してください。
• キャッシュの問題: data_cache ディレクトリを削除して、新しいダウンロードを強制してください。

貢献

このツールを改善するために、問題やプルリクエストを送信してください！

📄 ライセンス

MIT