naftiko: "1.0.0-alpha1"

info:
  label: "FastDOL Employer Compliance Research"
  description: "Interactive research workflow for journalists, ESG analysts, underwriters, and compliance teams: search a US employer, retrieve cross-agency enforcement profile (OSHA, WHD, EPA, MSHA, NLRB, SEC, etc.), drill into inspections and violations, benchmark against industry peers, and view risk-history."
  tags:
    - FastDOL
    - Federal Enforcement
    - Workplace Safety
    - Compliance
    - OSHA
    - WHD
    - Public Records
    - Research
  created: "2026-05-16"
  modified: "2026-05-16"

binds:
  - namespace: env
    keys:
      FASTDOL_API_KEY: FASTDOL_API_KEY

capability:
  consumes:
    - import: fastdol
      location: ./shared/fastdol.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: employer-compliance-research-api
      description: "Unified REST API for cross-agency employer compliance research."
      resources:
        - path: /v1/employers
          name: employers
          description: "Employer search and profile lookup."
          operations:
            - method: GET
              name: search-employers
              description: "Search employers by name, EIN, ZIP, state, or NAICS."
              call: "fastdol.search-employers"
              with:
                name: "rest.name"
                ein: "rest.ein"
                state: "rest.state"
                zip: "rest.zip"
                naics: "rest.naics"
                limit: "rest.limit"
                offset: "rest.offset"
              outputParameters:
                - { type: object, mapping: "$." }

            - method: GET
              name: get-employer
              description: "Get a full cross-agency employer profile."
              call: "fastdol.get-employer"
              with:
                employer_id: "rest.employer_id"
              outputParameters:
                - { type: object, mapping: "$." }

            - method: GET
              name: get-employer-by-ein
              description: "Look up an employer by EIN."
              call: "fastdol.get-employer-by-ein"
              with:
                ein: "rest.ein"
              outputParameters:
                - { type: object, mapping: "$." }

            - method: GET
              name: get-parent-company
              description: "Roll up enforcement across a parent company's locations."
              call: "fastdol.get-parent-company"
              with:
                parent_name: "rest.parent_name"
              outputParameters:
                - { type: object, mapping: "$." }

        - path: /v1/enforcement
          name: enforcement
          description: "Cross-agency enforcement records for an employer."
          operations:
            - method: GET
              name: get-inspections
              description: "List OSHA inspections."
              call: "fastdol.get-inspections"
              with: { employer_id: "rest.employer_id" }
              outputParameters: [ { type: object, mapping: "$." } ]

            - method: GET
              name: get-severe-injuries
              description: "List OSHA severe-injury reports."
              call: "fastdol.get-severe-injuries"
              with: { employer_id: "rest.employer_id" }
              outputParameters: [ { type: object, mapping: "$." } ]

            - method: GET
              name: get-whd-cases
              description: "List WHD wage theft cases."
              call: "fastdol.get-whd-cases"
              with: { employer_id: "rest.employer_id" }
              outputParameters: [ { type: object, mapping: "$." } ]

            - method: GET
              name: get-osha-accidents
              description: "List OSHA accident reports."
              call: "fastdol.get-osha-accidents"
              with: { employer_id: "rest.employer_id" }
              outputParameters: [ { type: object, mapping: "$." } ]

            - method: GET
              name: get-sec-enforcement
              description: "List SEC enforcement actions for the parent."
              call: "fastdol.get-sec-enforcement"
              with: { employer_id: "rest.employer_id" }
              outputParameters: [ { type: object, mapping: "$." } ]

        - path: /v1/violations
          name: violations
          description: "Citation-level OSHA inspection detail."
          operations:
            - method: GET
              name: get-violations
              description: "Citation-level violations for an OSHA inspection."
              call: "fastdol.get-violations"
              with: { activity_nr: "rest.activity_nr" }
              outputParameters: [ { type: object, mapping: "$." } ]

        - path: /v1/risk
          name: risk
          description: "Risk scoring and history."
          operations:
            - method: GET
              name: get-risk-history
              description: "Month-over-month risk-score history."
              call: "fastdol.get-risk-history"
              with: { employer_id: "rest.employer_id" }
              outputParameters: [ { type: object, mapping: "$." } ]

            - method: GET
              name: get-peers
              description: "Peer employers in the same NAICS code and state."
              call: "fastdol.get-peers"
              with: { employer_id: "rest.employer_id" }
              outputParameters: [ { type: object, mapping: "$." } ]

        - path: /v1/industries
          name: industries
          description: "NAICS industry metadata and BLS SOII benchmarks."
          operations:
            - method: GET
              name: list-naics-codes
              description: "List all known NAICS codes."
              call: "fastdol.list-naics-codes"
              outputParameters: [ { type: object, mapping: "$." } ]
            - method: GET
              name: get-industry
              description: "Get industry metadata for a NAICS-4 code."
              call: "fastdol.get-industry"
              with: { naics4: "rest.naics4" }
              outputParameters: [ { type: object, mapping: "$." } ]

        - path: /v1/stats
          name: stats
          description: "Aggregate state, industry, and nursing-home stats."
          operations:
            - method: GET
              name: states-index
              description: "Index of US states with aggregate stats."
              call: "fastdol.states-index"
              outputParameters: [ { type: object, mapping: "$." } ]
            - method: GET
              name: state-stats
              description: "Aggregate stats for a state."
              call: "fastdol.state-stats"
              with: { code: "rest.code" }
              outputParameters: [ { type: object, mapping: "$." } ]
            - method: GET
              name: industries-index
              description: "Index of industries with aggregate stats."
              call: "fastdol.industries-index"
              outputParameters: [ { type: object, mapping: "$." } ]
            - method: GET
              name: industry-stats
              description: "Aggregate stats for a NAICS code."
              call: "fastdol.industry-stats"
              with: { naics: "rest.naics" }
              outputParameters: [ { type: object, mapping: "$." } ]
            - method: GET
              name: nursing-homes-index
              description: "Top-level nursing-home index."
              call: "fastdol.nursing-homes-index"
              outputParameters: [ { type: object, mapping: "$." } ]
            - method: GET
              name: nursing-homes-by-state
              description: "Nursing homes for a state."
              call: "fastdol.nursing-homes-by-state"
              with: { state_code: "rest.state_code" }
              outputParameters: [ { type: object, mapping: "$." } ]
            - method: GET
              name: nursing-home-detail
              description: "Detail for a single CMS CCN."
              call: "fastdol.nursing-home-detail"
              with: { ccn: "rest.ccn" }
              outputParameters: [ { type: object, mapping: "$." } ]

    - type: mcp
      port: 9090
      namespace: employer-compliance-research-mcp
      transport: http
      description: "MCP server for AI-assisted employer compliance research across FastDOL's 16 federal data sources."
      tools:
        - name: search-employers
          description: "Search the 2.3M-employer FastDOL index by name, EIN, ZIP, state, or NAICS."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.search-employers"
          with:
            name: "tools.name"
            ein: "tools.ein"
            state: "tools.state"
            zip: "tools.zip"
            naics: "tools.naics"
            limit: "tools.limit"
            offset: "tools.offset"
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-employer
          description: "Get a single employer's full cross-agency profile."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-employer"
          with: { employer_id: "tools.employer_id" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-employer-by-ein
          description: "Look up an employer by exact EIN."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-employer-by-ein"
          with: { ein: "tools.ein" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-parent-company
          description: "Roll up enforcement across all locations of a parent company."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-parent-company"
          with: { parent_name: "tools.parent_name" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-inspections
          description: "List OSHA inspections for an employer."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-inspections"
          with: { employer_id: "tools.employer_id" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-severe-injuries
          description: "List OSHA severe-injury reports for an employer."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-severe-injuries"
          with: { employer_id: "tools.employer_id" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-whd-cases
          description: "List WHD wage theft cases for an employer."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-whd-cases"
          with: { employer_id: "tools.employer_id" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-osha-accidents
          description: "List OSHA accidents for an employer."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-osha-accidents"
          with: { employer_id: "tools.employer_id" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-sec-enforcement
          description: "List SEC enforcement actions for an employer's public-company parent."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-sec-enforcement"
          with: { employer_id: "tools.employer_id" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-violations
          description: "Citation-level violations for an OSHA inspection activity number."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-violations"
          with: { activity_nr: "tools.activity_nr" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-risk-history
          description: "Month-over-month risk-score history for an employer."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-risk-history"
          with: { employer_id: "tools.employer_id" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-peers
          description: "Peer employers in the same NAICS code and state."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-peers"
          with: { employer_id: "tools.employer_id" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: list-naics-codes
          description: "List all known NAICS codes."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.list-naics-codes"
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: get-industry
          description: "Get industry metadata and BLS SOII benchmark for a NAICS-4 code."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.get-industry"
          with: { naics4: "tools.naics4" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: states-index
          description: "Index of US states with aggregate enforcement stats."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.states-index"
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: state-stats
          description: "Aggregate enforcement stats for a US state."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.state-stats"
          with: { code: "tools.code" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: industries-index
          description: "Index of industries with aggregate enforcement stats."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.industries-index"
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: industry-stats
          description: "Aggregate enforcement stats for a NAICS code."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.industry-stats"
          with: { naics: "tools.naics" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: nursing-homes-index
          description: "Index of CMS-certified nursing homes."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.nursing-homes-index"
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: nursing-homes-by-state
          description: "CMS nursing homes for a US state."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.nursing-homes-by-state"
          with: { state_code: "tools.state_code" }
          outputParameters: [ { type: object, mapping: "$." } ]

        - name: nursing-home-detail
          description: "Detail for a CMS nursing-home CCN."
          hints: { readOnly: true, openWorld: true }
          call: "fastdol.nursing-home-detail"
          with: { ccn: "tools.ccn" }
          outputParameters: [ { type: object, mapping: "$." } ]