naftiko: 1.0.0-alpha2
info:
  label: UtilityAPI Energy Data Access
  description: Unified workflow capability for accessing utility energy data including meters, billing history, interval usage,
    and authorization management. Designed for cleantech developers, energy analytics platforms, and EV charging optimization
    tools.
  tags:
  - Energy
  - Utilities
  - Billing
  - Meter Data
  - Green Button
  - Clean Energy
  - EV Charging
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    UTILITYAPI_TOKEN: UTILITYAPI_TOKEN
capability:
  consumes:
  - type: http
    namespace: utilityapi
    baseUri: https://utilityapi.com/api/v2
    description: UtilityAPI REST API for utility data access
    authentication:
      type: bearer
      token: '{{UTILITYAPI_TOKEN}}'
    resources:
    - name: meters
      path: /meters
      description: Utility service meters for authorized customers
      operations:
      - name: list-meters
        method: GET
        description: List all utility meters for authorized customers
        inputParameters:
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of meters to return
        - name: authorization_uid
          in: query
          type: string
          required: false
          description: Filter meters by authorization UID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-meter
        method: GET
        description: Retrieve a specific utility meter
        inputParameters:
        - name: uid
          in: path
          type: string
          required: true
          description: Meter unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: collect-meter-data
        method: POST
        description: Trigger data collection for a utility meter
        inputParameters:
        - name: uid
          in: path
          type: string
          required: true
          description: Meter unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: monitor-meter-data
        method: POST
        description: Enable ongoing monitoring for a utility meter
        inputParameters:
        - name: uid
          in: path
          type: string
          required: true
          description: Meter unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: bills
      path: /bills
      description: Utility billing information
      operations:
      - name: list-bills
        method: GET
        description: List all utility bills for authorized meters
        inputParameters:
        - name: meter_uid
          in: query
          type: string
          required: false
          description: Filter bills by meter UID
        - name: start
          in: query
          type: string
          required: false
          description: Start date filter (ISO 8601)
        - name: end
          in: query
          type: string
          required: false
          description: End date filter (ISO 8601)
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of bills to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: intervals
      path: /intervals
      description: Meter usage intervals
      operations:
      - name: list-intervals
        method: GET
        description: List meter usage intervals for authorized meters
        inputParameters:
        - name: meter_uid
          in: query
          type: string
          required: false
          description: Filter intervals by meter UID
        - name: start
          in: query
          type: string
          required: false
          description: Start datetime filter (ISO 8601)
        - name: end
          in: query
          type: string
          required: false
          description: End datetime filter (ISO 8601)
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of intervals to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: authorizations
      path: /authorizations
      description: Customer authorizations for utility data access
      operations:
      - name: list-authorizations
        method: GET
        description: List all submitted authorizations
        inputParameters:
        - name: status
          in: query
          type: string
          required: false
          description: Filter by authorization status
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of authorizations to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-authorization
        method: GET
        description: Retrieve a specific authorization
        inputParameters:
        - name: uid
          in: path
          type: string
          required: true
          description: Authorization unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: revoke-authorization
        method: POST
        description: Revoke a customer authorization
        inputParameters:
        - name: uid
          in: path
          type: string
          required: true
          description: Authorization unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: events
      path: /events
      description: Webhook events and notifications
      operations:
      - name: list-events
        method: GET
        description: List webhook events for the authenticated account
        inputParameters:
        - name: type
          in: query
          type: string
          required: false
          description: Filter by event type
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of events to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-event
        method: GET
        description: Retrieve a specific webhook event
        inputParameters:
        - name: uid
          in: path
          type: string
          required: true
          description: Event unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: billing-accounts
      path: /accounting/billing-accounts
      description: Customer billing accounts
      operations:
      - name: list-billing-accounts
        method: GET
        description: List all customer billing accounts
        inputParameters:
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of accounts to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-billing-account
        method: GET
        description: Retrieve a specific billing account
        inputParameters:
        - name: uid
          in: path
          type: string
          required: true
          description: Billing account unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: billing-summaries
      path: /accounting/billing-summaries
      description: Billing summaries for customer accounts
      operations:
      - name: list-billing-summaries
        method: GET
        description: List billing summaries for customer accounts
        inputParameters:
        - name: billing_account_uid
          in: query
          type: string
          required: false
          description: Filter by billing account UID
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of summaries to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-billing-summary
        method: GET
        description: Retrieve a specific billing summary
        inputParameters:
        - name: uid
          in: path
          type: string
          required: true
          description: Billing summary unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: energy-data-api
    description: Unified REST API for energy data access and utility management.
    resources:
    - path: /v1/meters
      name: meters
      description: Utility meter access for authorized customers
      operations:
      - method: GET
        name: list-meters
        description: List all utility meters for authorized customers
        call: utilityapi.list-meters
        with:
          authorization_uid: rest.authorization_uid
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/meters/{uid}
      name: meter
      description: Individual meter details
      operations:
      - method: GET
        name: get-meter
        description: Get a specific utility meter
        call: utilityapi.get-meter
        with:
          uid: rest.uid
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/meters/{uid}/collect
      name: meter-collect
      description: Trigger meter data collection
      operations:
      - method: POST
        name: collect-meter-data
        description: Trigger data collection for a meter
        call: utilityapi.collect-meter-data
        with:
          uid: rest.uid
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/meters/{uid}/monitor
      name: meter-monitor
      description: Enable meter monitoring
      operations:
      - method: POST
        name: monitor-meter-data
        description: Enable ongoing monitoring for a meter
        call: utilityapi.monitor-meter-data
        with:
          uid: rest.uid
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/bills
      name: bills
      description: Utility billing data
      operations:
      - method: GET
        name: list-bills
        description: List utility bills for authorized meters
        call: utilityapi.list-bills
        with:
          meter_uid: rest.meter_uid
          start: rest.start
          end: rest.end
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/intervals
      name: intervals
      description: Meter usage interval data
      operations:
      - method: GET
        name: list-intervals
        description: List meter usage intervals
        call: utilityapi.list-intervals
        with:
          meter_uid: rest.meter_uid
          start: rest.start
          end: rest.end
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/authorizations
      name: authorizations
      description: Customer authorizations
      operations:
      - method: GET
        name: list-authorizations
        description: List all customer authorizations
        call: utilityapi.list-authorizations
        with:
          status: rest.status
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/authorizations/{uid}/revoke
      name: authorization-revoke
      description: Revoke a customer authorization
      operations:
      - method: POST
        name: revoke-authorization
        description: Revoke a customer's utility data authorization
        call: utilityapi.revoke-authorization
        with:
          uid: rest.uid
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/events
      name: events
      description: Webhook events
      operations:
      - method: GET
        name: list-events
        description: List webhook events
        call: utilityapi.list-events
        with:
          type: rest.type
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/billing-accounts
      name: billing-accounts
      description: Customer billing accounts
      operations:
      - method: GET
        name: list-billing-accounts
        description: List customer billing accounts
        call: utilityapi.list-billing-accounts
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/billing-summaries
      name: billing-summaries
      description: Billing summaries
      operations:
      - method: GET
        name: list-billing-summaries
        description: List billing summaries
        call: utilityapi.list-billing-summaries
        with:
          billing_account_uid: rest.billing_account_uid
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: energy-data-mcp
    transport: http
    description: MCP server for AI-assisted energy data analysis and utility management.
    tools:
    - name: list-meters
      description: List utility meters for authorized customers
      hints:
        readOnly: true
        openWorld: true
      call: utilityapi.list-meters
      with:
        authorization_uid: tools.authorization_uid
      outputParameters:
      - type: object
        mapping: $.
    - name: get-meter
      description: Get details for a specific utility meter
      hints:
        readOnly: true
        idempotent: true
      call: utilityapi.get-meter
      with:
        uid: tools.uid
      outputParameters:
      - type: object
        mapping: $.
    - name: collect-meter-data
      description: Trigger data collection for a utility meter
      hints:
        readOnly: false
        destructive: false
      call: utilityapi.collect-meter-data
      with:
        uid: tools.uid
      outputParameters:
      - type: object
        mapping: $.
    - name: monitor-meter-data
      description: Enable ongoing data monitoring for a utility meter
      hints:
        readOnly: false
        idempotent: true
      call: utilityapi.monitor-meter-data
      with:
        uid: tools.uid
      outputParameters:
      - type: object
        mapping: $.
    - name: list-bills
      description: List utility billing history for a meter
      hints:
        readOnly: true
        openWorld: true
      call: utilityapi.list-bills
      with:
        meter_uid: tools.meter_uid
        start: tools.start
        end: tools.end
      outputParameters:
      - type: object
        mapping: $.
    - name: list-intervals
      description: List meter usage interval data for energy analysis
      hints:
        readOnly: true
        openWorld: true
      call: utilityapi.list-intervals
      with:
        meter_uid: tools.meter_uid
        start: tools.start
        end: tools.end
      outputParameters:
      - type: object
        mapping: $.
    - name: list-authorizations
      description: List customer utility data authorizations
      hints:
        readOnly: true
        openWorld: true
      call: utilityapi.list-authorizations
      with:
        status: tools.status
      outputParameters:
      - type: object
        mapping: $.
    - name: revoke-authorization
      description: Revoke a customer's utility data authorization
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: utilityapi.revoke-authorization
      with:
        uid: tools.uid
      outputParameters:
      - type: object
        mapping: $.
    - name: list-events
      description: List webhook events for monitoring data updates
      hints:
        readOnly: true
        openWorld: true
      call: utilityapi.list-events
      with:
        type: tools.type
      outputParameters:
      - type: object
        mapping: $.
    - name: list-billing-accounts
      description: List customer billing accounts
      hints:
        readOnly: true
        openWorld: true
      call: utilityapi.list-billing-accounts
      outputParameters:
      - type: object
        mapping: $.
    - name: list-billing-summaries
      description: List billing summaries for energy cost analysis
      hints:
        readOnly: true
        openWorld: true
      call: utilityapi.list-billing-summaries
      with:
        billing_account_uid: tools.billing_account_uid
      outputParameters:
      - type: object
        mapping: $.