WattTime Carbon-Aware Computing

naftiko: "1.0.0-alpha1"

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-03"

binds:
  - namespace: env
    keys:
      WATTTIME_USERNAME: WATTTIME_USERNAME
      WATTTIME_PASSWORD: WATTTIME_PASSWORD

capability:
  consumes:
    - import: watttime
      location: ./shared/watttime-api.yaml

  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: "$."