naftiko: 1.0.0-alpha2
info:
  label: Soracom Harvest Data Capability
  description: Self-contained Naftiko capability for ingesting, retrieving, and exporting time-series telemetry from Soracom Harvest Data and binary uploads from Harvest Files.
  tags:
  - Soracom
  - Harvest
  - Data
  - Files
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    SORACOM_API_KEY: SORACOM_API_KEY
    SORACOM_API_TOKEN: SORACOM_API_TOKEN
capability:
  consumes:
  - type: http
    namespace: harvest
    baseUri: https://api.soracom.io/v1
    description: Soracom Harvest Data and Files API.
    resources:
    - name: data
      path: /data/{resource_type}/{resource_id}
      operations:
      - name: getDataEntries
        method: GET
        description: Get harvested data entries for a resource (Subscriber/Device/SigfoxDevice/LoraDevice).
        outputRawFormat: json
        outputParameters:
        - {name: result, type: array, value: $.}
        inputParameters:
        - {name: resource_type, in: path, type: string, required: true}
        - {name: resource_id, in: path, type: string, required: true}
        - {name: from, in: query, type: integer, required: false}
        - {name: to, in: query, type: integer, required: false}
        - {name: limit, in: query, type: integer, required: false}
    - name: data-resources
      path: /data/resources
      operations:
      - name: listDataResources
        method: GET
        description: List all resources that have harvested data.
        outputRawFormat: json
        outputParameters:
        - {name: result, type: array, value: $.}
        inputParameters: []
    - name: files
      path: /files/private/{path}
      operations:
      - name: getFile
        method: GET
        description: Download a Harvest File.
        outputRawFormat: bytes
        outputParameters:
        - {name: result, type: bytes, value: $.}
        inputParameters:
        - {name: path, in: path, type: string, required: true}
      - name: putFile
        method: PUT
        description: Upload a Harvest File.
        outputRawFormat: json
        outputParameters:
        - {name: result, type: object, value: $.}
        inputParameters:
        - {name: path, in: path, type: string, required: true}
        - {name: body, in: body, type: bytes, required: true}
    authentication:
      type: apikey
      key: X-Soracom-API-Key
      value: '{{env.SORACOM_API_KEY}}'
      placement: header
  exposes:
  - type: mcp
    namespace: harvest-mcp
    port: 9090
    transport: http
    description: MCP adapter for Harvest data and files.
    tools:
    - name: soracom-get-harvest-data
      description: Get harvested telemetry for a resource.
      hints: {readOnly: true, destructive: false, idempotent: true}
      call: harvest.getDataEntries
      with:
        resource_type: tools.resource_type
        resource_id: tools.resource_id
        from: tools.from
        to: tools.to
        limit: tools.limit
      outputParameters:
      - {type: array, mapping: $.}
    - name: soracom-list-harvest-resources
      description: List resources with harvested data.
      hints: {readOnly: true, destructive: false, idempotent: true}
      call: harvest.listDataResources
      outputParameters:
      - {type: array, mapping: $.}
    - name: soracom-get-harvest-file
      description: Download a Harvest File.
      hints: {readOnly: true, destructive: false, idempotent: true}
      call: harvest.getFile
      with:
        path: tools.path
      outputParameters:
      - {type: bytes, mapping: $.}
    - name: soracom-put-harvest-file
      description: Upload a Harvest File.
      hints: {readOnly: false, destructive: false, idempotent: true}
      call: harvest.putFile
      with:
        path: tools.path
        body: tools.body
      outputParameters:
      - {type: object, mapping: $.}