Cat Content Discovery

naftiko: "1.0.0-alpha1"

info:
  label: "Cat Content Discovery"
  description: >-
    Workflow capability for discovering, browsing, and curating cat content.
    Combines image search with breed lookup, category filtering, voting, and
    favouriting to support cat app builders, media platforms, and educational tools.
  tags:
    - Animals
    - Cats
    - Content Discovery
    - Images
    - Media
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      CAT_API_KEY: CAT_API_KEY

capability:
  consumes:
    - import: catapi
      location: ./shared/the-cat-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: cat-content-api
      description: "Unified REST API for cat content discovery, breed research, and user curation."
      resources:
        - path: /v1/images
          name: images
          description: Search and retrieve cat images.
          operations:
            - method: GET
              name: search-images
              description: Search cat images with optional breed and category filters.
              call: "catapi.search-images"
              with:
                limit: "rest.limit"
                breed_ids: "rest.breed_ids"
                category_ids: "rest.category_ids"
                has_breeds: "rest.has_breeds"
              outputParameters:
                - type: array
                  mapping: "$."
        - path: /v1/images/{image_id}
          name: image-detail
          description: Retrieve a specific cat image.
          operations:
            - method: GET
              name: get-image
              description: Get details for a specific cat image.
              call: "catapi.get-image"
              with:
                image_id: "rest.image_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/breeds
          name: breeds
          description: Browse and search cat breeds.
          operations:
            - method: GET
              name: list-breeds
              description: List all cat breeds with characteristics.
              call: "catapi.list-breeds"
              with:
                limit: "rest.limit"
                page: "rest.page"
              outputParameters:
                - type: array
                  mapping: "$."
        - path: /v1/breeds/search
          name: breed-search
          description: Search breeds by name.
          operations:
            - method: GET
              name: search-breeds
              description: Search cat breeds by name.
              call: "catapi.search-breeds"
              with:
                q: "rest.q"
              outputParameters:
                - type: array
                  mapping: "$."
        - path: /v1/categories
          name: categories
          description: Browse image categories.
          operations:
            - method: GET
              name: list-categories
              description: List all image categories.
              call: "catapi.list-categories"
              outputParameters:
                - type: array
                  mapping: "$."
        - path: /v1/favourites
          name: favourites
          description: Manage user favourite images.
          operations:
            - method: GET
              name: list-favourites
              description: List the user's favourite cat images.
              call: "catapi.list-favourites"
              outputParameters:
                - type: array
                  mapping: "$."
            - method: POST
              name: save-favourite
              description: Save a cat image as a favourite.
              call: "catapi.save-favourite"
              with:
                image_id: "rest.image_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/votes
          name: votes
          description: Cast and track votes on cat images.
          operations:
            - method: GET
              name: list-votes
              description: List all user votes.
              call: "catapi.list-votes"
              outputParameters:
                - type: array
                  mapping: "$."
            - method: POST
              name: create-vote
              description: Cast an upvote or downvote on an image.
              call: "catapi.create-vote"
              with:
                image_id: "rest.image_id"
                value: "rest.value"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: cat-content-mcp
      transport: http
      description: "MCP server for AI-assisted cat content discovery, breed research, and curation."
      tools:
        - name: search-cat-images
          description: Search for cat images, optionally filtered by breed or category.
          hints:
            readOnly: true
            openWorld: true
          call: "catapi.search-images"
          with:
            limit: "tools.limit"
            breed_ids: "tools.breed_ids"
            category_ids: "tools.category_ids"
          outputParameters:
            - type: array
              mapping: "$."
        - name: get-cat-image
          description: Retrieve details and metadata for a specific cat image by ID.
          hints:
            readOnly: true
            openWorld: false
          call: "catapi.get-image"
          with:
            image_id: "tools.image_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-cat-breeds
          description: List all cat breeds with detailed characteristics, personality ratings, and origin information.
          hints:
            readOnly: true
            openWorld: true
          call: "catapi.list-breeds"
          with:
            limit: "tools.limit"
            page: "tools.page"
          outputParameters:
            - type: array
              mapping: "$."
        - name: search-cat-breeds
          description: Search for cat breeds by name to find breed-specific information.
          hints:
            readOnly: true
            openWorld: true
          call: "catapi.search-breeds"
          with:
            q: "tools.q"
          outputParameters:
            - type: array
              mapping: "$."
        - name: list-image-categories
          description: List all available cat image categories for filtering searches.
          hints:
            readOnly: true
            openWorld: true
          call: "catapi.list-categories"
          outputParameters:
            - type: array
              mapping: "$."
        - name: list-user-favourites
          description: List all cat images saved as favourites by the current user.
          hints:
            readOnly: true
            openWorld: false
          call: "catapi.list-favourites"
          with:
            sub_id: "tools.sub_id"
          outputParameters:
            - type: array
              mapping: "$."
        - name: save-cat-favourite
          description: Save a cat image to the user's favourites collection.
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "catapi.save-favourite"
          with:
            image_id: "tools.image_id"
            sub_id: "tools.sub_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-user-votes
          description: List all votes cast by the current user on cat images.
          hints:
            readOnly: true
            openWorld: false
          call: "catapi.list-votes"
          with:
            sub_id: "tools.sub_id"
          outputParameters:
            - type: array
              mapping: "$."
        - name: vote-on-image
          description: Cast an upvote (1) or downvote (0) on a cat image.
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "catapi.create-vote"
          with:
            image_id: "tools.image_id"
            value: "tools.value"
            sub_id: "tools.sub_id"
          outputParameters:
            - type: object
              mapping: "$."