H1b Job Search MCP

🚀 H1B工作搜索MCP服務器

本項目是一個基於MCP（模型上下文協議）的服務器，藉助美國勞工部的真實勞工條件申請（LCA）披露數據，實現H-1B工作搜索自動化。它基於 FastMCP 構建。

🚀 在線服務器：https://h1b-job-search-mcp.onrender.com/mcp

✨ 主要特性

• 📊 下載LCA數據：自動從勞工部下載並緩存H-1B LCA披露數據。
• 🔍 智能搜索：可按職位、地點和薪資篩選提供H-1B贊助的公司。
• 🏢 公司分析：獲取特定公司的詳細贊助統計信息。
• 📈 頂級贊助商：按贊助數量列出頂級H-1B贊助公司。
• 🚫 中介過濾：自動過濾掉人力資源中介機構，以找到直接僱主。
• 📁 導出結果：將篩選結果導出為CSV文件，便於進一步聯繫。
• 💾 數據緩存：智能緩存機制，避免重複下載大型數據集。
• 🤖 多LLM支持：支持Claude、ChatGPT、Gemini、Cursor和Poke等多種大語言模型。

📦 安裝指南

本地開發設置

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 ，使用“可流式傳輸的HTTP”傳輸方式連接到 http://localhost:8000/mcp。

部署

選項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

💻 使用示例

快速示例

你可以自然地與系統交流，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"（告訴我有關谷歌的H-1B贊助情況）
• "Export data scientist positions to CSV"（將數據科學家職位導出為CSV文件）

詳細使用示例

請查看 使用指南，其中包含詳細的使用示例和自然語言提示。

示例使用流程

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"
   }
   

📚 詳細文檔

可用的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"（告訴我有關微軟的H-1B計劃）

多LLM支持

本MCP服務器支持多個大語言模型平臺。詳細的集成說明請參考 docs/LLM_INTEGRATION.md。

快速設置（按平臺）

Claude桌面版

{
  "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許可證。

貢獻

歡迎提交問題和拉取請求，以改進本工具！