brewers-almanack 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gregario
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+<p align="center">
+  <h1 align="center">Brewers Almanack</h1>
+  <p align="center">A brewing knowledge MCP server — beer styles, ingredients, off-flavour diagnosis, water chemistry, and recipe guidance for AI assistants.</p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/brewers-almanack"><img src="https://img.shields.io/npm/v/brewers-almanack.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/brewers-almanack"><img src="https://img.shields.io/npm/dm/brewers-almanack.svg" alt="npm downloads"></a>
+  <a href="https://github.com/gregario/brewers-almanack/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT Licence"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js 18+"></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-purple.svg" alt="MCP Compatible"></a>
+</p>
+
+---
+
+Ask your AI assistant about beer styles, diagnose off-flavours, build recipes, match water profiles, and pair food — all backed by real brewing data, not hallucinations.
+
+**6 tools. Zero config. Works with every MCP-compatible IDE.**
+
+## Install
+
+```bash
+npx -y brewers-almanack
+```
+
+No API keys, no network dependencies. All brewing data is embedded.
+
+### Add to your IDE
+
+<details open>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add brewers-almanack -- npx -y brewers-almanack
+```
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
+```json
+{
+  "mcpServers": {
+    "brewers-almanack": {
+      "command": "npx",
+      "args": ["-y", "brewers-almanack"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "brewers-almanack": {
+      "command": "npx",
+      "args": ["-y", "brewers-almanack"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>VS Code (Copilot)</strong></summary>
+
+Add to `.vscode/mcp.json`:
+```json
+{
+  "servers": {
+    "brewers-almanack": {
+      "command": "npx",
+      "args": ["-y", "brewers-almanack"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "brewers-almanack": {
+      "command": "npx",
+      "args": ["-y", "brewers-almanack"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Zed</strong></summary>
+
+Add to `settings.json`:
+```json
+{
+  "context_servers": {
+    "brewers-almanack": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "brewers-almanack"]
+      }
+    }
+  }
+}
+```
+</details>
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_styles` | Search 85 BJCP beer styles by name, category, or characteristics. Returns vital statistics, overall impression, ingredients, and commercial examples. |
+| `search_ingredients` | Search hops, malts, yeasts, and adjuncts by name, type, or characteristic. Filter by category or search across all. |
+| `diagnose_off_flavour` | Identify off-flavours from taste or aroma descriptions. Returns the likely compound, causes, prevention steps, and styles where it may be acceptable. |
+| `match_water_profile` | Find brewing water profiles by city name or beer style. Returns mineral composition (Ca, Mg, Na, Cl, SO4, HCO3) and style recommendations. |
+| `suggest_recipe` | Generate a recipe for a target beer style. Returns grain bill, hop schedule, yeast selection, water profile, and process parameters. |
+| `pairing_guide` | Beer and food pairing suggestions. Search by beer style or dish name. Returns matches with complement, contrast, and cleanse principles. |
+
+## Example Conversations
+
+**"What hops work in a Belgian Dubbel?"**
+> Searches ingredients for hops that complement Belgian styles — returns varieties like Styrian Goldings and Saaz with alpha acid ranges, aromas, and substitutes.
+
+**"My beer tastes like butter — what went wrong?"**
+> Diagnoses diacetyl: identifies the compound, explains causes (incomplete fermentation, premature racking), and gives prevention steps (diacetyl rest, healthy yeast pitch).
+
+**"Suggest a recipe for a West Coast IPA"**
+> Builds a complete recipe: pale malt base with crystal malt, Centennial/Cascade hop schedule with dry hop additions, American ale yeast, and a Burton-style water profile.
+
+**"What food pairs well with a stout?"**
+> Returns pairing suggestions — oysters, chocolate desserts, grilled meats — with principles explaining why each pairing works (complement, contrast, or cleanse).
+
+## Data Sources
+
+| Dataset | Records | Source | Licence / Basis |
+|---------|---------|--------|-----------------|
+| Beer styles | 85 | [BJCP 2021 Guidelines](https://www.bjcp.org/style/2021/beer/) via [beerjson/bjcp-json](https://github.com/beerjson/bjcp-json) | MIT; BJCP attribution |
+| Hops | 113 | [kasperg3/HopDatabase](https://github.com/kasperg3/HopDatabase) | MIT |
+| Malts | 38 | Compiled from published maltster spec sheets | Factual data |
+| Yeasts | 33 | Compiled from published yeast lab spec sheets | Factual data |
+| Adjuncts | 21 | Compiled from brewing literature | Factual data |
+| Water profiles | 20 | Compiled from brewing literature | Factual data |
+| Off-flavours | 25 | Compiled from brewing science literature | Factual data |
+| Food pairings | 23 | Compiled from Cicerone curriculum and pairing guides | Factual data |
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for planned features: brewing calculators, recipe intelligence, BeerXML/BeerJSON integration, and a brewing journal.
+
+## Contributing
+
+Contributions are welcome — especially data contributions. More hop varieties, yeast strains, regional water profiles, and food pairings make the server more useful for everyone.
+
+```bash
+git clone https://github.com/gregario/brewers-almanack.git
+cd brewers-almanack
+npm install
+npm run build
+npm test        # 73 tests
+```
+
+### Running locally
+
+```bash
+claude mcp add brewers-almanack-dev -- node /path/to/brewers-almanack/dist/index.js
+```
+
+See [ROADMAP.md](ROADMAP.md) for areas where contributions are most needed.
+
+## Licence
+
+[MIT](LICENSE)

package/dist/data/adjuncts.d.ts

@@ -0,0 +1,3 @@
+import type { Adjunct } from "../types.js";
+export declare const ADJUNCTS: Adjunct[];
+//# sourceMappingURL=adjuncts.d.ts.map

package/dist/data/adjuncts.js

@@ -0,0 +1,168 @@
+// Common brewing adjuncts: sugars, finings, grains, spices, and flavourings.
+export const ADJUNCTS = [
+    // ── Sugars ──────────────────────────────────────────────────────────
+    {
+        name: "Corn Sugar (Dextrose)",
+        type: "sugar",
+        fermentable: true,
+        usageRate: "5-20% of grist, or 120g per 19L for priming",
+        effect: "Raises ABV without adding body or flavour. Dries out the beer and lightens colour.",
+        description: "Pure glucose monosaccharide. The most common priming sugar and a popular adjunct for boosting gravity in Belgian and American styles.",
+    },
+    {
+        name: "Table Sugar (Sucrose)",
+        type: "sugar",
+        fermentable: true,
+        usageRate: "5-20% of grist, or 100g per 19L for priming",
+        effect: "Fully fermentable. Thins body and boosts ABV without adding flavour.",
+        description: "Common cane or beet sugar. Fully fermentable by brewing yeast. Used in Belgian brewing traditions and for bottle conditioning.",
+    },
+    {
+        name: "Belgian Candi Sugar (Light)",
+        type: "sugar",
+        fermentable: true,
+        usageRate: "5-20% of grist",
+        effect: "Increases ABV while keeping the beer light and dry. Adds subtle warmth.",
+        description: "Crystallised beet sugar used in Belgian tripels and golden strong ales. Lightens body while boosting alcohol content.",
+    },
+    {
+        name: "Belgian Candi Sugar (Dark)",
+        type: "sugar",
+        fermentable: true,
+        usageRate: "5-15% of grist",
+        effect: "Adds dark fruit, caramel, and toffee flavours. Deepens colour and raises ABV.",
+        description: "Caramelised beet sugar essential in Belgian dubbels and dark strong ales. Provides complex dark fruit and burnt sugar character.",
+    },
+    {
+        name: "Honey",
+        type: "sugar",
+        fermentable: true,
+        usageRate: "5-30% of grist by weight",
+        effect: "Adds delicate floral sweetness and dries out the finish. Flavour character varies by variety.",
+        description: "Natural honey added to braggots, honey ales, and Belgian styles. Most honey character ferments out; add at flameout to preserve aroma.",
+    },
+    {
+        name: "Molasses",
+        type: "sugar",
+        fermentable: true,
+        usageRate: "2-10% of grist",
+        effect: "Adds deep, earthy, slightly bitter sweetness and dark colour.",
+        description: "By-product of sugar refining. Used in old ales, strong dark ales, and some stouts. Adds a rustic, treacle-like complexity.",
+    },
+    {
+        name: "Lactose",
+        type: "sugar",
+        fermentable: false,
+        usageRate: "150-500g per 19L",
+        effect: "Adds residual sweetness and body. Not fermentable by Saccharomyces yeast.",
+        description: "Milk sugar used in milk stouts, pastry stouts, and milkshake IPAs. Provides a creamy, sweet body since brewing yeast cannot ferment it.",
+    },
+    // ── Finings ─────────────────────────────────────────────────────────
+    {
+        name: "Irish Moss",
+        type: "fining",
+        fermentable: false,
+        usageRate: "1 tsp (5g) per 19L, added 15 min before end of boil",
+        effect: "Clarifies wort by coagulating proteins. Reduces chill haze.",
+        description: "Dried red seaweed (Chondrus crispus). A traditional kettle fining that promotes hot break formation and protein coagulation.",
+    },
+    {
+        name: "Whirlfloc",
+        type: "fining",
+        fermentable: false,
+        usageRate: "1 tablet per 19L, added 5-10 min before end of boil",
+        effect: "Clarifies wort by attracting and settling proteins and tannins.",
+        description: "Concentrated tablet form of Irish moss blended with purified carrageenan. More convenient and consistent than raw Irish moss.",
+    },
+    {
+        name: "Gelatin",
+        type: "fining",
+        fermentable: false,
+        usageRate: "1-2 tsp dissolved in 150ml warm water per 19L",
+        effect: "Clarifies beer by binding to polyphenols and yeast. Used cold-side.",
+        description: "Animal-derived collagen protein. An effective cold-side fining agent that drops yeast and haze particles out of suspension rapidly.",
+    },
+    {
+        name: "Isinglass",
+        type: "fining",
+        fermentable: false,
+        usageRate: "Per manufacturer instructions, typically 1-2ml per litre",
+        effect: "Attracts yeast cells and clarifies cask-conditioned ales.",
+        description: "Collagen derived from fish swim bladders. The traditional cask ale fining, prized for producing brilliant clarity while preserving flavour.",
+    },
+    // ── Grains ──────────────────────────────────────────────────────────
+    {
+        name: "Flaked Rice",
+        type: "grain",
+        fermentable: true,
+        usageRate: "10-40% of grist",
+        effect: "Lightens body and colour. Produces a dry, crisp finish.",
+        description: "Pre-gelatinised rice flakes. Used in Japanese lagers and American light lagers to produce a clean, light, refreshing beer.",
+    },
+    {
+        name: "Flaked Maize",
+        type: "grain",
+        fermentable: true,
+        usageRate: "10-30% of grist",
+        effect: "Lightens body, adds subtle corn sweetness, smooths flavour.",
+        description: "Pre-gelatinised corn flakes. Traditional adjunct in American lagers and cream ales. Adds a subtle sweet corn character.",
+    },
+    {
+        name: "Torrified Wheat",
+        type: "grain",
+        fermentable: true,
+        usageRate: "5-15% of grist",
+        effect: "Improves head retention, adds body, increases haze.",
+        description: "Wheat kernels heated until puffed. Adds protein for head retention and a bready character. Common in English bitters.",
+    },
+    // ── Spices & Flavourings ────────────────────────────────────────────
+    {
+        name: "Coriander Seed",
+        type: "spice",
+        fermentable: false,
+        usageRate: "15-30g per 19L, added at flameout",
+        effect: "Adds citrusy, slightly spicy, lemony character.",
+        description: "Dried coriander seeds, lightly crushed before use. A defining ingredient in Belgian witbiers alongside orange peel.",
+    },
+    {
+        name: "Orange Peel (Bitter)",
+        type: "spice",
+        fermentable: false,
+        usageRate: "15-30g per 19L, added at flameout",
+        effect: "Adds bitter citrus aroma and a zesty, marmalade-like character.",
+        description: "Dried Curaçao or Seville orange peel. Essential in Belgian witbiers and many Belgian ales. Provides a complex bitter citrus note.",
+    },
+    {
+        name: "Vanilla Beans",
+        type: "spice",
+        fermentable: false,
+        usageRate: "1-3 beans per 19L, split and scraped, added to secondary",
+        effect: "Adds smooth vanilla flavour and aroma. Rounds out roasted and sweet flavours.",
+        description: "Whole vanilla pods added to secondary fermentation. Popular in porters, stouts, cream ales, and pastry-style beers.",
+    },
+    {
+        name: "Cacao Nibs",
+        type: "spice",
+        fermentable: false,
+        usageRate: "60-120g per 19L, added to secondary for 3-7 days",
+        effect: "Adds roasted chocolate character without sweetness. Enhances malt complexity.",
+        description: "Roasted, hulled cocoa beans. Adds genuine chocolate aroma and flavour to porters, stouts, and chocolate-themed beers.",
+    },
+    {
+        name: "Coffee",
+        type: "spice",
+        fermentable: false,
+        usageRate: "30-60g coarsely ground per 19L, cold-steeped or added to secondary",
+        effect: "Adds coffee aroma and flavour. Complements roasted malt character.",
+        description: "Coarsely ground coffee beans, often cold-steeped to avoid astringency. Popular in coffee stouts, porters, and breakfast-style beers.",
+    },
+    {
+        name: "Ginger",
+        type: "spice",
+        fermentable: false,
+        usageRate: "15-60g fresh grated per 19L, added at flameout",
+        effect: "Adds a warm, spicy, pungent heat and zesty aroma.",
+        description: "Fresh ginger root, peeled and grated. Used in ginger beers, saisons, wheat ales, and seasonal spiced ales.",
+    },
+];
+//# sourceMappingURL=adjuncts.js.map

package/dist/data/adjuncts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adjuncts.js","sourceRoot":"","sources":["../../src/data/adjuncts.ts"],"names":[],"mappings":"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"}

package/dist/data/hops.d.ts

@@ -0,0 +1,3 @@
+import type { Hop } from "../types.js";
+export declare const HOPS: Hop[];
+//# sourceMappingURL=hops.d.ts.map