Punk API — Beers

naftiko: "1.0.0-alpha2"

info:
  label: "Punk API — Beers"
  description: >-
    Beers — the only Punk API surface. Three read-only operations: list with
    rich recipe-oriented filtering, get by id, and random. The public
    api.punkapi.com endpoint was sunset in 2023; this capability targets the
    historical contract and the same contract served by community self-hosters
    of sammdec/punkapi-server.
  tags:
    - PunkAPI
    - Beers
    - BrewDog
    - DIY Dog
    - Beer Recipes
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      PUNKAPI_BASE_URL: PUNKAPI_BASE_URL

capability:

  consumes:
    - type: http
      namespace: "punkapi-beers"
      baseUri: "https://api.punkapi.com/v2"
      description: "Punk API v2 Beers surface. No authentication required. Historical endpoint (decommissioned 2023) — override PUNKAPI_BASE_URL to point at a self-hosted mirror."
      resources:
        - name: "beers"
          path: "/beers"
          operations:
            - name: "listBeers"
              method: GET
              description: "Paginated list of BrewDog DIY Dog beer recipes with rich query filters."
              inputParameters:
                - name: "page"
                  in: query
                  type: integer
                  required: false
                  description: "Page number (1-indexed)."
                - name: "per_page"
                  in: query
                  type: integer
                  required: false
                  description: "Items per page (1-80, default 25)."
                - name: "abv_gt"
                  in: query
                  type: number
                  required: false
                  description: "ABV strictly greater than this value."
                - name: "abv_lt"
                  in: query
                  type: number
                  required: false
                  description: "ABV strictly less than this value."
                - name: "ibu_gt"
                  in: query
                  type: number
                  required: false
                  description: "IBU strictly greater than this value."
                - name: "ibu_lt"
                  in: query
                  type: number
                  required: false
                  description: "IBU strictly less than this value."
                - name: "ebc_gt"
                  in: query
                  type: number
                  required: false
                  description: "EBC colour strictly greater than this value."
                - name: "ebc_lt"
                  in: query
                  type: number
                  required: false
                  description: "EBC colour strictly less than this value."
                - name: "beer_name"
                  in: query
                  type: string
                  required: false
                  description: "Substring match on beer name (underscores for spaces)."
                - name: "hops"
                  in: query
                  type: string
                  required: false
                  description: "Substring match on hop name (underscores for spaces)."
                - name: "malt"
                  in: query
                  type: string
                  required: false
                  description: "Substring match on malt name (underscores for spaces)."
                - name: "yeast"
                  in: query
                  type: string
                  required: false
                  description: "Substring match on yeast strain name."
                - name: "food"
                  in: query
                  type: string
                  required: false
                  description: "Substring match on a food-pairing entry."
                - name: "brewed_before"
                  in: query
                  type: string
                  required: false
                  description: "Brewed-before date in mm-yyyy format."
                - name: "brewed_after"
                  in: query
                  type: string
                  required: false
                  description: "Brewed-after date in mm-yyyy format."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "beer"
          path: "/beers/{beerId}"
          operations:
            - name: "getBeer"
              method: GET
              description: "Get a single beer recipe by integer id."
              inputParameters:
                - name: "beerId"
                  in: path
                  type: integer
                  required: true
                  description: "Beer identifier (1-325)."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "random-beer"
          path: "/beers/random"
          operations:
            - name: "getRandomBeer"
              method: GET
              description: "Get a uniformly random beer recipe."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "punkapi-beers-rest"
      port: 8080
      description: "REST adapter for Punk API Beers. One resource per consumed operation under /v1."
      resources:
        - path: "/v1/beers"
          name: "beers"
          description: "List beers with recipe-oriented filters."
          operations:
            - method: GET
              name: "listBeers"
              description: "List BrewDog DIY Dog beer recipes."
              call: "punkapi-beers.listBeers"
              with:
                "page": "rest.page"
                "per_page": "rest.per_page"
                "abv_gt": "rest.abv_gt"
                "abv_lt": "rest.abv_lt"
                "ibu_gt": "rest.ibu_gt"
                "ibu_lt": "rest.ibu_lt"
                "ebc_gt": "rest.ebc_gt"
                "ebc_lt": "rest.ebc_lt"
                "beer_name": "rest.beer_name"
                "hops": "rest.hops"
                "malt": "rest.malt"
                "yeast": "rest.yeast"
                "food": "rest.food"
                "brewed_before": "rest.brewed_before"
                "brewed_after": "rest.brewed_after"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/beers/{beerId}"
          name: "beer"
          description: "Get a single beer recipe by id."
          operations:
            - method: GET
              name: "getBeer"
              description: "Get a beer by id."
              call: "punkapi-beers.getBeer"
              with:
                "beerId": "rest.beerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/beers/random"
          name: "random-beer"
          description: "Get a random beer recipe."
          operations:
            - method: GET
              name: "getRandomBeer"
              description: "Get a uniformly random beer."
              call: "punkapi-beers.getRandomBeer"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      namespace: "punkapi-beers-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Punk API Beers. One verb-noun tool per consumed operation."
      tools:
        - name: "list-beers"
          description: "List BrewDog DIY Dog beer recipes with optional ABV/IBU/EBC/date/ingredient filters."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "punkapi-beers.listBeers"
          with:
            "page": "tools.page"
            "per_page": "tools.per_page"
            "abv_gt": "tools.abv_gt"
            "abv_lt": "tools.abv_lt"
            "ibu_gt": "tools.ibu_gt"
            "ibu_lt": "tools.ibu_lt"
            "ebc_gt": "tools.ebc_gt"
            "ebc_lt": "tools.ebc_lt"
            "beer_name": "tools.beer_name"
            "hops": "tools.hops"
            "malt": "tools.malt"
            "yeast": "tools.yeast"
            "food": "tools.food"
            "brewed_before": "tools.brewed_before"
            "brewed_after": "tools.brewed_after"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "get-beer"
          description: "Get a single beer recipe by id (1-325)."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "punkapi-beers.getBeer"
          with:
            "beerId": "tools.beerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "get-random-beer"
          description: "Get a uniformly random beer recipe from the DIY Dog dataset."
          hints:
            readOnly: true
            destructive: false
            idempotent: false
          call: "punkapi-beers.getRandomBeer"
          outputParameters:
            - type: object
              mapping: "$."