H1b

@pipeworx/h1b

DOL（米国労働省）の労働条件申請（LCA）公開データに基づく、米国のH-1Bビザスポンサーシップと賃金のデータです。「企業XはH-1Bをスポンサーしますか」「企業Xで職種Yの給与はいくらですか」「オースティンで最も多くのデータエンジニアをスポンサーしているのはどの企業ですか」といった質問に対応します。

Pipeworx の一部です。AI エージェントを1881以上の稼働中データソースに接続するMCPゲートウェイです。これは独立した非公式の連携であり、上流プロバイダーとは提携しておらず、同プロバイダーによる承認や公開も受けていません。

ツール

• h1b_employer_sponsorship(employer, year?) — 雇用主の申請件数、給与範囲、上位の職種名・勤務地です。
• h1b_salary(job_title, employer?, city?, year?, limit?) — 実際に開示された基本給の統計と、その職種に関するレコードのサンプルです。
• h1b_top_sponsors(job_title, city?, year?, limit?) — 職種ごとに申請件数で順位付けした雇用主と、給与の中央値です。

引数の名前や形式は fleet #2514 以前から変わっておらず、回答の提供元のみが変更されています。

2層のデータソース（fleet #2514）

プライマリ：直近の連邦会計年度については、DOL独自のLCA公開ファイルです。 古い年度のデータはh1bdata.infoから取得します。DOLのデータを使用した回答にはすべてdata_as_ofが含まれます。

フォールバック：h1bdata.infoは、同じDOLデータを集約するサードパーティのサービスです。要求された年度がローカルミラーの読み込み済み期間外の場合、またはDBに接続できない場合にのみ使用されます。ミラーへのデータの取り込みが一部完了していない間も、このパックの動作が#2514以前より後退することはありません。回答には、実際にどちらが処理したかを示すsourceフィールドが必ず含まれます。通知なしにデータソースが切り替わることはありません。

フォールバックで0件でも、確信を持って「該当なし」とは示しません（fleet #3198）。 認証情報の不足、タイムアウト、一時的なエラーなどにより、この呼び出しでDBの読み取りに失敗した場合（source_status: "primary_unreachable"）、h1bdata.infoの回答が0件でも、sponsors_h1b: nullを返し、プライマリソースを実際には照会していないため未確認であることを示すメッセージを返します。プライマリソースから正常に回答を得たものの、対象年度が実際に読み込み済み期間外だった場合（source_status: "out_of_window）に限り、フォールバックの0件は（遅延や名称変更の影響を受けやすいサードパーティのデータではありますが）実際の「該当なし」として扱われます。dbRpcは一時的なエラーが発生すると、フォールバックに移る前にすぐ1回再試行するため、ネットワークの瞬断だけでミラーが対応しているクエリが信頼性の低いデータソースに切り替わることはありません。また、h1b_employer_sponsorshipのmatched_employersは完全一致を先に、次に名前を含む候補を順位付けして返すようになり、それぞれにname_matchが付与されます。雇用主名の照合は単純な部分文字列検索のため、複数の異なる法人名が正当に一致する場合があります。

ミラーを用意する理由： h1bdata.infoのライブスクレイピングには、クエリごとに取得する生のHTMLテーブル行数に上限があります（fetchLcaLiveの安全上限は20,000行）。そのため、申請件数がこの上限を超える雇用主や職種では、給与統計やtop_sponsorsのランキングが、通知なしに切り捨てられた代表性のないデータから算出されていました。DOLデータを使用する年度では、top_sponsorsは上限を設けず、条件に一致するすべての行を集計します（222_h1b_lca_disclosures.sqlのh1b_top_sponsors RPCにあるtotal_all_filingsを参照。行数制限の適用前にウィンドウ関数で合計しています）。

ローカルミラーでは暦年ではなく会計年度を使用します。 DOLのファイルは連邦会計年度（10月1日～9月30日）ごとに整理されており、ローカルで処理する場合、yearはそのまま会計年度として渡されます。h1bdata.info独自の「year」フィルターは意味が異なり、検証もされていません（おそらく暦年です）。同じyearの値でも、どちらの経路で回答するかによって、対象となる12か月間が同一とは限りません。どちらの経路で処理されたかは、回答のnote／sourceフィールドに記載されます。これは実際に開示された差異であり、取り繕われるものではありません。

個人データに関するルール（必須、ローカルコピーのルール — タスク #2514）

DOL 独自のレコードレイアウト（LCA_Record_Layout_FY2024_Q4.pdf、2026-09-29 に全文を確認）には、個人を特定できる連絡先フィールドが含まれていますが、ミラーには決して読み込みません。scripts/h1b-lca-transform.py はソース列の許可リスト（ブロックリストではありません）を使用するため、DOL が後から列を追加しても、デフォルトで除外されます。

• EMPLOYER_POC_{LAST,FIRST,MIDDLE}_NAME、EMPLOYER_POC_EMAIL、 EMPLOYER_POC_PHONE — 雇用主の指名連絡担当者です。
• AGENT_ATTORNEY_{LAST,FIRST,MIDDLE}_NAME、 AGENT_ATTORNEY_EMAIL_ADDRESS、AGENT_ATTORNEY_PHONE — 雇用主を代理する弁護士または代理人です。
• PREPARER_{LAST,FIRST,MIDDLE}_NAME、PREPARER_EMAIL — フォームの記入者です。

DOL のファイルでは、外国人労働者本人の氏名と住所はすでに除外されています（DOL 独自の注記では、非開示情報として「Attorney's FEIN and Attorney's State Bar Number」のみを挙げており、このデータセットに労働者の PII が含まれていたことはありません）。保持されるのは、EMPLOYER_NAME／TRADE_NAME_DBA、市・州・国までの雇用主住所（番地は含みません）、および職務・賃金・勤務地の各フィールドです。これらは、義務付けられた公開情報の開示を行う雇用主を特定するものであり、個人を特定するものではありません。

データソース

• https://www.dol.gov/agencies/eta/foreign-labor/performance — DOL OFLC の実績データページです。各会計年度の開示ファイルへのリンクがあります。
• 2026-09-29 にライブデータで検証済み（DOL による説明はなく、decision_date の分布からリバースエンジニアリングで確認。終了済み年度については、レコードレイアウト PDF の表紙の記載は誤りです）：
  • 現在進行中の会計年度の最新四半期ファイルは、その会計年度の 10 月 1 日から対象四半期の末日までを含む累積ファイルです（FY2026_Q3.xlsx は 2025 年 10 月から 2026 年 6 月までを対象とします）。保存先は https://www.dol.gov/media/LCA_Disclosure_Data_<label>.xlsx です。進行中の年度について読み込むのは、最新ファイル 1 件だけにしてください。
  • 会計年度が終了すると、DOL がアーカイブするその年度の四半期ファイルはそれぞれ個別の期間を対象とします。decision_date は該当する四半期内の日付のみです（確認済み：FY2025_Q3.xlsx は 2025 年 4 月～6 月のみ、FY2025_Q4.xlsx は 2025 年 7 月～9 月のみを対象とし、年度全体ではありません。レコードレイアウト PDF の表紙には「Reporting Period: October 1 ... through September 30」と明記されていますが、これは正しくありません）。保存先は https://www.dol.gov/sites/dolgov/files/ETA/oflc/pdfs/LCA_Disclosure_Data_<label>.xlsx です。終了済み年度をすべて網羅するには、4 四半期分のファイルすべてが必要です。各ファイルの期間は重複しません。
• 認証は不要で、レート制限も確認されていません。米国連邦政府の行政データであり、パブリックドメインです。

取り込みハーネス

• supabase/migrations/222_h1b_lca_disclosures.sql — h1b_lca_disclosures テーブル、h1b_lca_ingest_runs の記録管理、3 つの RPC（h1b_lca_search、 h1b_top_sponsors、h1b_lca_coverage）。RLS は有効で、anon／authenticated には権限がなく、service_role のみがアクセスできます。
• scripts/h1b-lca-transform.py — openpyxl(read_only=True) で 1 つの .xlsx ファイルを行単位でストリーミング処理します（ワークブック全体をメモリに読み込むことはありません。会計年度全体では非圧縮で 80～250MB になります）。個人情報を含まない列を許可リストに基づいて選択し、 WAGE_RATE_OF_PAY_FROM／WAGE_UNIT_OF_PAY から base_salary_annual を計算します（Hour×2080、Week×52、 Bi-Weekly×26、Month×12、Year×1）。
• scripts/h1b-lca-upsert.sh — ファイルごとに、ダウンロード（当年の URL を試し、閉鎖済み年度のアーカイブ URL にフォールバック）、変換、ステージングテーブルへの \copy、その後 INSERT ... ON CONFLICT (case_number) DO UPDATE を実行します （CASE_NUMBER は DOL 独自の、申請ごとに安定した ID のため、合成キーは不要です）。
• .github/workflows/h1b-lca-refresh.yml — workflow_dispatch のみ （意図的に schedule: はありません。Bruce の「supa stagger」ルールでは、大規模な Supabase の読み込みを一度に 1 件ずつ、夜間に実行するようキューに入れます。また、GitHub の schedule: トリガーは 2026-09-09 頃から全体的に不安定になっています）。デフォルトの files 入力は、タスクの指定どおり「直近 8 四半期」で、重複も欠落もないことを確認済みです。 2026:FY2026_Q3（累積、＝ FY2026 Q1＋Q2＋Q3）＋ 2025:FY2025_Q1,2025:FY2025_Q2,2025:FY2025_Q3,2025:FY2025_Q4（個別の四半期 4 件）＋ 2024:FY2024_Q4（個別の四半期 1 件）— 6 ファイル、 2024 年 7 月～2026 年 6 月。

確認済みのサイズ／行数（実データ、2026-09-29 — 変換の検証実行であり、全件読み込みではありません）

ファイル	バイト数	実データ行数
FY2026_Q3（累積、2025 年 10 月～2026 年 6 月）	251,850,891	437,496
FY2025_Q4（2025 年 7～9 月のみ）	79,134,156	118,580
FY2025_Q3（2025 年 4～6 月のみ）	143,867,250	238,425
FY2025_Q2（2025 年 1～3 月のみ）	106,951,050	未ダウンロード — サイズ比から推定約 175k
FY2025_Q1（2024 年 10～12 月のみ）	87,690,398	未ダウンロード — サイズ比から推定約 145k
FY2024_Q4（2024 年 7～9 月のみ）	83,056,843	未ダウンロード — サイズ比から推定約 120k

デフォルトの 6 ファイル読み込みの合計は、約 1.2～1.3M 行、xlsx の ダウンロードサイズは約 650MB と推定されます。各 .xlsx シートには、実データの後に実際には空の余分な行が大量に続きます（例：FY2026_Q3 では、シートの宣言上の行数は 1,032,736 行ですが、実データは 437,496 行です）。これは DOL のエクスポートに起因するもので、変換スクリプトの不具合ではありません。これらの行は破棄され、「CASE_NUMBER なし」としてカウントされます。

既知のソースデータ品質上の注意点

DOL の生データでは、WAGE_RATE_OF_PAY_FROM と WAGE_UNIT_OF_PAY が食い違い、base_salary_annual が異常な値になることがあります（FY2026_Q3 で確認された行では年換算額が約 4 億 5,300 万ドルになります。申請者による単位入力ミスの可能性が非常に高いものの、「修正」せず、そのまま保持しています。sba_loans でソースの重複・競合する行を文字どおり保持するのと同じ方針です）。median を使う統計はこうした影響を受けにくい一方、レスポンスの max にはまれにこうした外れ値が表示される場合があります。これはソースデータに起因するものであり、ミラーの不具合ではありません。

注意点

• DOL の実際の .xlsx ファイルでは、H-1B 依存雇用主の列名は H_1B_DEPENDENT（アンダースコア）です。record-layout PDF では H-1B_DEPENDENT（ハイフン）となっています。実際のファイルを優先してください。2026-09-29 に FY2026_Q3.xlsx で確認済みです。
• 進行中の会計年度についてはファイルを 1 件より多く読み込まないでください。また、閉鎖済み年度のファイルは、その年度の四半期 4 件すべてを揃えずに読み込まないでください。上記の「データソース」を参照してください。誤ると、重複行が発生する（重複期間のある累積ファイルと個別ファイルを二重にカウントする）か、気付かれない欠落が生じます。

クイックスタート

MCP クライアント（Claude Desktop、Cursor、Windsurf など）に追加します。

{
  "mcpServers": {
    "h1b": {
      "url": "https://gateway.pipeworx.io/h1b/mcp"
    }
  }
}

このエンドポイントが実際に提供するもの

https://gateway.pipeworx.io/h1b/mcp の tools/list は、上記の表にあるツールに加えて、共有 Pipeworx メタツール（ask_pipeworx、discover_tools、search_within、remember／recall など、ゲートウェイ全体で利用できる一連のツール）も返します。そのため、表示されるツール数はこの表より多くなります。単一パックのエンドポイントでは現在、そのパック独自のツールに加えて、およそ30個の共有ツールが一覧表示されます。接続の initialize レスポンスには正確な範囲が記載されており、その日の状況を確認する際の最も信頼できる情報源です。

これは意図的な設計であり、偶然の多重化ではありません。メタツールを使うことで、このパックが対応していない質問にも、カタログ全体を対象に処理を振り分ける ask_pipeworx を介して回答できます。そのため、MCP サーバーをもう1つ追加する必要はありません。現時点では、メタツールを含めずにパックのエンドポイントをマウントする方法はありません。追加のスキーマによるコンテキスト消費が、ルーティングの利点を上回る場合は、複数のパックエンドポイントではなく、フルゲートウェイに一度接続してください。

または、Pipeworx のフルゲートウェイに接続して、このパックのツールだけでなく、すべてのパックのツールを直接一覧表示できます。

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

どちらのURLも同じゲートウェイと同じ1881以上のデータソースにアクセスします。違いは、どのパックのツールが直接一覧表示されるかだけです。どちらからでも ask_pipeworx を使ってすべてのツールにアクセスできます。

MCP クライアントをお持ちでない場合：HTTP 経由で呼び出す

curl -X POST https://gateway.pipeworx.io/v1/tools/h1b_employer_sponsorship \
  -H 'Content-Type: application/json' \
  -d '{"employer":"Google","year":2024}'

最初の呼び出しにアカウントは必要ありません。ツールの内容を確認するには、GET https://gateway.pipeworx.io/v1/tools/h1b_employer_sponsorship を実行してください。ツールを検索するには、{"query":"..."} を指定して POST https://gateway.pipeworx.io/v1/tools/search_packs を実行してください。

スタンドアロン（ゲートウェイアカウント不要）

このパッケージは、ローカルの stdio MCP サーバーとしても実行できます。Pipeworx アカウントもゲートウェイとの往復通信も必要ありません。

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

または、直接実行して起動することを確認できます。

npx -y @pipeworx/mcp-h1b

stdin/stdout 経由で MCP を使用し、このパックのツールのみを対象に initialize／tools/list／tools/call に応答します。上記のゲートウェイ接続で追加される共有メタツールは含まれません。同じソース、同じツールで、ask_pipeworx によるルーティングはありません。

ask_pipeworx を使う

ツールを直接呼び出す代わりに、自然な英語で質問できます。これは上記のパックエンドポイントでも、フルゲートウェイでも利用できます。

ask_pipeworx({ question: "your question about H1b data" })

ゲートウェイが適切なツールを選び、引数を自動的に入力します。

詳細

• ドキュメントとガイド
• pipeworx.io

ライセンス

MIT