USACE Water Management

naftiko: "1.0.0-alpha1"

info:
  label: "USACE Water Management"
  description: >-
    Workflow capability for USACE water management operations including
    reservoir monitoring, flood control, navigation, and water quality.
    Combines CWMS time series data, location metadata, reservoir pool levels,
    and field measurements for comprehensive water resource management workflows.
  tags:
    - Water Management
    - Hydrology
    - Reservoirs
    - Flood Control
    - Navigation
    - Federal Government
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys: {}

capability:
  consumes:
    - import: cwms
      location: ./shared/usace-cwms-data-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: water-management-api
      description: "Unified REST API for USACE water management data and monitoring."
      resources:
        - path: /v1/timeseries
          name: timeseries
          description: "Water management time series measurements"
          operations:
            - method: GET
              name: get-time-series
              description: "Get time series data for a water management location"
              call: "cwms.get-time-series"
              with:
                office: "rest.office"
                name: "rest.name"
                begin: "rest.begin"
                end: "rest.end"
                unit: "rest.unit"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/timeseries/catalog
          name: timeseries-catalog
          description: "Catalog of available time series"
          operations:
            - method: GET
              name: get-time-series-catalog
              description: "Browse available time series identifiers"
              call: "cwms.get-time-series-catalog"
              with:
                office: "rest.office"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/locations
          name: locations
          description: "Water monitoring locations"
          operations:
            - method: GET
              name: get-locations
              description: "Get USACE monitoring locations"
              call: "cwms.get-locations"
              with:
                office: "rest.office"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/locations/{locationId}
          name: location
          description: "Single monitoring location"
          operations:
            - method: GET
              name: get-location
              description: "Get details for a specific monitoring location"
              call: "cwms.get-location"
              with:
                locationId: "rest.locationId"
                office: "rest.office"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/locations/catalog
          name: locations-catalog
          description: "Searchable location catalog"
          operations:
            - method: GET
              name: get-location-catalog
              description: "Browse all available USACE locations"
              call: "cwms.get-location-catalog"
              with:
                office: "rest.office"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/levels
          name: levels
          description: "Location levels and pool data"
          operations:
            - method: GET
              name: get-levels
              description: "Get location levels and flood stage thresholds"
              call: "cwms.get-levels"
              with:
                office: "rest.office"
                location-id: "rest.location_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/ratings
          name: ratings
          description: "Stage-discharge rating curves"
          operations:
            - method: GET
              name: get-ratings
              description: "Get rating curves for stage to discharge conversion"
              call: "cwms.get-ratings"
              with:
                office: "rest.office"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/projects
          name: projects
          description: "USACE projects and reservoirs"
          operations:
            - method: GET
              name: get-projects
              description: "Get USACE water projects"
              call: "cwms.get-projects"
              with:
                office: "rest.office"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pools
          name: pools
          description: "Reservoir pool definitions"
          operations:
            - method: GET
              name: get-pools
              description: "Get reservoir pool storage zones"
              call: "cwms.get-pools"
              with:
                office: "rest.office"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/measurements
          name: measurements
          description: "Field measurements"
          operations:
            - method: GET
              name: get-measurements
              description: "Get field measurements from hydrographer site visits"
              call: "cwms.get-measurements"
              with:
                office: "rest.office"
                location-id: "rest.location_id"
                begin: "rest.begin"
                end: "rest.end"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/offices
          name: offices
          description: "USACE district offices"
          operations:
            - method: GET
              name: get-offices
              description: "List USACE district offices"
              call: "cwms.get-offices"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: water-management-mcp
      transport: http
      description: "MCP server for AI-assisted USACE water management monitoring, flood risk analysis, and reservoir operations."
      tools:
        - name: get-water-time-series
          description: >-
            Get time series water measurements from a USACE monitoring location.
            Retrieves streamflow, stage, reservoir elevation, temperature, and
            other parameters. Specify office, time series name, and time range.
          hints:
            readOnly: true
            openWorld: true
          call: "cwms.get-time-series"
          with:
            office: "tools.office"
            name: "tools.name"
            begin: "tools.begin"
            end: "tools.end"
            unit: "tools.unit"
          outputParameters:
            - type: object
              mapping: "$."
        - name: browse-time-series-catalog
          description: >-
            Browse the catalog of available USACE time series identifiers.
            Useful for discovering what data is available for a district office
            before retrieving actual measurements.
          hints:
            readOnly: true
            openWorld: true
          call: "cwms.get-time-series-catalog"
          with:
            office: "tools.office"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-monitoring-locations
          description: >-
            Get USACE water monitoring locations with geographic coordinates
            and metadata. Filter by district office to scope results.
          hints:
            readOnly: true
            openWorld: true
          call: "cwms.get-locations"
          with:
            office: "tools.office"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-monitoring-location-details
          description: >-
            Get detailed information for a specific USACE monitoring location
            including coordinates, elevation datum, state, county, and description.
          hints:
            readOnly: true
            openWorld: false
          call: "cwms.get-location"
          with:
            locationId: "tools.location_id"
            office: "tools.office"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-flood-stage-levels
          description: >-
            Get location levels including flood stage thresholds, flood control
            pools, and operational levels for USACE monitoring locations and
            reservoirs. Essential for flood risk assessment.
          hints:
            readOnly: true
            openWorld: true
          call: "cwms.get-levels"
          with:
            office: "tools.office"
            location-id: "tools.location_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-stage-discharge-ratings
          description: >-
            Get rating curves used to convert stage (water level) measurements
            to discharge (streamflow) values. Essential for computing streamflow
            from continuous stage data.
          hints:
            readOnly: true
            openWorld: true
          call: "cwms.get-ratings"
          with:
            office: "tools.office"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-usace-projects
          description: >-
            Get USACE water resource projects including reservoirs, navigation
            projects, and flood control structures with operational parameters.
          hints:
            readOnly: true
            openWorld: true
          call: "cwms.get-projects"
          with:
            office: "tools.office"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-reservoir-pools
          description: >-
            Get reservoir pool definitions including conservation pool, flood
            control pool, and surcharge storage zones for USACE reservoirs.
          hints:
            readOnly: true
            openWorld: true
          call: "cwms.get-pools"
          with:
            office: "tools.office"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-field-measurements
          description: >-
            Get field measurements collected by USACE hydrographers during site
            visits. These include streamflow discharge measurements used for
            rating curve development and validation.
          hints:
            readOnly: true
            openWorld: true
          call: "cwms.get-measurements"
          with:
            office: "tools.office"
            location-id: "tools.location_id"
            begin: "tools.begin"
            end: "tools.end"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-usace-offices
          description: >-
            List all USACE district offices with their identifiers.
            Use to find the office ID needed to scope other queries.
          hints:
            readOnly: true
            openWorld: true
          call: "cwms.get-offices"
          outputParameters:
            - type: object
              mapping: "$."