naftiko: 1.0.0-alpha2
info:
  label: USDA ARS Agricultural Research Data
  description: Unified capability for USDA Agricultural Research Service data access, combining FoodData Central nutritional
    data with Ag Data Commons agricultural research dataset discovery. Supports nutritionists, agricultural researchers, food
    scientists, and data analysts.
  tags:
  - Food Data
  - Nutrition
  - Agricultural Research
  - Open Data
  - Federal Government
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    USDA_FDC_API_KEY: USDA_FDC_API_KEY
capability:
  consumes:
  - type: http
    namespace: usda-fdc
    baseUri: https://api.nal.usda.gov/fdc/v1
    description: USDA FoodData Central REST API.
    authentication:
      type: apikey
      key: api_key
      value: '{{USDA_FDC_API_KEY}}'
      placement: query
    resources:
    - name: food-search
      path: /foods/search
      description: Search foods by keywords
      operations:
      - name: search-foods
        method: GET
        description: Search for foods matching keywords
        inputParameters:
        - name: query
          in: query
          type: string
          required: true
          description: Search keywords
        - name: dataType
          in: query
          type: string
          required: false
          description: Filter by data type (Foundation, Branded, SR Legacy, etc.)
        - name: pageSize
          in: query
          type: integer
          required: false
          description: Results per page (max 200)
        - name: pageNumber
          in: query
          type: integer
          required: false
          description: Page number
        - name: brandOwner
          in: query
          type: string
          required: false
          description: Filter by brand owner
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: food-detail
      path: /food/{fdcId}
      description: Individual food record
      operations:
      - name: get-food
        method: GET
        description: Get detailed nutritional data for a food by FDC ID
        inputParameters:
        - name: fdcId
          in: path
          type: integer
          required: true
          description: FoodData Central ID
        - name: format
          in: query
          type: string
          required: false
          description: abridged or full
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: foods-list
      path: /foods/list
      description: Browse foods list
      operations:
      - name: list-foods
        method: GET
        description: Get paginated list of foods in abridged format
        inputParameters:
        - name: dataType
          in: query
          type: string
          required: false
          description: Filter by data type
        - name: pageSize
          in: query
          type: integer
          required: false
          description: Results per page
        - name: pageNumber
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
  - type: http
    namespace: usda-adc
    baseUri: https://data.nal.usda.gov
    description: USDA Ag Data Commons CKAN API.
    resources:
    - name: dataset-search
      path: /api/action/package_search
      description: Search agricultural research datasets
      operations:
      - name: search-datasets
        method: GET
        description: Search Ag Data Commons catalog for agricultural research datasets
        inputParameters:
        - name: q
          in: query
          type: string
          required: false
          description: Search query
        - name: fq
          in: query
          type: string
          required: false
          description: Filter query
        - name: rows
          in: query
          type: integer
          required: false
          description: Number of results (max 1000)
        - name: start
          in: query
          type: integer
          required: false
          description: Offset for pagination
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: dataset-detail
      path: /api/action/package_show
      description: Dataset detail by ID
      operations:
      - name: get-dataset
        method: GET
        description: Get full metadata for a specific dataset
        inputParameters:
        - name: id
          in: query
          type: string
          required: true
          description: Dataset ID or name slug
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: datastore-search
      path: /api/action/datastore_search
      description: Query data records within a dataset resource
      operations:
      - name: query-datastore
        method: GET
        description: Query tabular data records within a published dataset
        inputParameters:
        - name: resource_id
          in: query
          type: string
          required: true
          description: Resource ID to query
        - name: q
          in: query
          type: string
          required: false
          description: Search query
        - name: limit
          in: query
          type: integer
          required: false
          description: Rows to return
        - name: offset
          in: query
          type: integer
          required: false
          description: Pagination offset
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: ars-data-api
    description: Unified REST API for USDA ARS food and agricultural research data.
    resources:
    - path: /v1/foods/search
      name: food-search
      description: Food nutritional data search
      operations:
      - method: GET
        name: search-foods
        description: Search USDA FoodData Central for nutritional data
        call: usda-fdc.search-foods
        with:
          query: rest.query
          dataType: rest.dataType
          pageSize: rest.pageSize
          pageNumber: rest.pageNumber
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/foods/{fdcId}
      name: food
      description: Individual food nutritional record
      operations:
      - method: GET
        name: get-food
        description: Get full nutritional data for a specific food
        call: usda-fdc.get-food
        with:
          fdcId: rest.fdcId
          format: full
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/research/datasets
      name: datasets
      description: Agricultural research datasets
      operations:
      - method: GET
        name: search-datasets
        description: Search Ag Data Commons for research datasets
        call: usda-adc.search-datasets
        with:
          q: rest.q
          rows: rest.rows
          start: rest.start
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/research/datasets/{id}
      name: dataset
      description: Research dataset detail
      operations:
      - method: GET
        name: get-dataset
        description: Get full metadata for a research dataset
        call: usda-adc.get-dataset
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: ars-data-mcp
    transport: http
    description: MCP server for AI-assisted USDA ARS food and agricultural research data access.
    tools:
    - name: search-foods
      description: Search USDA FoodData Central for foods by name or keyword. Returns nutritional data from Foundation, SR
        Legacy, Survey, and Branded food databases.
      hints:
        readOnly: true
        openWorld: true
      call: usda-fdc.search-foods
      with:
        query: tools.query
        dataType: tools.dataType
        pageSize: tools.pageSize
      outputParameters:
      - type: object
        mapping: $.
    - name: get-food-nutrition
      description: Get detailed nutritional composition (calories, macros, vitamins, minerals) for a specific food item by
        its USDA FDC ID.
      hints:
        readOnly: true
        openWorld: false
      call: usda-fdc.get-food
      with:
        fdcId: tools.fdcId
        format: full
      outputParameters:
      - type: object
        mapping: $.
    - name: browse-foundation-foods
      description: Browse USDA Foundation Foods — the highest quality nutritional data with detailed metadata and extended
        nutrient values.
      hints:
        readOnly: true
        openWorld: true
      call: usda-fdc.list-foods
      with:
        dataType: Foundation
        pageSize: tools.pageSize
        pageNumber: tools.pageNumber
      outputParameters:
      - type: array
        mapping: $.
    - name: search-research-datasets
      description: Search USDA Ag Data Commons for agricultural research datasets covering soil health, crop genetics, animal
        production, food safety, and more.
      hints:
        readOnly: true
        openWorld: true
      call: usda-adc.search-datasets
      with:
        q: tools.q
        rows: tools.rows
      outputParameters:
      - type: object
        mapping: $.
    - name: get-research-dataset
      description: Get full metadata and download links for a specific USDA research dataset
      hints:
        readOnly: true
        openWorld: false
      call: usda-adc.get-dataset
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: query-dataset-records
      description: Query tabular data records within a published USDA research dataset (for datasets with structured/tabular
        data in the Ag Data Commons datastore).
      hints:
        readOnly: true
        openWorld: false
      call: usda-adc.query-datastore
      with:
        resource_id: tools.resource_id
        q: tools.q
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.