Perm MCP server

@pipeworx/perm

US green-card labor certification data from DOL PERM (Program Electronic Review Management, Form ETA-9089) disclosures — "does company X sponsor green cards", "what does role Y pay at company X under PERM", "who sponsors the most data engineers for green cards". The permanent-labor-certification sibling of @pipeworx/h1b (which covers the LCA / temporary-visa side).

Part of Pipeworx — an MCP gateway connecting AI agents to 1831+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.

Tools

range, top titles/locations for an employer. Total count first, dataasof on every response.

• permemployercertifications(employer, year?) — filing count, offered-wage

offered-wage stats + a sample of records for a role.

• permsalary(jobtitle, employer?, city?, year?, limit?) — real disclosed

filing count for a role, with median offered wage.

• permtopsponsors(job_title, city?, year?, limit?) — employers ranked by

Auth

Keyless. Local mirror only — no caller credential is needed or accepted.

Local mirror, no live fallback

Why a mirror: PERM, like LCA, is published only as bulk quarterly/annual .xlsx files — it is not on the apiprod.dol.gov v4 gateway that dol-whd/osha/ebsa already use (checked live 2026-10-17: not present in that gateway's 45-dataset catalog). A local Supabase mirror is this pack's only source.

Unlike h1b, there is no live fallback. LCA has h1bdata.info, a long-standing third-party aggregator of the same DOL data; no comparable third-party mirror of PERM disclosures was found. So when a query falls outside the mirror's currently loaded fiscal-year window, or the mirror cannot be read at all, every tool returns a coverage_status field and a null (not false) sponsorship/count — never a bare empty result that reads as "this employer doesn't sponsor" when the real reason is that the mirror has not loaded that year yet, or has not completed its first load. Three distinguishable states, same discipline as h1b's fleet #3198 fix:

first refresh has never run). "This data source has not completed its first load yet."

• notloadedyet — the mirror's ingest table is genuinely empty (the

credentials, a timeout, a transient DB error). "Not confirmation of zero filings — the data source was never actually consulted this call."

• mirrorunreachable** — the coverage read itself failed (no

year is outside its loaded range. A real (if incomplete-coverage) signal.

• outofwindow — the mirror answered fine, but the requested fiscal

Employer-name match grading. Both permsearch's SQL (employername ILIKE '%' || pemployer || '%') and the stats RPC's grouping are plain substring matches, so a query like "Amazon" can legitimately pull back more than one distinct legal name (verified live against the real FY2025 file: AMAZON.COM SERVICES LLC / Amazon.com Services LLC / Amazon.Com Services Llc / Amazon Data Services, Inc. all appear). matchedemployers ranks exact-match first (after stripping case/punctuation and common entity suffixes), then name-contains variants, each tagged name_match — same employerNameKey/gradeEmployerMatch/ rankEmployerVariants logic h1b uses (fleet #3198).

PERSONAL-DATA RULE (mandatory, local-copy rule — task #3263)

DOL's own record layout (PERMRecordLayoutFY2026Q3.pdf, read in full 2026-10-17) carries named-individual contact fields that are never read into the mirror — scripts/perm-transform.py uses an ALLOWLIST of source columns (not a blocklist), so a column DOL adds later is excluded by default:

Shortened. The full README is on GitHub.