Whisky Market Intelligence

naftiko: "1.0.0-alpha1"

info:
  label: "Whisky Market Intelligence"
  description: >-
    Unified whisky market intelligence capability composing auction data and distillery
    analytics from the Whisky Hunter API to support collectors, investors, and traders
    researching whisky market trends, distillery performance, and auction price dynamics.
  tags:
    - Whisky
    - Market Intelligence
    - Auctions
    - Distilleries
    - Collectors
    - Investors
    - Price Research
  created: "2026-05-03"
  modified: "2026-05-03"

capability:
  consumes:
    - import: whisky-hunter
      location: ./shared/whisky-hunter-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: whisky-market-intelligence-api
      description: "Unified REST API for whisky market research, auction analytics, and distillery price tracking."
      resources:
        - path: /v1/auctions
          name: auctions
          description: "Aggregated whisky auction statistics across all tracked platforms."
          operations:
            - method: GET
              name: get-auctions-data
              description: "Get aggregated auction trading volumes, bid statistics, and lot counts across all 28 tracked platforms."
              call: "whisky-hunter.get-auctions-data"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/distilleries
          name: distilleries
          description: "All distilleries tracked in the Whisky Hunter database."
          operations:
            - method: GET
              name: list-distilleries
              description: "List all tracked distilleries with their slugs for further data queries."
              call: "whisky-hunter.list-distilleries"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/distilleries/{slug}
          name: distillery-auction-data
          description: "Historical auction data for a specific distillery."
          operations:
            - method: GET
              name: get-distillery-data
              description: "Get historical auction trading volumes and price statistics for a distillery."
              call: "whisky-hunter.get-distillery-data"
              with:
                slug: "rest.slug"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: whisky-market-intelligence-mcp
      transport: http
      description: "MCP server for AI-assisted whisky market research and investment analysis."
      tools:
        - name: get-auctions-data
          description: >-
            Get aggregated whisky auction statistics across all 28 tracked platforms
            including trading volumes, winning bid ranges, and lot counts. Useful for
            understanding overall market activity and trends.
          hints:
            readOnly: true
            openWorld: true
          call: "whisky-hunter.get-auctions-data"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-distilleries
          description: >-
            List all whisky distilleries tracked in the database. Returns names and
            slugs that can be used with get-distillery-data to research specific
            distillery auction performance.
          hints:
            readOnly: true
            openWorld: true
          call: "whisky-hunter.list-distilleries"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-distillery-data
          description: >-
            Get historical whisky auction data for a specific distillery, including
            trading volumes, lot counts, and winning bid statistics over time.
            Use the slug from list-distilleries (e.g., 'macallan', 'ardbeg', 'yamazaki').
          hints:
            readOnly: true
            openWorld: false
          call: "whisky-hunter.get-distillery-data"
          with:
            slug: "tools.slug"
          outputParameters:
            - type: object
              mapping: "$."