Debian Sources API — Sources

naftiko: 1.0.0-alpha2
info:
  label: Debian Sources API — Sources
  description: 'Debian Sources API — Sources. 8 operations. Lead operation: Search by ctag. Self-contained Naftiko capability
    covering one Debian business surface.'
  tags:
  - Debian
  - Sources
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    DEBIAN_API_KEY: DEBIAN_API_KEY
capability:
  consumes:
  - type: http
    namespace: sources-sources
    baseUri: https://sources.debian.org/api
    description: Debian Sources API — Sources business capability. Self-contained, no shared references.
    resources:
    - name: ctag
      path: /ctag/
      operations:
      - name: searchbyctag
        method: GET
        description: Search by ctag
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ctag
          in: query
          type: string
          required: true
    - name: info-package-package-version
      path: /info/package/{package}/{version}
      operations:
      - name: getpackageinfo
        method: GET
        description: Get package info
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: package
          in: path
          type: string
          required: true
        - name: version
          in: path
          type: string
          required: true
    - name: list
      path: /list
      operations:
      - name: listpackages
        method: GET
        description: List all packages
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: ping
      path: /ping/
      operations:
      - name: ping
        method: GET
        description: Health check
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: prefix-prefix
      path: /prefix/{prefix}
      operations:
      - name: listpackagesbyprefix
        method: GET
        description: List packages by prefix
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: prefix
          in: path
          type: string
          required: true
    - name: search-query
      path: /search/{query}
      operations:
      - name: searchsources
        method: GET
        description: Search source code
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: path
          type: string
          required: true
    - name: sha256
      path: /sha256/
      operations:
      - name: searchbysha256
        method: GET
        description: Search by file checksum
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: checksum
          in: query
          type: string
          required: true
    - name: src-package-version-path
      path: /src/{package}/{version}/{path}
      operations:
      - name: getsourcepath
        method: GET
        description: Browse source tree
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: package
          in: path
          type: string
          required: true
        - name: version
          in: path
          type: string
          required: true
        - name: path
          in: path
          type: string
          required: true
  exposes:
  - type: rest
    namespace: sources-sources-rest
    port: 8080
    description: REST adapter for Debian Sources API — Sources. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/ctag
      name: ctag
      description: REST surface for ctag.
      operations:
      - method: GET
        name: searchbyctag
        description: Search by ctag
        call: sources-sources.searchbyctag
        with:
          ctag: rest.ctag
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/info/package/{package}/{version}
      name: info-package-package-version
      description: REST surface for info-package-package-version.
      operations:
      - method: GET
        name: getpackageinfo
        description: Get package info
        call: sources-sources.getpackageinfo
        with:
          package: rest.package
          version: rest.version
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/list
      name: list
      description: REST surface for list.
      operations:
      - method: GET
        name: listpackages
        description: List all packages
        call: sources-sources.listpackages
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ping
      name: ping
      description: REST surface for ping.
      operations:
      - method: GET
        name: ping
        description: Health check
        call: sources-sources.ping
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/prefix/{prefix}
      name: prefix-prefix
      description: REST surface for prefix-prefix.
      operations:
      - method: GET
        name: listpackagesbyprefix
        description: List packages by prefix
        call: sources-sources.listpackagesbyprefix
        with:
          prefix: rest.prefix
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/search/{query}
      name: search-query
      description: REST surface for search-query.
      operations:
      - method: GET
        name: searchsources
        description: Search source code
        call: sources-sources.searchsources
        with:
          query: rest.query
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/sha256
      name: sha256
      description: REST surface for sha256.
      operations:
      - method: GET
        name: searchbysha256
        description: Search by file checksum
        call: sources-sources.searchbysha256
        with:
          checksum: rest.checksum
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/src/{package}/{version}/{path}
      name: src-package-version-path
      description: REST surface for src-package-version-path.
      operations:
      - method: GET
        name: getsourcepath
        description: Browse source tree
        call: sources-sources.getsourcepath
        with:
          package: rest.package
          version: rest.version
          path: rest.path
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: sources-sources-mcp
    port: 9090
    transport: http
    description: MCP adapter for Debian Sources API — Sources. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: search-ctag
      description: Search by ctag
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: sources-sources.searchbyctag
      with:
        ctag: tools.ctag
      outputParameters:
      - type: object
        mapping: $.
    - name: get-package-info
      description: Get package info
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: sources-sources.getpackageinfo
      with:
        package: tools.package
        version: tools.version
      outputParameters:
      - type: object
        mapping: $.
    - name: list-all-packages
      description: List all packages
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: sources-sources.listpackages
      outputParameters:
      - type: object
        mapping: $.
    - name: health-check
      description: Health check
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: sources-sources.ping
      outputParameters:
      - type: object
        mapping: $.
    - name: list-packages-prefix
      description: List packages by prefix
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: sources-sources.listpackagesbyprefix
      with:
        prefix: tools.prefix
      outputParameters:
      - type: object
        mapping: $.
    - name: search-source-code
      description: Search source code
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: sources-sources.searchsources
      with:
        query: tools.query
      outputParameters:
      - type: object
        mapping: $.
    - name: search-file-checksum
      description: Search by file checksum
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: sources-sources.searchbysha256
      with:
        checksum: tools.checksum
      outputParameters:
      - type: object
        mapping: $.
    - name: browse-source-tree
      description: Browse source tree
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: sources-sources.getsourcepath
      with:
        package: tools.package
        version: tools.version
        path: tools.path
      outputParameters:
      - type: object
        mapping: $.