DOL WHD MCP

TypeScript MCP server for Department of Labor WHD Enforcement, OFLC LCA disclosure, OSHA inspection, and SAM.gov contract opportunity data.

Setup

npm install
npm run build

Create a local .env file:

DOL_API_KEY=your-api-key
SAM_GOV_API_KEY=your-sam-gov-api-key
GOOGLE_PLACES_API_KEY=your-google-places-api-key

The server also accepts DOL_API_KEY, SAM_GOV_API_KEY, or SAM_API_KEY from the process environment. SAM.gov tools can run in dry-run mode without a SAM key. Tool responses redact request URLs and never return keys.

Run Locally Over Stdio

npm start

Example MCP client config:

{
  "mcpServers": {
    "dol-whd": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "<project-directory>"
    }
  }
}

Run Remotely Over HTTP

Build first, then start the Streamable HTTP MCP endpoint:

npm run build
npm run start:http

Defaults:

• MCP endpoint: http://127.0.0.1:8787/mcp

• Health check: http://127.0.0.1:8787/health

• Transport: MCP Streamable HTTP, stateless per request.

Remote environment knobs:

DOL_MCP_HOST=127.0.0.1
DOL_MCP_PORT=8787
DOL_MCP_AUTH_TOKEN=change-this-before-exposing
DOL_MCP_ALLOW_ORIGIN=*

If DOL_MCP_AUTH_TOKEN is set, MCP clients must send either:

Authorization: Bearer change-this-before-exposing

or:

X-API-Key: change-this-before-exposing

Keep the default host for local-only access. To make it reachable from another machine, bind to a reachable interface such as 0.0.0.0 and put it behind a trusted tunnel or reverse proxy with authentication. The DOL and SAM.gov API keys remain server-side in .env.

Deploy To Render

The repo ships a render.yaml Blueprint that provisions a free Node web service.

1. From the Render dashboard, click New → Blueprint and point it at https://github.com/UHQ-Actual/DOL_MCP.

2. Render reads render.yaml, creates the dol-whd-mcp service, generates a fresh DOL_MCP_AUTH_TOKEN, and prompts for the API key secrets (DOL_API_KEY, SAM_API_KEY, GOOGLE_PLACES_API_KEY).

3. After the first deploy the public URL is https://dol-whd-mcp.onrender.com (or whatever Render assigns). Verify with:

   curl https://<your-service>.onrender.com/health

4. Copy the DOL_MCP_AUTH_TOKEN value out of the Render env var panel — you need it for the MCP client.

Connect From Claude (Phone Or Web)

Claude.ai's mobile app shares Custom Connectors with the web UI, so adding the remote MCP once unlocks it on every device tied to that account.

1. In Claude.ai, open Settings → Connectors → Add custom connector.

2. Use the values from the Render deploy:

   • URL: https://<your-service>.onrender.com/mcp

   • Auth header: Authorization: Bearer <DOL_MCP_AUTH_TOKEN>

3. Save. The connector now lists every tool registered by createServer() (WHD, OFLC LCA, Foreign Labor, OSHA, SAM.gov, Google Places, ask_government_data).

4. Toggle the connector on inside any conversation to call the tools from your phone or laptop.

Tools

• ask_government_data: Route a plain-English question to the right database and execute the query against WHD enforcement, OSHA inspections, DOL foreign-labor/LCA disclosures, or SAM.gov opportunities.

• whd_enforcement_query: Query WHD/enforcement with limit, offset, fields, sort, sort_by, and filter_object.

• whd_enforcement_case: Look up a numeric case_id.

• whd_enforcement_metadata: Return full metadata rows, with optional search, category, and limit.

• whd_enforcement_fields: Return concise field descriptions for query building.

• dol_datasets_search: Search the public DOL datasets catalog.

• lca_disclosure_files: Return official DOL OFLC LCA disclosure and record-layout URLs for a fiscal year quarter.

• lca_disclosure_fields: Read field names from a DOL LCA disclosure XLSX file.

• lca_search: Search DOL OFLC LCA disclosure data by employer, worksite, title, SOC, NAICS, status, visa class, wage, and dates.

• lca_employer_profile: Build a DOL LCA-only employer profile with certification counts, wage statistics, top job titles, SOC codes, worksites, H-1B dependent, and willful violator flags.

• foreign_labor_files: Discover official DOL OFLC disclosure workbook, record-layout, and auxiliary file URLs for LCA, PERM, H-2A, H-2B, or CW.

• foreign_labor_fields: Read field names from an official DOL foreign-labor disclosure XLSX file.

• foreign_labor_search: Stream-search DOL OFLC foreign-labor disclosure workbooks and return a unified schema across LCA, PERM, H-2A, H-2B, and CW-1. First call per quarter downloads + parses the workbook and writes a gzipped JSONL cache alongside it; subsequent calls read the cache in 1-3 seconds.

• osha_fields: Return metadata for the official DOL OSHA inspection or violation dataset.

• osha_inspection_search: Search OSHA inspections by establishment, state, city, NAICS, inspection type, safety/health, and open-date range. Optionally joins non-deleted violation/citation records.

• osha_inspection_detail: Look up one OSHA inspection by activity_nr and optionally join violation/citation records.

• osha_state_plan_lookup: Static reference returning OSHA jurisdiction tier (federal_osha / public_only_state_plan / complete_state_plan), program name (MIOSHA, Cal/OSHA, IOSHA, etc.), administering agency, expected reporting lag, public-records request path, and a one-line caveat for any of the 50 states + DC + territories. Pair with osha_inspection_search to annotate sparse results with the right state-plan caveat.

• sos_portal_lookup: Static reference returning the Secretary of State / DFI / Corporation Commission business-entity search portal URL, agency, searchable fields, bulk-download availability, and pricing for any US state. The 10 Midwest states are verified with detailed notes (including Michigan's June 2025 MiBusiness Registry replacement of legacy COFS URLs and the Wisconsin DFI-not-SOS gotcha); the other 40 states use general portal URLs. For programmatic lookups, prefer business_entity_search via OpenCorporates.

• sam_opportunities_search: Search official SAM.gov contract opportunities by title keywords, NAICS codes, procurement types, set-aside code, contracting-office state, place-of-performance state/city, and posted date range. SAM.gov returns SOLICITATIONS, not awarded contracts; use usaspending_award_search for awarded dollar amounts.

• sam_opportunity_detail: Look up one SAM.gov opportunity by noticeId.

• sam_reference: Return common SAM.gov procurement type and set-aside codes.

• usaspending_award_search: Search USAspending.gov for federal awards with KNOWN obligated dollar amounts. Filters by NAICS, PSC, recipient, awarding agency, place-of-performance state/city/county FIPS, award amount range, and start-date range. Defaults to contract award types (A, B, C, D). No API key required.

• places_search: Search Google Places (New) Text Search for businesses in an area. Returns deduped results with googleMapsUrl for source-tracing. Designed as a per-round retrieval primitive for the Restaurant Research Agent.

• places_detail: Look up one Google place by Place ID. Returns hours, delivery/dine-in flags, and (optionally) editorialSummary and reviews.

• adv_estimate: Deterministic Annual Dollar Volume calculator for FLSA $500k enterprise-coverage screening. Encodes Methods 1-4 (per-employee, per-seat, chain per-unit, format default), the geographic cost-of-living multiplier, +/-40% range, and the FLSA flag (Above / Below / Borderline / Insufficient Data). Screening signal only; not a coverage determination.

• census_area_profile: Resolve a US city/town/CDP to total population (ACS 5-year), area tier (major_metro / mid_metro / small_or_rural), row-scaling tier and target (matching the Restaurant Research Agent's max(pop/250, floor) formula), county FIPS for follow-on usaspending_award_search, and the high-cost-of-living-state flag. Pairs with adv_estimate for end-to-end research workflows.

• business_entity_search: Search Secretary of State / DFI business registrations across all 50 states via OpenCorporates. Sourced directly from official state registries; data lineage is auditable. Returns name, company number, status, type, incorporation date, registered address, previous names, and an opencorporates_url per record. Free tier ~50 lookups/day; set OPENCORPORATES_API_KEY for higher volume. See docs/data-sources/state-business-registration.md for per-state coverage notes.

• business_entity_detail: Look up one entity by jurisdiction code + state company number via OpenCorporates. Returns the full canonical record (registered address, dissolution date, previous names, registry URL).

LCA tools use official OFLC disclosure workbooks from the DOL Performance Data page. The workbooks can be large, so downloaded files are cached under .cache/dol-lca/. You can also pass localFile with an already-downloaded official LCA disclosure XLSX file.

The LCA profile is DOL-only. USCIS H-1B petition approval and denial rates are not included unless a separate USCIS data source is added.

Foreign-labor tools read the DOL Performance Data page to discover current disclosure links, then stream-parse XLSX files row by row. Supported programs are LCA, PERM, H-2A, H-2B, and CW; supported unified-parser fiscal years are 2020 through 2030. Use localFile to point at an already-downloaded official workbook.

OSHA tools use the official DOL Open Data API datasets OSHA/inspection and OSHA/violation. Violation rows are joined to inspections by activity_nr; rows with delete_flag equal to X are excluded from joined output.

SAM.gov tools use the official Opportunities API at https://api.sam.gov/opportunities/v2/search. Live searches require SAM_GOV_API_KEY or SAM_API_KEY; dry-run searches return sample opportunities without calling SAM.gov. The API requires posted date bounds, so postedDaysAgo is converted to postedFrom and postedTo in MM/dd/yyyy format.

Examples

Filter Iowa records with back wages:

{
  "limit": 10,
  "fields": ["case_id", "trade_nm", "st_cd", "bw_atp_amt", "findings_end_date"],
  "sort": "desc",
  "sort_by": "bw_atp_amt",
  "filter_object": {
    "and": [
      { "field": "st_cd", "operator": "eq", "value": "IA" },
      { "field": "bw_atp_amt", "operator": "gt", "value": 0 }
    ]
  }
}

Search field metadata:

{
  "search": "backwage",
  "limit": 20
}

Search LCA disclosure data:

{
  "fiscalYear": 2026,
  "quarter": 1,
  "employerName": "Google",
  "state": "CA",
  "jobTitle": "software",
  "maxResults": 25
}

Build a DOL LCA employer profile:

{
  "fiscalYear": 2026,
  "quarter": 1,
  "employerName": "Google",
  "searchMode": "contains",
  "maxResults": 5000
}

Search unified DOL foreign-labor disclosures:

{
  "visaProgram": "H-2A",
  "fiscalYear": 2026,
  "fiscalQuarter": "Q1",
  "worksiteState": "IA",
  "caseStatus": "Certified",
  "maxItems": 100
}

Search PERM certifications:

{
  "visaProgram": "PERM",
  "fiscalYear": 2026,
  "fiscalQuarter": "Q1",
  "employerName": "Intel",
  "minAnnualWage": 150000,
  "maxItems": 500
}

Search OSHA inspections with joined citations:

{
  "companyName": "Walmart",
  "state": "TX",
  "includeViolations": true,
  "maxResults": 25
}

Search fatality/catastrophe construction inspections:

{
  "state": "TX",
  "naicsCode": "23",
  "inspectionType": "A",
  "dateFrom": "2024-01-01",
  "includeViolations": true,
  "maxResults": 100
}

Search SAM.gov opportunities in dry-run mode:

{
  "keywords": "cybersecurity",
  "naicsCodes": ["541512"],
  "setAsideType": "SBA",
  "postedDaysAgo": 30,
  "maxResults": 10,
  "dryRun": true
}

Search live SAM.gov opportunities after adding a SAM key:

{
  "keywords": "software development",
  "naicsCodes": ["541512", "541511"],
  "procurementTypes": ["o", "k", "r"],
  "state": "VA",
  "postedDaysAgo": 30,
  "maxResults": 100,
  "dryRun": false
}

Ask a plain-English routed question:

{
  "question": "Show OSHA inspections and citations for Walmart in TX",
  "maxResults": 10
}

Ask for SAM.gov opportunities in dry-run mode:

{
  "question": "Find cybersecurity solicitations NAICS 541512 in Virginia",
  "maxResults": 10,
  "dryRun": true
}

Ask for DOL foreign-labor disclosure records:

{
  "question": "H-2A certified farm jobs in IA SOC 45-2092 over $20 hourly",
  "maxResults": 10
}

Search Google Places for restaurants in a city:

{
  "query": "restaurants in Hillsdale, MI",
  "includedTypes": ["restaurant"],
  "maxResults": 30,
  "excludeClosed": true
}

Look up one Google place by Place ID:

{
  "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4",
  "includeAtmosphere": false
}

Data Source Reference

Background reference for sources the MCP queries (and a few it doesn't yet but agents may need to reach):

• Midwest State OSHA Programs — federal vs state-plan jurisdiction map for IL, IN, IA, KS, MI, MN, MO, NE, OH, WI; how state-plan reporting cadence affects osha_inspection_search results; what the federal OIS does and doesn't cover.

• Midwest State Business Registration Searches — Secretary of State / DFI portals, free search vs. paid bulk download, registered-agent and officer searches; IL, IN, IA, KS, MI, MN, MO, NE, OH, WI.