Perm

@pipeworx/perm

DOL PERM（Program Electronic Review Management、Form ETA-9089）の開示データに基づく、米国のグリーンカード労働認定データです。「企業 X はグリーンカードをスポンサーしていますか」「PERM に基づき、企業 X で職種 Y の給与はいくらですか」「グリーンカードをスポンサーするデータエンジニアが最も多いのはどの企業ですか」といった質問に対応します。LCA／一時就労ビザ側を扱う @pipeworx/h1b の、永続的労働認定版です。

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

ツール

• perm_employer_certifications(employer, year?) — 企業ごとの申請件数、提示賃金の範囲、上位の職種／勤務地を返します。合計件数を最初に返し、すべての応答に data_as_of を含めます。
• perm_salary(job_title, employer?, city?, year?, limit?) — 職種の実際に開示された提示賃金の統計と、レコードのサンプルを返します。
• perm_top_sponsors(job_title, city?, year?, limit?) — 職種ごとの申請件数で企業をランキングし、提示賃金の中央値も返します。

認証

キーは不要です。ローカルミラーのみを使用します。呼び出し元の認証情報は不要で、受け付けません。

ローカルミラー、ライブフォールバックなし

ミラーを使う理由：PERM は LCA と同様、四半期／年次の一括 .xlsx ファイルとしてのみ公開されており、dol-whd／osha／ebsa がすでに利用している apiprod.dol.gov v4 ゲートウェイにはありません（2026-10-17 に実際に確認済み。そのゲートウェイの45データセットのカタログにもありません）。このパックでは、ローカルの Supabase ミラーのみがデータソースです。

h1b とは異なり、ライブフォールバックはありません。 LCA には、同じ DOL データを集約する、長年運用されているサードパーティーの h1bdata.info がありますが、PERM 開示データに相当するサードパーティーミラーは見つかりませんでした。そのため、クエリが現在読み込み済みの会計年度の範囲外である場合や、ミラーをまったく読み取れない場合、すべてのツールは coverage_status フィールドと null（false ではありません）のスポンサー状況／件数を返します。「この企業はスポンサーしていない」と受け取れる、単なる空の結果は返しません。実際には、ミラーがその年度のデータをまだ読み込んでいない、または初回読み込みを完了していない可能性があるためです。状態は3種類あり、h1b の fleet #3198 の修正と同じ方針です。

• not_loaded_yet — ミラーの取り込みテーブルが実際に空です（初回の更新がまだ実行されていません）。「このデータソースの初回読み込みはまだ完了していません。」
• mirror_unreachable — カバレッジの読み取り自体に失敗しました（認証情報がない、タイムアウト、一時的な DB エラーなど）。「申請件数がゼロであることを確認したわけではありません。この呼び出しではデータソースが実際に参照されませんでした。」
• out_of_window — ミラーは正常に応答しましたが、要求された会計年度は読み込み済みの範囲外です。実際のシグナルですが、カバレッジは不完全です。

雇用主名の照合レベル。 perm_search の SQL（employer_name ILIKE '%' || p_employer || '%'）も、統計 RPC のグループ化も、単純な部分文字列照合です。そのため、「Amazon」のようなクエリで、正当な理由により複数の異なる法人名が返されることがあります（実際の FY2025 ファイルで確認済み：AMAZON.COM SERVICES LLC／Amazon.com Services LLC／Amazon.Com Services Llc／Amazon Data Services, Inc. がすべて含まれています）。matched_employers は、まず完全一致（大文字小文字／句読点を除去し、一般的な法人種別の接尾辞を取り除いた後）を優先し、次に名前を含むバリエーションを順位付けし、それぞれに name_match を付けます。h1b が使用するものと同じ employerNameKey／gradeEmployerMatch／rankEmployerVariants のロジックです（fleet #3198）。

個人データ規則（必須、ローカルコピー規則 — task #3263）

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

• EMP_POC_{LAST,FIRST,MIDDLE}_NAME、EMP_POC_EMAIL、EMP_POC_PHONE、およびすべての EMP_POC_ADDR* フィールド — 雇用主の氏名付き連絡担当者です。
• ATTY_AG_{LAST,FIRST,MIDDLE}_NAME、ATTY_AG_EMAIL、ATTY_AG_PHONE、すべての ATTY_AG_ADDRESS*／STATE_BAR_NUMBER／GOOD_STANDING* フィールド — 雇用主を代理する個人の弁護士または代理人です（事業者名である ATTY_AG_LAW_FIRM_NAME も、このツールでは使用しないため除外されます）。
• DECL_PREP_{LAST,FIRST,MIDDLE}_NAME、DECL_PREP_EMAIL — 雇用主の宣誓書に署名した人物です。
• すべての FOREIGN_WORKER_*／COUNTRY_OF_CITIZENSHIP／CLASS_OF_ADMISSION フィールド — PERM のレイアウトには外国人労働者の氏名フィールドは一切ありません（レイアウト全文を確認済み）。ただし、これらのフィールドもスポンサー対象労働者自身の国籍／学歴／職歴を示すものであり、このツールでは必要ありません。

保持する項目：EMP_BUSINESS_NAME／EMP_TRADE_NAME、雇用主の市／州／国／FEIN／NAICS（番地は含めません — h1b_lca_disclosures と同じ方針です）、ならびに職務／賃金／勤務地のフィールドとケースのステータス／日付 — これらは、非公開の個人ではなく、義務的な公開情報を開示する雇用主を特定します。

データソース

• 米国労働省、外国人労働者認証局 — PERM 開示データです。連邦会計年度（10 月 1 日から 9 月 30 日）ごとに四半期単位で公開されます。認証は不要で、レート制限は確認されていません。米国連邦政府の行政データであり、パブリックドメインです。
• 2026-10-17 にライブデータで確認済み：会計年度が終了している場合、その年度の Q4 表記のファイルはすでに会計年度全体を含みます — h1b の LCA ミラーとは異なります。h1b では、終了済み年度の四半期ファイルはそれぞれ独立しており、4 つすべてが必要です。PERM_Record_Layout_FY2025_Q4.pdf の表紙には、「報告期間：2024 年 10 月 1 日から 2025 年 9 月 30 日」と記載されています。したがって、会計年度ごとにファイル 1 つで年間全体を網羅できます。現在進行中の会計年度についても、最新の四半期ファイルには同様に 10 月 1 日からの累計データが含まれます（FY2026_Q3.pdf：「2025 年 10 月 1 日から 2026 年 6 月 30 日」）。

新フォームのみ

DOL の PERM フォーム（ETA-9089）は 2023-06-01 に変更されました。2026-10-17 に実際のダウンロードファイル 2 件を照合して確認済みです。FY2024 のファイルは旧形式の 155 列構成（例：EMP_CONTACT_NAME という単一フィールドがあり、JOB_OPP_WAGE_FROM はありません）ですが、FY2025 以降は、このパックの変換処理が想定する新形式の 137 列構成を使用しています。scripts/perm-transform.py の REQUIRED_SOURCE チェックは、旧形式のファイルを誤った列対応のまま処理することなく、明示的に拒否します。旧形式の過去データの取り込み（FY2025 より前）は今後の作業であり、ここでは試みていません。ミラーは現在、FY2025 以降を読み込みます。

取り込みハーネス

• supabase/migrations/259_perm_disclosures.sql — perm_disclosures テーブルと perm_ingest_runs の記録管理、および 4 つの RPC（perm_search、perm_stats、 perm_top_sponsors、perm_coverage）。RLS は有効で、anon／authenticated には 権限がなく、service_role のみが利用できます。
• scripts/perm-transform.py — openpyxl(read_only=True) を使用して、1 つの .xlsx ファイルを 行ごとにストリーミング処理します（ワークブック全体をバッファーに保持することはありません）。個人情報を含まない列を許可リストから選択し、 JOB_OPP_WAGE_FROM／JOB_OPP_WAGE_PER から base_salary_annual を計算します（Hour×2080、Week×52、Bi-Weekly×26、 Month×12、Year×1）。h1b の変換処理と同じ、申請者の入力ミスに対するガードを適用します （「Hour」タグ付きの 4 桁または 5 桁の金額は、すでに年額として扱います。年換算後の金額が $5,000,000 を超える場合は、データとして提供せず null にします）。
• scripts/perm-upsert.sh — ファイルごとに、ダウンロード（現行年度の URL を試し、閉鎖済み年度のアーカイブ URL にフォールバック）、変換、 ステージングテーブルへの \copy、続いて INSERT ... ON CONFLICT (case_number) DO UPDATE を実行します （CASE_NUMBER は DOL 独自の、申請ごとに安定した ID のため、合成キーは不要です）。
• .github/workflows/perm-refresh.yml — workflow_dispatch のみ （意図的に schedule: は設定していません。Bruce の「supa stagger」ルールにより、大規模な Supabase の読み込みは 意図的に夜間に 1 件ずつ実行されます。また、GitHub の schedule: トリガーは、2026-09-09 頃以降、全体的に信頼性が低下しています）。デフォルトの files 入力：2026:FY2026_Q3（現在公開中の年度）＋2025:FY2025_Q4 （FY2025 全期間）。

確認済みのサイズ／行数（実データ、2026-10-17 — 変換処理のドライランによる検証、ストアへの読み込みは未実施）

ファイル	バイト数	実データ行数（変換のみ、DB 書き込みなし）
FY2025_Q4（FY2025 全期間、2024 年 10 月～2025 年 9 月）	87,007,731	147,056 行を保持、1,603 行を除外（CASE_NUMBER なし）
FY2024_Q4（旧形式、未読み込み）	76,167,854	変換処理で拒否 — 旧形式の構造
FY2026_Q3（現行、累計）	156,267,808	検証実行中は未ダウンロード — FY2025 の通年件数を 12 か月中 9 か月分で按分すると、約 11 万～13 万件と推定

注意点

• 実際の FY2025 ファイルで確認された case_status の値：Certified、 Certified - Expired（ダッシュの前後にスペースがあります。レコードレイアウトの説明から想定される Certified-Expired ではありません）、Denied、Withdrawn。「Certified」でのフィルターには最初の 2 つが一致します。
• 旧形式の変換処理を先に構築せずに、FY2024 以前のファイルをリフレッシュに追加しないでください。上記の「NEW FORM ONLY」を参照してください。
• perm_employer_certifications／perm_salary／perm_top_sponsors は、ミラーから回答できない場合、 スポンサー情報や件数に false／0 ではなく、常に null を返します。空の結果を実際に該当なしと判断する前に coverage_status を確認してください。

クイックスタート

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

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

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

https://gateway.pipeworx.io/perm/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 も同じゲートウェイと同じ 1831 以上のデータソースに接続します。違いは、どのパックのツールが直接一覧表示されるかだけです。どちらからでも ask_pipeworx を使って、すべてのツールにアクセスできます。

MCP クライアントがない場合は、HTTP で呼び出す

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

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

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

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

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

起動することを確認するには、直接実行することもできます。

npx -y @pipeworx/mcp-perm

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

ask_pipeworx を使う

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

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

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

詳細

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

ライセンス

MIT