BLS Labor Statistics Data Access

naftiko: "1.0.0-alpha1"

info:
  label: BLS Labor Statistics Data Access
  description: >-
    Unified capability for accessing Bureau of Labor Statistics time series data,
    including employment, unemployment, inflation (CPI), wages, and occupational
    statistics. Designed for economic researchers, HR analysts, policy teams, and
    data journalists who need programmatic access to authoritative US labor data.
  tags:
    - Federal Government
    - Labor Statistics
    - Economic Data
    - Employment
    - Unemployment
    - Consumer Price Index
    - Wages
    - Open Data
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      BLS_REGISTRATION_KEY: BLS_REGISTRATION_KEY

capability:
  consumes:
    - import: bls-public-data
      location: ./shared/bls-public-data-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: bls-labor-statistics-api
      description: Unified REST API for BLS labor statistics data access.
      resources:
        - path: /v1/time-series
          name: time-series
          description: Query BLS statistical time series data
          operations:
            - method: POST
              name: query-time-series
              description: Retrieve time series data for one or more BLS series IDs
              call: "bls-public-data.get-multiple-time-series"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/time-series/{seriesId}
          name: time-series-item
          description: Get time series data for a specific series
          operations:
            - method: GET
              name: get-series-data
              description: Retrieve historical data for a specific BLS series
              call: "bls-public-data.get-single-time-series"
              with:
                seriesId: "rest.seriesId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/surveys
          name: surveys
          description: BLS survey catalog
          operations:
            - method: GET
              name: list-surveys
              description: List all BLS survey programs and abbreviations
              call: "bls-public-data.list-surveys"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/surveys/{surveyAbbreviation}
          name: survey-detail
          description: Survey metadata
          operations:
            - method: GET
              name: get-survey
              description: Get metadata for a specific BLS survey
              call: "bls-public-data.get-survey-details"
              with:
                surveyAbbreviation: "rest.surveyAbbreviation"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/popular-series
          name: popular-series
          description: Most popular BLS series
          operations:
            - method: GET
              name: get-popular-series
              description: Get the 25 most popular BLS series identifiers
              call: "bls-public-data.get-popular-series"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: bls-labor-statistics-mcp
      transport: http
      description: MCP server for AI-assisted access to BLS labor statistics data.
      tools:
        - name: query-time-series
          description: >-
            Query BLS time series data for employment, unemployment, CPI, wages,
            or any other BLS statistical series by series ID and date range
          hints:
            readOnly: true
            openWorld: true
          call: "bls-public-data.get-multiple-time-series"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-series-data
          description: >-
            Retrieve historical data for a single BLS series ID (e.g.,
            LNS14000000 for unemployment rate, CUUR0000SA0 for CPI)
          hints:
            readOnly: true
            openWorld: true
          call: "bls-public-data.get-single-time-series"
          with:
            seriesId: "tools.seriesId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-surveys
          description: List all BLS survey programs to discover available data types
          hints:
            readOnly: true
            openWorld: false
          call: "bls-public-data.list-surveys"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-survey-details
          description: Get detailed metadata for a specific BLS survey program
          hints:
            readOnly: true
            openWorld: false
          call: "bls-public-data.get-survey-details"
          with:
            surveyAbbreviation: "tools.surveyAbbreviation"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-popular-series
          description: >-
            Get the 25 most popular BLS series IDs, useful for discovering
            commonly referenced economic indicators like unemployment rate and CPI
          hints:
            readOnly: true
            openWorld: false
          call: "bls-public-data.get-popular-series"
          outputParameters:
            - type: object
              mapping: "$."