naftiko: 1.0.0-alpha2
info:
  label: USACE Water Data
  description: Unified water data capability composing USACE CWMS Data API resources for water resource monitoring, flood
    forecasting, reservoir operations, and hydrological analysis. Used by water managers, flood forecasters, environmental
    engineers, and researchers accessing USACE real-time and historical water data.
  tags:
  - Water Resources
  - Federal Government
  - Flood Forecasting
  - Reservoir Operations
  - Hydrological Data
  - Open Data
  created: '2026-05-03'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: cwms-data
    baseUri: https://cwms-data.usace.army.mil/cwms-data
    description: USACE CWMS Data API - public water management data
    resources:
    - name: timeseries
      path: /timeseries
      description: Water management timeseries data (flow, stage, precipitation)
      operations:
      - name: get-timeseries
        method: GET
        description: Retrieve timeseries values for a specific location and parameter
        inputParameters:
        - name: name
          in: query
          type: string
          required: true
          description: Timeseries identifier (e.g., TULA.Flow.Inst.1Hour.0.CBT-RAW)
        - name: office
          in: query
          type: string
          required: false
          description: Owning office identifier
        - name: unit
          in: query
          type: string
          required: false
          description: Unit of measure for values
        - name: begin
          in: query
          type: string
          required: false
          description: Start time (ISO 8601 or epoch ms)
        - name: end
          in: query
          type: string
          required: false
          description: End time (ISO 8601 or epoch ms)
        - name: page-size
          in: query
          type: integer
          required: false
          description: Records per page
        - name: page
          in: query
          type: string
          required: false
          description: Pagination cursor
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-timeseries-catalog
        method: GET
        description: Get catalog of available timeseries identifiers
        inputParameters:
        - name: office
          in: query
          type: string
          required: false
          description: Filter by office
        - name: timeseries-id-like
          in: query
          type: string
          required: false
          description: Filter by ID pattern (SQL LIKE syntax)
        - name: page-size
          in: query
          type: integer
          required: false
          description: Records per page
        - name: page
          in: query
          type: string
          required: false
          description: Pagination cursor
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: locations
      path: /locations
      description: CWMS monitored locations (streams, reservoirs, gages)
      operations:
      - name: get-locations
        method: GET
        description: List all CWMS locations, optionally filtered by office
        inputParameters:
        - name: office
          in: query
          type: string
          required: false
          description: Filter by office identifier
        - name: unit
          in: query
          type: string
          required: false
          description: Unit system (EN or SI)
        - name: page-size
          in: query
          type: integer
          required: false
          description: Records per page
        - name: page
          in: query
          type: string
          required: false
          description: Pagination cursor
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-location
        method: GET
        description: Get details for a specific CWMS location
        inputParameters:
        - name: location-id
          in: path
          type: string
          required: true
          description: Location identifier
        - name: office
          in: query
          type: string
          required: true
          description: Office that owns the location
        - name: unit
          in: query
          type: string
          required: false
          description: Unit system (EN or SI)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: ratings
      path: /ratings
      description: Rating tables for value conversion (e.g., stage to flow)
      operations:
      - name: get-ratings
        method: GET
        description: Retrieve rating tables used to convert measured values to derived values
        inputParameters:
        - name: rating-id-mask
          in: query
          type: string
          required: false
          description: Filter by rating ID pattern
        - name: office
          in: query
          type: string
          required: false
          description: Filter by office
        - name: begin
          in: query
          type: string
          required: false
          description: Effective date start filter
        - name: end
          in: query
          type: string
          required: false
          description: Effective date end filter
        - name: page-size
          in: query
          type: integer
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: levels
      path: /levels
      description: Location levels (stage thresholds, elevation reference values)
      operations:
      - name: get-levels
        method: GET
        description: Retrieve location level values for stage and elevation thresholds
        inputParameters:
        - name: location-id-mask
          in: query
          type: string
          required: false
          description: Filter by location ID pattern
        - name: office
          in: query
          type: string
          required: false
          description: Filter by office
        - name: unit
          in: query
          type: string
          required: false
          description: Unit system
        - name: begin
          in: query
          type: string
          required: false
          description: Start time filter
        - name: end
          in: query
          type: string
          required: false
          description: End time filter
        - name: page-size
          in: query
          type: integer
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: catalog
      path: /catalog/{dataset}
      description: Data catalog for all available CWMS data types
      operations:
      - name: get-catalog
        method: GET
        description: Get catalog of available data items by dataset type
        inputParameters:
        - name: dataset
          in: path
          type: string
          required: true
          description: Dataset type (TIMESERIES, LOCATIONS, RATINGS, etc.)
        - name: office
          in: query
          type: string
          required: false
          description: Filter by office
        - name: page-size
          in: query
          type: integer
          required: false
        - name: page
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: offices
      path: /offices
      description: USACE district offices in the CWMS system
      operations:
      - name: get-offices
        method: GET
        description: List all USACE district offices
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: reservoirs
      path: /reservoirs
      description: USACE reservoir project information
      operations:
      - name: get-reservoirs
        method: GET
        description: List USACE reservoir projects with storage and pool data
        inputParameters:
        - name: office
          in: query
          type: string
          required: false
          description: Filter by office
        - name: project-id-like
          in: query
          type: string
          required: false
          description: Filter by project ID pattern
        - name: page-size
          in: query
          type: integer
          required: false
        - name: page
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: water-data-api
    description: Unified REST API for USACE water management data access.
    resources:
    - path: /v1/timeseries
      name: timeseries
      description: Water management timeseries data (streamflow, stage, precipitation)
      operations:
      - method: GET
        name: get-timeseries
        description: Get timeseries values for a monitored location and parameter
        call: cwms-data.get-timeseries
        with:
          name: rest.name
          office: rest.office
          unit: rest.unit
          begin: rest.begin
          end: rest.end
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/timeseries/catalog
      name: timeseries-catalog
      description: Catalog of available timeseries identifiers
      operations:
      - method: GET
        name: list-timeseries
        description: List available CWMS timeseries identifiers
        call: cwms-data.get-timeseries-catalog
        with:
          office: rest.office
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/locations
      name: locations
      description: CWMS monitored locations
      operations:
      - method: GET
        name: list-locations
        description: List monitored water resource locations
        call: cwms-data.get-locations
        with:
          office: rest.office
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/locations/{location-id}
      name: location
      description: Single monitored location details
      operations:
      - method: GET
        name: get-location
        description: Get details for a specific monitored location
        call: cwms-data.get-location
        with:
          location-id: rest.location-id
          office: rest.office
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ratings
      name: ratings
      description: Stage-to-flow rating tables
      operations:
      - method: GET
        name: list-ratings
        description: Retrieve rating tables for value conversion
        call: cwms-data.get-ratings
        with:
          office: rest.office
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/levels
      name: levels
      description: Location level thresholds
      operations:
      - method: GET
        name: list-levels
        description: Get stage and elevation threshold levels
        call: cwms-data.get-levels
        with:
          office: rest.office
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reservoirs
      name: reservoirs
      description: USACE reservoir projects
      operations:
      - method: GET
        name: list-reservoirs
        description: List USACE reservoir projects and pool data
        call: cwms-data.get-reservoirs
        with:
          office: rest.office
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/offices
      name: offices
      description: USACE district offices
      operations:
      - method: GET
        name: list-offices
        description: List all USACE district offices
        call: cwms-data.get-offices
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/catalog/{dataset}
      name: catalog
      description: Data catalog by dataset type
      operations:
      - method: GET
        name: get-catalog
        description: Get catalog of available data by dataset type
        call: cwms-data.get-catalog
        with:
          dataset: rest.dataset
          office: rest.office
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: water-data-mcp
    transport: http
    description: MCP server for AI-assisted USACE water resource data access and analysis.
    tools:
    - name: get-streamflow-data
      description: Retrieve real-time or historical streamflow timeseries data for a CWMS location
      hints:
        readOnly: true
        openWorld: true
      call: cwms-data.get-timeseries
      with:
        name: tools.name
        office: tools.office
        unit: tools.unit
        begin: tools.begin
        end: tools.end
      outputParameters:
      - type: object
        mapping: $.
    - name: list-timeseries
      description: List available CWMS timeseries identifiers for a given office
      hints:
        readOnly: true
        openWorld: true
      call: cwms-data.get-timeseries-catalog
      with:
        office: tools.office
      outputParameters:
      - type: object
        mapping: $.
    - name: list-locations
      description: List CWMS monitored locations (stream gages, reservoirs, weather stations)
      hints:
        readOnly: true
        openWorld: true
      call: cwms-data.get-locations
      with:
        office: tools.office
      outputParameters:
      - type: object
        mapping: $.
    - name: get-location-details
      description: Get detailed information for a specific CWMS monitored location
      hints:
        readOnly: true
        openWorld: true
      call: cwms-data.get-location
      with:
        location-id: tools.location-id
        office: tools.office
      outputParameters:
      - type: object
        mapping: $.
    - name: get-stage-flow-ratings
      description: Retrieve rating tables for converting stage measurements to flow values
      hints:
        readOnly: true
        openWorld: true
      call: cwms-data.get-ratings
      with:
        office: tools.office
      outputParameters:
      - type: object
        mapping: $.
    - name: get-flood-stage-levels
      description: Get flood stage, conservation pool, and other threshold levels for locations
      hints:
        readOnly: true
        openWorld: true
      call: cwms-data.get-levels
      with:
        office: tools.office
      outputParameters:
      - type: object
        mapping: $.
    - name: list-reservoirs
      description: List USACE reservoir projects with storage and pool information
      hints:
        readOnly: true
        openWorld: true
      call: cwms-data.get-reservoirs
      with:
        office: tools.office
      outputParameters:
      - type: object
        mapping: $.
    - name: list-usace-offices
      description: List all USACE district offices (LRN, SWD, MVP, etc.)
      hints:
        readOnly: true
        openWorld: true
      call: cwms-data.get-offices
      outputParameters:
      - type: object
        mapping: $.
    - name: browse-data-catalog
      description: Browse available CWMS data types (TIMESERIES, LOCATIONS, RATINGS, RESERVOIRS)
      hints:
        readOnly: true
        openWorld: true
      call: cwms-data.get-catalog
      with:
        dataset: tools.dataset
        office: tools.office
      outputParameters:
      - type: object
        mapping: $.