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: "$."