naftiko: 1.0.0-alpha2
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-06'
binds:
- namespace: env
  keys:
    BLS_REGISTRATION_KEY: BLS_REGISTRATION_KEY
capability:
  consumes:
  - type: http
    namespace: bls-public-data
    baseUri: https://api.bls.gov/publicAPI/v2
    description: BLS Public Data API for time series statistical data
    authentication:
      type: apikey
      key: registrationkey
      value: '{{BLS_REGISTRATION_KEY}}'
      placement: query
    resources:
    - name: time-series
      path: /timeseries/data
      description: Time series data retrieval for BLS statistical series
      operations:
      - name: get-multiple-time-series
        method: POST
        description: Retrieve time series data for one or more BLS series IDs
        inputParameters:
        - name: seriesid
          in: body
          type: array
          required: true
          description: Array of BLS series IDs (max 50)
        - name: startyear
          in: body
          type: string
          required: false
          description: Start year (4-digit)
        - name: endyear
          in: body
          type: string
          required: false
          description: End year (4-digit)
        - name: catalog
          in: body
          type: boolean
          required: false
          description: Include series catalog metadata
        - name: calculations
          in: body
          type: boolean
          required: false
          description: Include net change and percent change calculations
        - name: annualaverage
          in: body
          type: boolean
          required: false
          description: Include annual average values
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-single-time-series
        method: GET
        description: Retrieve time series data for a single BLS series ID
        inputParameters:
        - name: seriesId
          in: path
          type: string
          required: true
          description: BLS series identifier
        - name: startyear
          in: query
          type: string
          required: false
          description: Start year for data range
        - name: endyear
          in: query
          type: string
          required: false
          description: End year for data range
        - name: catalog
          in: query
          type: boolean
          required: false
          description: Include catalog information
        - name: calculations
          in: query
          type: boolean
          required: false
          description: Include statistical calculations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: surveys
      path: /surveys
      description: BLS survey discovery and metadata
      operations:
      - name: list-surveys
        method: GET
        description: List all available BLS surveys with abbreviations and names
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-survey-details
        method: GET
        description: Get detailed metadata for a specific BLS survey
        inputParameters:
        - name: surveyAbbreviation
          in: path
          type: string
          required: true
          description: Two-letter BLS survey abbreviation code (e.g., CU, LN, CE)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: popular-series
      path: /timeseries/popular
      description: Most popular BLS series identifiers
      operations:
      - name: get-popular-series
        method: GET
        description: Retrieve the 25 most popular BLS series IDs
        inputParameters:
        - name: survey
          in: query
          type: string
          required: false
          description: Filter by survey abbreviation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  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: $.