naftiko: 1.0.0-alpha2
info:
  label: USGS Earth Science Monitoring
  description: Workflow capability for USGS earth science monitoring combining earthquake catalog data and water resources
    data. Supports hazard assessment, natural disaster response, environmental monitoring, and scientific research workflows
    combining seismic activity data with hydrological measurements.
  tags:
  - Earthquakes
  - Water Data
  - Earth Science
  - Hazards
  - Environmental Monitoring
  - Federal Government
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    USGS_WATER_API_KEY: USGS_WATER_API_KEY
capability:
  consumes:
  - type: http
    namespace: usgs-earthquake
    baseUri: https://earthquake.usgs.gov/fdsnws/event/1
    description: USGS FDSN Event Web Service for earthquake catalog access
    resources:
    - name: earthquakes
      path: /query
      description: Earthquake catalog query
      operations:
      - name: query-earthquakes
        method: GET
        description: Query earthquake catalog with spatial, temporal, and magnitude filters
        inputParameters:
        - name: format
          in: query
          type: string
          required: false
          description: Output format (geojson, quakeml, kml, csv, text)
        - name: starttime
          in: query
          type: string
          required: false
          description: Start time (ISO 8601)
        - name: endtime
          in: query
          type: string
          required: false
          description: End time (ISO 8601)
        - name: minmagnitude
          in: query
          type: number
          required: false
          description: Minimum magnitude
        - name: maxmagnitude
          in: query
          type: number
          required: false
          description: Maximum magnitude
        - name: minlatitude
          in: query
          type: number
          required: false
          description: Southern boundary latitude
        - name: maxlatitude
          in: query
          type: number
          required: false
          description: Northern boundary latitude
        - name: minlongitude
          in: query
          type: number
          required: false
          description: Western boundary longitude
        - name: maxlongitude
          in: query
          type: number
          required: false
          description: Eastern boundary longitude
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of events to return
        - name: orderby
          in: query
          type: string
          required: false
          description: Sort order (time, magnitude)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: earthquake-count
      path: /count
      description: Count earthquakes matching query parameters
      operations:
      - name: count-earthquakes
        method: GET
        description: Count earthquakes without returning full data
        inputParameters:
        - name: starttime
          in: query
          type: string
          required: false
          description: Start time
        - name: endtime
          in: query
          type: string
          required: false
          description: End time
        - name: minmagnitude
          in: query
          type: number
          required: false
          description: Minimum magnitude
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: usgs-water
    baseUri: https://api.waterdata.usgs.gov/ogcapi/v0
    description: USGS Water Data OGC APIs
    authentication:
      type: apikey
      key: api_key
      value: '{{USGS_WATER_API_KEY}}'
      placement: query
    resources:
    - name: continuous-values
      path: /collections/continuous-values/items
      description: Real-time continuous sensor measurements
      operations:
      - name: query-continuous-values
        method: GET
        description: Query continuous water measurement data
        inputParameters:
        - name: monitoringLocationIdentifier
          in: query
          type: string
          required: false
          description: USGS monitoring location ID
        - name: parameterCode
          in: query
          type: string
          required: false
          description: USGS parameter code
        - name: datetime
          in: query
          type: string
          required: false
          description: Temporal filter (ISO 8601)
        - name: bbox
          in: query
          type: string
          required: false
          description: Bounding box for spatial filtering
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum features to return
        - name: f
          in: query
          type: string
          required: false
          description: Response format
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: daily-values
      path: /collections/daily-values/items
      description: Daily summary water data
      operations:
      - name: query-daily-values
        method: GET
        description: Query daily water data summaries
        inputParameters:
        - name: monitoringLocationIdentifier
          in: query
          type: string
          required: false
          description: USGS monitoring location ID
        - name: parameterCode
          in: query
          type: string
          required: false
          description: USGS parameter code
        - name: datetime
          in: query
          type: string
          required: false
          description: Temporal filter
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum features to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: monitoring-locations
      path: /collections/monitoring-locations/items
      description: Water monitoring station metadata
      operations:
      - name: query-monitoring-locations
        method: GET
        description: Query water monitoring locations
        inputParameters:
        - name: monitoringLocationIdentifier
          in: query
          type: string
          required: false
          description: USGS monitoring location ID
        - name: monitoringLocationType
          in: query
          type: string
          required: false
          description: Location type (Stream, Lake, Well)
        - name: stateCd
          in: query
          type: string
          required: false
          description: Two-letter state code
        - name: bbox
          in: query
          type: string
          required: false
          description: Spatial bounding box
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum features to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: earth-science-api
    description: Unified REST API for USGS earth science monitoring combining earthquake and water data.
    resources:
    - path: /v1/earthquakes
      name: earthquakes
      description: Earthquake events from USGS National Earthquake Information Center
      operations:
      - method: GET
        name: query-earthquakes
        description: Query earthquake catalog by time, location, and magnitude
        call: usgs-earthquake.query-earthquakes
        with:
          starttime: rest.starttime
          endtime: rest.endtime
          minmagnitude: rest.minmagnitude
          minlatitude: rest.minlatitude
          maxlatitude: rest.maxlatitude
          minlongitude: rest.minlongitude
          maxlongitude: rest.maxlongitude
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/earthquake-counts
      name: earthquake-counts
      description: Earthquake count statistics
      operations:
      - method: GET
        name: count-earthquakes
        description: Count earthquakes matching query parameters
        call: usgs-earthquake.count-earthquakes
        with:
          starttime: rest.starttime
          endtime: rest.endtime
          minmagnitude: rest.minmagnitude
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/water-measurements
      name: water-measurements
      description: Real-time water measurements from USGS monitoring stations
      operations:
      - method: GET
        name: query-water-measurements
        description: Get continuous water measurements from monitoring stations
        call: usgs-water.query-continuous-values
        with:
          monitoringLocationIdentifier: rest.site_id
          parameterCode: rest.parameter_code
          datetime: rest.datetime
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/daily-water-values
      name: daily-water-values
      description: Daily summary water data
      operations:
      - method: GET
        name: query-daily-water-values
        description: Get daily water data summaries
        call: usgs-water.query-daily-values
        with:
          monitoringLocationIdentifier: rest.site_id
          parameterCode: rest.parameter_code
          datetime: rest.datetime
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/monitoring-stations
      name: monitoring-stations
      description: Water monitoring station locations
      operations:
      - method: GET
        name: query-monitoring-stations
        description: Find water monitoring stations by geography
        call: usgs-water.query-monitoring-locations
        with:
          stateCd: rest.state
          bbox: rest.bbox
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: earth-science-mcp
    transport: http
    description: MCP server for AI-assisted USGS earth science monitoring, hazard assessment, and water resources analysis.
    tools:
    - name: query-earthquake-events
      description: Query the USGS earthquake catalog for seismic events. Filter by time range, geographic bounding box, or
        circular area, magnitude range, and depth. Returns GeoJSON FeatureCollection with event properties including magnitude,
        location, depth, and PAGER alert level.
      hints:
        readOnly: true
        openWorld: true
      call: usgs-earthquake.query-earthquakes
      with:
        starttime: tools.starttime
        endtime: tools.endtime
        minmagnitude: tools.minmagnitude
        maxmagnitude: tools.maxmagnitude
        minlatitude: tools.minlatitude
        maxlatitude: tools.maxlatitude
        minlongitude: tools.minlongitude
        maxlongitude: tools.maxlongitude
        latitude: tools.latitude
        longitude: tools.longitude
        maxradiuskm: tools.maxradiuskm
        limit: tools.limit
        orderby: tools.orderby
      outputParameters:
      - type: object
        mapping: $.
    - name: count-seismic-events
      description: Count earthquakes in the USGS catalog without retrieving full event data. Useful for assessing seismic
        activity levels in a region or time period.
      hints:
        readOnly: true
        openWorld: true
      call: usgs-earthquake.count-earthquakes
      with:
        starttime: tools.starttime
        endtime: tools.endtime
        minmagnitude: tools.minmagnitude
      outputParameters:
      - type: object
        mapping: $.
    - name: get-streamflow-data
      description: Get real-time streamflow and water level measurements from a USGS monitoring station. Specify station ID
        (e.g., USGS-01646500) and optional parameter code (00060 = discharge cfs, 00065 = gage height ft).
      hints:
        readOnly: true
        openWorld: true
      call: usgs-water.query-continuous-values
      with:
        monitoringLocationIdentifier: tools.site_id
        parameterCode: tools.parameter_code
        datetime: tools.datetime
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.
    - name: get-daily-water-statistics
      description: Get historical daily water data (mean, max, min values) for a USGS monitoring station. Useful for flood
        analysis, drought assessment, and long-term trend analysis.
      hints:
        readOnly: true
        openWorld: true
      call: usgs-water.query-daily-values
      with:
        monitoringLocationIdentifier: tools.site_id
        parameterCode: tools.parameter_code
        datetime: tools.datetime
      outputParameters:
      - type: object
        mapping: $.
    - name: find-usgs-monitoring-stations
      description: Find USGS water monitoring stations by state, type, or geographic bounding box. Returns location details
        including coordinates, HUC codes, and monitoring parameters available at each station.
      hints:
        readOnly: true
        openWorld: true
      call: usgs-water.query-monitoring-locations
      with:
        stateCd: tools.state
        monitoringLocationType: tools.type
        bbox: tools.bbox
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.