naftiko: "1.0.0-alpha1"

info:
  label: Apptainer API
  description: >-
    API for the Apptainer container runtime for managing HPC container images and
    instances optimized for scientific computing workloads.
  tags:
    - Apptainer
    - Containers
    - HPC
    - Scientific Computing
  created: "2026-04-19"
  modified: "2026-04-19"

binds:
  - namespace: env
    keys:
      APPTAINER_API_TOKEN: APPTAINER_API_TOKEN

capability:
  consumes:
    - type: http
      namespace: apptainer
      baseUri: "https://api.apptainer.org/v1"
      description: Apptainer container runtime API
      authentication:
        type: bearer
        token: "{{APPTAINER_API_TOKEN}}"
      resources:
        - name: images
          path: /images
          description: Container image management
          operations:
            - name: list-images
              method: GET
              description: Returns a list of container images
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: pull-image
              method: POST
              description: Pulls a container image from a source URI
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
              body:
                type: json
                data:
                  source: "{{tools.source}}"
                  name: "{{tools.name}}"
            - name: get-image
              method: GET
              description: Returns a specific container image
              inputParameters:
                - name: imageId
                  in: path
                  type: string
                  required: true
                  description: Image identifier
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

        - name: instances
          path: /instances
          description: Container instance management
          operations:
            - name: list-instances
              method: GET
              description: Returns running container instances
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: start-instance
              method: POST
              description: Starts a new container instance
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
              body:
                type: json
                data:
                  imageId: "{{tools.imageId}}"
                  name: "{{tools.name}}"
                  command: "{{tools.command}}"

  exposes:
    - type: mcp
      port: 9090
      namespace: apptainer-mcp
      transport: http
      tools:
        - name: list-container-images
          description: Lists Apptainer container images available for HPC workloads
          hints:
            readOnly: true
            idempotent: true
          call: "apptainer.list-images"
          outputParameters:
            - type: object
              mapping: "$."

        - name: pull-container-image
          description: Pulls a container image from Docker Hub, OCI registry, or Apptainer library
          hints:
            readOnly: false
            destructive: false
          call: "apptainer.pull-image"
          with:
            source: "tools.source"
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-running-instances
          description: Lists currently running Apptainer container instances
          hints:
            readOnly: true
            idempotent: true
          call: "apptainer.list-instances"
          outputParameters:
            - type: object
              mapping: "$."

        - name: start-container-instance
          description: Starts a new Apptainer container instance from an existing image
          hints:
            readOnly: false
            destructive: false
          call: "apptainer.start-instance"
          with:
            imageId: "tools.imageId"
            name: "tools.name"
            command: "tools.command"
          outputParameters:
            - type: object
              mapping: "$."