naftiko: 1.0.0-alpha2
info:
  label: WattTime Carbon-Aware Computing
  description: Workflow capability combining WattTime's real-time, forecast, and historical emissions data to enable carbon-aware
    scheduling, sustainability reporting, and clean energy procurement decisions. Used by software engineers, platform teams,
    and sustainability analysts to reduce carbon footprint of compute workloads and measure emissions reductions.
  tags:
  - Carbon-Aware Computing
  - Emissions
  - Sustainability
  - Energy
  - WattTime
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    WATTTIME_USERNAME: WATTTIME_USERNAME
    WATTTIME_PASSWORD: WATTTIME_PASSWORD
capability:
  consumes:
  - type: http
    namespace: watttime
    baseUri: https://api.watttime.org/v3
    description: WattTime Data API v3 for marginal emissions and grid data.
    authentication:
      type: bearer
      token: '{{WATTTIME_TOKEN}}'
    resources:
    - name: authentication
      path: /login
      description: Obtain JWT bearer token via HTTP Basic Auth.
      operations:
      - name: login
        method: GET
        description: Authenticate and obtain a JWT access token.
        outputRawFormat: json
        outputParameters:
        - name: token
          type: string
          value: $.token
    - name: account
      path: /my-access
      description: Account access information and available grid regions.
      operations:
      - name: get-my-access
        method: GET
        description: Get accessible grid regions and model metadata.
        inputParameters:
        - name: signal_type
          in: query
          type: string
          required: false
          description: Filter by signal type (co2_moer, co2_aoer, health_damage).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: grid-regions
      path: /region-from-loc
      description: Identify the grid region for a geographic location.
      operations:
      - name: get-region-from-location
        method: GET
        description: Get the grid balancing authority for lat/lon coordinates.
        inputParameters:
        - name: latitude
          in: query
          type: number
          required: true
          description: Latitude in decimal degrees.
        - name: longitude
          in: query
          type: number
          required: true
          description: Longitude in decimal degrees.
        - name: signal_type
          in: query
          type: string
          required: false
          description: Signal type to check region for.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: emissions-data
      path: /data
      description: Historical emissions data for a grid region.
      operations:
      - name: get-historical-data
        method: GET
        description: Get historical emissions data (up to 32-day window).
        inputParameters:
        - name: region
          in: query
          type: string
          required: true
          description: Grid region identifier.
        - name: signal_type
          in: query
          type: string
          required: true
          description: Emissions signal type.
        - name: start
          in: query
          type: string
          required: true
          description: Start datetime (ISO 8601 UTC).
        - name: end
          in: query
          type: string
          required: true
          description: End datetime (ISO 8601 UTC).
        - name: model
          in: query
          type: string
          required: false
          description: Model version date.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: forecasts
      path: /forecast
      description: Real-time and forecast emissions data.
      operations:
      - name: get-forecast
        method: GET
        description: Get current emissions forecast (updated every 5 minutes).
        inputParameters:
        - name: region
          in: query
          type: string
          required: true
          description: Grid region identifier.
        - name: signal_type
          in: query
          type: string
          required: true
          description: Emissions signal type.
        - name: horizon_hours
          in: query
          type: integer
          required: false
          description: Forecast horizon in hours (max 72).
        - name: model
          in: query
          type: string
          required: false
          description: Model version date.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-forecast-historical
        method: GET
        description: Get historically generated forecast data for back-testing.
        inputParameters:
        - name: region
          in: query
          type: string
          required: true
          description: Grid region identifier.
        - name: signal_type
          in: query
          type: string
          required: true
          description: Emissions signal type.
        - name: start
          in: query
          type: string
          required: true
          description: Start of historical forecast window.
        - name: end
          in: query
          type: string
          required: true
          description: End of historical forecast window.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: historical-download
      path: /historical
      description: Download multi-year historical emissions CSV files.
      operations:
      - name: download-historical-data
        method: GET
        description: Get download URL for multi-year historical emissions CSV.
        inputParameters:
        - name: region
          in: query
          type: string
          required: true
          description: Grid region identifier.
        - name: signal_type
          in: query
          type: string
          required: true
          description: Emissions signal type.
        - name: start
          in: query
          type: string
          required: false
          description: Start date (YYYY-MM-DD).
        - name: end
          in: query
          type: string
          required: false
          description: End date (YYYY-MM-DD).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: maps
      path: /maps
      description: GeoJSON grid region boundary maps.
      operations:
      - name: get-grid-maps
        method: GET
        description: Get GeoJSON boundaries for accessible grid regions.
        inputParameters:
        - name: signal_type
          in: query
          type: string
          required: false
          description: Filter by signal type.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: carbon-aware-api
    description: Unified REST API for carbon-aware computing workflows.
    resources:
    - path: /v1/auth/login
      name: authentication
      description: Authenticate with the WattTime API.
      operations:
      - method: GET
        name: login
        description: Obtain a WattTime API access token.
        call: watttime.login
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/grid/region
      name: grid-region
      description: Identify the grid region for a location.
      operations:
      - method: GET
        name: get-region-from-location
        description: Look up the grid region for geographic coordinates.
        call: watttime.get-region-from-location
        with:
          latitude: rest.latitude
          longitude: rest.longitude
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/grid/regions
      name: grid-regions
      description: List accessible grid regions and models.
      operations:
      - method: GET
        name: get-my-access
        description: Get all accessible grid regions and available model versions.
        call: watttime.get-my-access
        with:
          signal_type: rest.signal_type
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/emissions/realtime
      name: realtime-emissions
      description: Real-time emissions data and short-term forecast.
      operations:
      - method: GET
        name: get-forecast
        description: Get real-time and forecast emissions for a grid region.
        call: watttime.get-forecast
        with:
          region: rest.region
          signal_type: rest.signal_type
          horizon_hours: rest.horizon_hours
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/emissions/historical
      name: historical-emissions
      description: Historical emissions data for analysis and reporting.
      operations:
      - method: GET
        name: get-historical-data
        description: Get historical emissions data (up to 32-day window).
        call: watttime.get-historical-data
        with:
          region: rest.region
          signal_type: rest.signal_type
          start: rest.start
          end: rest.end
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/emissions/forecast-history
      name: forecast-history
      description: Historically generated forecasts for back-testing.
      operations:
      - method: GET
        name: get-forecast-historical
        description: Get historical forecast data for algorithm validation.
        call: watttime.get-forecast-historical
        with:
          region: rest.region
          signal_type: rest.signal_type
          start: rest.start
          end: rest.end
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/emissions/download
      name: emissions-download
      description: Download multi-year historical emissions CSV data.
      operations:
      - method: GET
        name: download-historical-data
        description: Get download URL for historical emissions dataset.
        call: watttime.download-historical-data
        with:
          region: rest.region
          signal_type: rest.signal_type
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/grid/maps
      name: grid-maps
      description: GeoJSON grid region boundaries for visualization.
      operations:
      - method: GET
        name: get-grid-maps
        description: Get GeoJSON boundaries for grid regions.
        call: watttime.get-grid-maps
        with:
          signal_type: rest.signal_type
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: carbon-aware-mcp
    transport: http
    description: MCP server for AI-assisted carbon-aware computing and sustainability analysis.
    tools:
    - name: authenticate
      description: Authenticate with the WattTime API to obtain an access token for subsequent calls.
      hints:
        readOnly: false
        openWorld: false
      call: watttime.login
      outputParameters:
      - type: object
        mapping: $.
    - name: find-grid-region
      description: Identify the electric grid balancing authority for a geographic location by latitude and longitude.
      hints:
        readOnly: true
        openWorld: true
      call: watttime.get-region-from-location
      with:
        latitude: tools.latitude
        longitude: tools.longitude
      outputParameters:
      - type: object
        mapping: $.
    - name: list-accessible-regions
      description: List all grid regions accessible under the current WattTime subscription, with model versions.
      hints:
        readOnly: true
        openWorld: false
      call: watttime.get-my-access
      with:
        signal_type: tools.signal_type
      outputParameters:
      - type: object
        mapping: $.
    - name: get-realtime-emissions
      description: Get the current real-time marginal emissions forecast for a grid region, updated every 5 minutes. Use for
        deciding whether NOW is a good time to run a workload.
      hints:
        readOnly: true
        openWorld: true
      call: watttime.get-forecast
      with:
        region: tools.region
        signal_type: tools.signal_type
        horizon_hours: tools.horizon_hours
      outputParameters:
      - type: object
        mapping: $.
    - name: get-historical-emissions
      description: Get historical marginal emissions data for a grid region over a time window (max 32 days). Use for reporting
        past emissions impact.
      hints:
        readOnly: true
        openWorld: false
      call: watttime.get-historical-data
      with:
        region: tools.region
        signal_type: tools.signal_type
        start: tools.start
        end: tools.end
      outputParameters:
      - type: object
        mapping: $.
    - name: get-forecast-history
      description: Retrieve previously generated forecast data for a historical period. Use for back-testing carbon-aware
        scheduling algorithms.
      hints:
        readOnly: true
        openWorld: false
      call: watttime.get-forecast-historical
      with:
        region: tools.region
        signal_type: tools.signal_type
        start: tools.start
        end: tools.end
      outputParameters:
      - type: object
        mapping: $.
    - name: download-emissions-dataset
      description: Get a download URL for multi-year historical emissions data as a CSV file.
      hints:
        readOnly: true
        openWorld: false
      call: watttime.download-historical-data
      with:
        region: tools.region
        signal_type: tools.signal_type
        start: tools.start
        end: tools.end
      outputParameters:
      - type: object
        mapping: $.
    - name: get-grid-maps
      description: Get GeoJSON boundaries for all accessible grid regions for map visualization.
      hints:
        readOnly: true
        openWorld: true
      call: watttime.get-grid-maps
      with:
        signal_type: tools.signal_type
      outputParameters:
      - type: object
        mapping: $.