USDA Food and Agriculture Data Research

naftiko: "1.0.0-alpha1"

info:
  label: "USDA Food and Agriculture Data Research"
  description: >-
    Unified capability for food and agricultural data research workflows
    combining USDA FoodData Central nutrient data with NASS agricultural
    production statistics. Used by nutritionists, food researchers, public
    health analysts, and agricultural economists to access comprehensive USDA
    food and farm data.
  tags:
    - Food
    - Nutrition
    - Agriculture
    - Statistics
    - USDA
    - Federal Government
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      FDC_API_KEY: FDC_API_KEY
      NASS_API_KEY: NASS_API_KEY

capability:
  consumes:
    - import: fdc
      location: ./shared/usda-fooddata-central.yaml
    - import: nass
      location: ./shared/usda-nass-quickstats.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: usda-food-ag-api
      description: "Unified REST API for USDA food nutrition and agricultural statistics research."
      resources:
        - path: /v1/foods/search
          name: food-search
          description: "Search USDA FoodData Central for food items"
          operations:
            - method: GET
              name: search-foods
              description: "Search for foods by keyword across all USDA food data types"
              call: "fdc.search-foods"
              with:
                query: "rest.query"
                dataType: "rest.dataType"
                pageSize: "rest.pageSize"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/foods/{fdcId}
          name: food-detail
          description: "Retrieve full nutrient profile for a specific food"
          operations:
            - method: GET
              name: get-food
              description: "Get food item with complete nutrient data"
              call: "fdc.get-food-by-id"
              with:
                fdcId: "rest.fdcId"
                format: "rest.format"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/nutrients
          name: nutrients
          description: "List all nutrients tracked in FoodData Central"
          operations:
            - method: GET
              name: list-nutrients
              description: "Get all available nutrients"
              call: "fdc.get-nutrients"
              with: {}
              outputParameters:
                - type: array
                  mapping: "$."

        - path: /v1/agriculture/statistics
          name: ag-statistics
          description: "Query USDA NASS agricultural production statistics"
          operations:
            - method: GET
              name: get-ag-statistics
              description: "Get agricultural commodity production statistics"
              call: "nass.get-agricultural-statistics"
              with:
                commodity_desc: "rest.commodity"
                statisticcat_desc: "rest.category"
                year: "rest.year"
                state_name: "rest.state"
                agg_level_desc: "rest.aggLevel"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/agriculture/parameters
          name: ag-parameters
          description: "Look up valid values for statistics query parameters"
          operations:
            - method: GET
              name: get-parameter-values
              description: "Get valid values for a NASS statistics parameter"
              call: "nass.get-parameter-values"
              with:
                param: "rest.param"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: usda-food-ag-mcp
      transport: http
      description: "MCP server for AI-assisted food nutrition and agricultural data research."
      tools:
        - name: search-foods
          description: "Search USDA FoodData Central for food items using keywords"
          hints:
            readOnly: true
            idempotent: true
          call: "fdc.search-foods"
          with:
            query: "tools.query"
            dataType: "tools.data_type"
            pageSize: "tools.page_size"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-food-nutrition
          description: "Get detailed nutrient profile for a specific food item from USDA FoodData Central"
          hints:
            readOnly: true
            idempotent: true
          call: "fdc.get-food-by-id"
          with:
            fdcId: "tools.fdc_id"
            format: "tools.format"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-nutrients
          description: "List all nutrients tracked in USDA FoodData Central including IDs, names, and units"
          hints:
            readOnly: true
            idempotent: true
          call: "fdc.get-nutrients"
          with: {}
          outputParameters:
            - type: array
              mapping: "$."

        - name: get-crop-production-statistics
          description: "Query USDA NASS for crop production statistics by commodity, year, and state"
          hints:
            readOnly: true
            idempotent: true
          call: "nass.get-agricultural-statistics"
          with:
            commodity_desc: "tools.commodity"
            statisticcat_desc: "tools.category"
            year: "tools.year"
            state_name: "tools.state"
            agg_level_desc: "tools.agg_level"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-livestock-statistics
          description: "Query USDA NASS for livestock and animal production statistics"
          hints:
            readOnly: true
            idempotent: true
          call: "nass.get-agricultural-statistics"
          with:
            commodity_desc: "tools.commodity"
            statisticcat_desc: "tools.category"
            year: "tools.year"
            state_name: "tools.state"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-nass-parameter-values
          description: "Look up valid values for NASS statistics query parameters to build accurate queries"
          hints:
            readOnly: true
            idempotent: true
          call: "nass.get-parameter-values"
          with:
            param: "tools.param_name"
          outputParameters:
            - type: object
              mapping: "$."