mcp-server-brewfather 0.1.0__tar.gz

mcp_server_brewfather-0.1.0/.env.example

@@ -0,0 +1,4 @@
+# Brewfather API credentials — generate in Brewfather: Settings → API → Generate API Key.
+# Grant only the scopes you want this server to have (see README "Security posture").
+export BREWFATHER_USER_ID=your_user_id
+export BREWFATHER_API_KEY=your_api_key

mcp_server_brewfather-0.1.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+# Keep GitHub Actions pinned to immutable SHAs current. The workflows
+# pin actions to commit SHAs (not floating tags); Dependabot opens PRs
+# that bump both the SHA and the trailing `# vX.Y.Z` comment when new
+# releases land.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly

mcp_server_brewfather-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,119 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  # PR title validation - must NOT use conventional commit format
+  # (conventional format is for commit messages only; PR titles are descriptive)
+  pr-title:
+    name: PR Title Check
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
+        with:
+          egress-policy: audit
+
+      - name: Check PR title is not conventional commit format
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          # Exempt release-please and Dependabot PRs
+          if echo "$PR_TITLE" | grep -qE "^chore\(main\): release [0-9]"; then
+            echo "✅ Release-please PR exempt"
+            exit 0
+          fi
+          if echo "$PR_TITLE" | grep -qE "^chore\(deps(-dev)?\): [Bb]ump "; then
+            echo "✅ Dependabot PR exempt"
+            exit 0
+          fi
+
+          PATTERN="^(feat|fix|perf|docs|refactor|ci|chore)(\(.+\))?!?:"
+          if echo "$PR_TITLE" | grep -qE "$PATTERN"; then
+            echo "::error::PR title should NOT use conventional commit format."
+            echo "::error::Use a descriptive title (e.g., 'Add reorder support' not 'feat: add reorder support')."
+            exit 1
+          fi
+          echo "✅ PR title format is valid"
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      # Unit tests only. The acceptance suite hits the live Brewfather API and needs
+      # user credentials, so it is intentionally not run in CI (stays local/manual).
+      - name: Run unit tests
+        run: uv run pytest
+
+  # CI gate job for simplified branch protection — this is the "CI Success"
+  # status check referenced by the repository ruleset.
+  ci-success:
+    name: CI Success
+    runs-on: ubuntu-latest
+    needs: [pr-title, lint, test]
+    if: always()
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
+        with:
+          egress-policy: audit
+
+      - name: Check all jobs passed
+        run: |
+          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
+            echo "❌ Some jobs failed"
+            exit 1
+          fi
+          if [[ "${{ contains(needs.*.result, 'cancelled') }}" == "true" ]]; then
+            echo "❌ Some jobs were cancelled"
+            exit 1
+          fi
+          echo "✅ All CI jobs passed"

mcp_server_brewfather-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,76 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Authenticate via a dedicated GitHub App (token minted at job time) rather
+# than GITHUB_TOKEN. Events generated by the default GITHUB_TOKEN do not
+# trigger downstream workflows, so the tag release-please pushes would never
+# run release.yml (PyPI publish). App-minted tokens are treated as first-class
+# actors and do trigger downstream workflows.
+permissions: {}
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
+        with:
+          egress-policy: audit
+
+      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        id: app-token
+        with:
+          client-id: ${{ secrets.RELEASE_PLEASE_APP_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_PLEASE_APP_PRIVATE_KEY }}
+
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      # release-please bumps the version in pyproject.toml but not uv.lock, and
+      # the lock records the root project's own version, so `uv sync --locked`
+      # fails on the release PR — and on main once it merges.
+      #
+      # Find the open release PR directly rather than using the action's `pr`
+      # output: that output is set only when release-please creates or updates
+      # a PR. A commit of a hidden changelog type (ci, chore, docs) leaves the
+      # PR unchanged — no output — while still rebuilding the release branch on
+      # top of the new main, which drops any earlier lock-sync commit.
+      #
+      # `--repo` is required: no checkout has happened, so gh has no remote.
+      - id: release_pr
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          branch=$(gh pr list --repo "${{ github.repository }}" --state open --limit 100 --json headRefName \
+            --jq '[.[] | select(.headRefName | startswith("release-please--"))][0].headRefName // ""')
+          echo "branch=$branch" >> "$GITHUB_OUTPUT"
+
+      - if: ${{ steps.release_pr.outputs.branch }}
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ steps.release_pr.outputs.branch }}
+          token: ${{ steps.app-token.outputs.token }}
+
+      - if: ${{ steps.release_pr.outputs.branch }}
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+
+      # Idempotent: when the lock is already in sync nothing is pushed.
+      - if: ${{ steps.release_pr.outputs.branch }}
+        name: Sync uv.lock with the bumped version
+        run: |
+          uv lock
+          if git diff --quiet uv.lock; then
+            echo "uv.lock already in sync; nothing to push."
+            exit 0
+          fi
+          git config user.name "release-please[bot]"
+          git config user.email "release-please[bot]@users.noreply.github.com"
+          git commit -m "chore: sync uv.lock with release version" -- uv.lock
+          git push

mcp_server_brewfather-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    # Trusted publishing: PyPI issues a short-lived token in exchange for a
+    # GitHub-signed OIDC assertion, so no API token is stored in the repo. The
+    # trust relationship is configured once on PyPI (pin this repo + workflow).
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

mcp_server_brewfather-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+
+# Secrets / local config
+.env

mcp_server_brewfather-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

mcp_server_brewfather-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

mcp_server_brewfather-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-09-28)
+
+
+### Features
+
+* add create_recipe tool ([25eb043](https://github.com/cacack/mcp-server-brewfather/commit/25eb043f07651a2195c688d8d0b449f5e6fe7feb))
+* add update_recipe tool for editing recipe settings and ingredients ([0241cdf](https://github.com/cacack/mcp-server-brewfather/commit/0241cdf73147b09a7e028f643ee95701820c5f9f))
+* fetch only the latest reading when get_readings limit is 1 ([10d3361](https://github.com/cacack/mcp-server-brewfather/commit/10d33610e1f7e52a6015475dcb0c1e7ff87a1c26)), closes [#10](https://github.com/cacack/mcp-server-brewfather/issues/10)
+* migrate to mcp 2 MCPServer ([77dd155](https://github.com/cacack/mcp-server-brewfather/commit/77dd1559f7326a1e8789906f2d459db7fcb0096c))
+* scaffold Brewfather MCP server ([82b09ed](https://github.com/cacack/mcp-server-brewfather/commit/82b09ed3e4e8b161ea3e9ead97a184477438c5c7))
+
+
+### Bug Fixes
+
+* harden get_readings limit=1 per panel review ([509a075](https://github.com/cacack/mcp-server-brewfather/commit/509a075fbb965602f4d8edbb3a0c5f5611628564)), closes [#10](https://github.com/cacack/mcp-server-brewfather/issues/10)
+* project batch estimates and drop boolean measured flags ([c0a1e28](https://github.com/cacack/mcp-server-brewfather/commit/c0a1e2816078ef5e338c54d3a955d5471741d554))

mcp_server_brewfather-0.1.0/CLAUDE.md

@@ -0,0 +1,38 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+MCP server (Python, mcp 2 `MCPServer` over stdio) wrapping the Brewfather v2 REST API. User docs, tool table, and setup live in README.md.
+
+## Commands
+
+```bash
+uv sync                                   # install (incl. dev group)
+uv run ruff check . && uv run ruff format --check .
+uv run pytest                             # unit tests; acceptance auto-skipped
+uv run pytest tests/unit/test_server.py::test_find_batches_rejects_unknown_status
+uv run pytest --run-acceptance            # live read-only API checks; needs BREWFATHER_USER_ID/API_KEY
+```
+
+## Architecture
+
+Three modules in `src/mcp_server_brewfather/`, layered one direction:
+
+- `client.py` — httpx wrapper: Basic auth from env, `start_after` pagination (`PAGE_SIZE` 50), and every failure (incl. 429) raised as `BrewfatherError` with a model-readable message. PATCH endpoints return plain text, not JSON.
+- `normalize.py` — projects multi-KB API objects down to compact dicts; epoch-ms → ISO; missing/None fields omitted, never returned as null.
+- `server.py` — the `@mcp.tool()` functions. Validate all input (statuses, measurement keys, inventory kinds) *before* any request is sent.
+
+Tools must call `client.get_client()` through the module (not `from .client import get_client`): the `fake_api` fixture in `tests/conftest.py` monkeypatches that attribute. `fake_api` routes `(method, path)` to a body, a list of pages (list of lists), or an `httpx.Response`, and records requests for assertions.
+
+## Constraints
+
+- No tool may call a delete endpoint. The API key's scopes are the trust boundary.
+- The API accepts any field silently and never computes recipe stats (the app does). Writes go through field allowlists in `server.py`; never make stats writable.
+- Recipe ingredient lists are replaced wholesale on PATCH — send full raw items, never the compact projection.
+- Keep dependencies to `mcp` and `httpx`.
+- Raise `ToolError` (or `BrewfatherError`, a subclass) for anything the model should read: mcp 2 replaces any other exception's message with a generic "Error executing tool".
+- API is metric-only (SG, L, kg/g, °C).
+- Acceptance tests must stay read-only. Detail fields added to `normalize.py` should be verified there against live objects.
+- Adding/changing a tool: update the README tool table and the `server.py` module docstring.
+- Commits use conventional format; PR titles must **not** (CI enforces).
+- Releases: release-please (`release-please.yml`, GitHub App token) opens the release PR and syncs `uv.lock` on it; the `v*` tag it creates triggers `release.yml`, which publishes to PyPI via trusted publishing. Never bump versions or tag by hand.

mcp_server_brewfather-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Clonch
+
+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.

mcp_server_brewfather-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: mcp-server-brewfather
+Version: 0.1.0
+Summary: MCP server for Brewfather: read batches, recipes, readings, and inventory; create and edit recipes; update batch status and stock
+Project-URL: Homepage, https://github.com/cacack/mcp-server-brewfather
+Project-URL: Repository, https://github.com/cacack/mcp-server-brewfather
+Project-URL: Issues, https://github.com/cacack/mcp-server-brewfather/issues
+Author-email: Chris Clonch <chris@theclonchs.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: brewfather,brewing,homebrew,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Requires-Dist: mcp[cli]<3,>=2.2
+Description-Content-Type: text/markdown
+
+# mcp-server-brewfather
+
+An MCP server for the [Brewfather](https://brewfather.app) API. It lets an LLM read
+your batches, recipes, fermentation readings, and inventory, and make the routine
+writes that come up while brewing: advancing a batch's status, logging measured
+gravities and volumes, tweaking a recipe, and adjusting stock after brew day.
+
+Brewfather has no official MCP server; this wraps the public
+[v2 API](https://docs.brewfather.app/api) directly.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `find_batches(name?, status?)` | Find batches by name substring and/or status → `{id, name, batch_no, status, brewer, brew_date, recipe}` |
+| `get_batch(batch_id)` | Batch summary, measured values, and embedded recipe (stats + ingredient bill) |
+| `get_readings(batch_id, limit?)` | Most recent hydrometer/sensor readings, oldest→newest (`limit=0` for all; `limit=1` fetches only the latest reading, without `total`) |
+| `update_batch(batch_id, status?, measurements?)` | Set status and/or `measured*` values (validated before sending) |
+| `find_recipes(name?)` | Find recipes by name substring → `{id, name, author, type, style, equipment}` |
+| `get_recipe(recipe_id)` | Target stats (OG, FG, ABV, IBU, color, …) and ingredient bill |
+| `create_recipe(name, type?, fields?, ingredients?)` | New All Grain or Extract recipe with settings and an ingredient bill |
+| `update_recipe(recipe_id, fields?, ingredients?)` | Change settings (batch size, boil time, efficiency, …) and add/change/remove ingredients |
+| `list_inventory(kind, name?, in_stock_only?)` | Fermentables, hops, miscs, or yeasts in stock |
+| `set_inventory(kind, item_id, amount? \| adjust?)` | Set absolute stock, or add/subtract |
+
+All values are metric (SG, liters, kg/g, °C) — the API accepts nothing else.
+Timestamps are returned as ISO-8601 UTC.
+
+Brewfather computes recipe stats (OG, FG, ABV, IBU, color) in the app, not the API.
+After `create_recipe` or `update_recipe`, the app shows correct stats as soon as you
+open the recipe, but `get_recipe` returns the stored values, which the API never
+calculates (a new recipe has none).
+Stats can't be written through this server.
+
+## Setup
+
+### 1. Generate an API key
+
+In Brewfather: **Settings → API → Generate API Key**. Pick scopes to match what you
+want the server to do (see [Security posture](#security-posture)). Note the
+**User ID** shown alongside the key.
+
+### 2. Install
+
+Requires Python **3.12+**. With [uv](https://docs.astral.sh/uv/), there is nothing
+to install: `uvx` fetches and runs the published package. Otherwise:
+
+```bash
+pip install mcp-server-brewfather
+# or, isolated:
+pipx install mcp-server-brewfather
+```
+
+## Register with Claude
+
+Claude Code:
+
+```bash
+claude mcp add brewfather --scope user \
+  -e BREWFATHER_USER_ID=your_user_id -e BREWFATHER_API_KEY=your_api_key \
+  -- uvx mcp-server-brewfather
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "brewfather": {
+      "command": "uvx",
+      "args": ["mcp-server-brewfather"],
+      "env": {
+        "BREWFATHER_USER_ID": "your_user_id",
+        "BREWFATHER_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+## Security posture
+
+- **The API key's scopes are the trust boundary.** For read-only use, grant only
+  `batches.read`, `recipes.read`, `inventory.read`. Add `batches.write` /
+  `recipes.write` / `inventory.write` to enable `update_batch` / `create_recipe` and
+  `update_recipe` / `set_inventory`. **Never grant `*.delete`** — no tool uses it.
+- No delete tools. Every write is checked against an allowlist of fields before
+  it's sent, because the API silently accepts unknown fields.
+- **Two dependencies only** (`mcp`, `httpx` — the latter already required by `mcp`);
+  pinned via the committed `uv.lock`.
+- Credentials live in a gitignored `.env` / Claude config.
+
+## Rate limits
+
+Brewfather allows **500 calls per hour per API key**. List tools page 50 items per
+call, so `find_*`/`list_inventory` cost one call per 50 items. A rate-limited call
+surfaces as an error naming the `Retry-After` delay.
+
+## Development
+
+```bash
+cp .env.example .env             # then fill in your user id / API key
+source .env
+uv sync                          # install deps (incl. dev group)
+uv run ruff check .              # lint
+uv run ruff format .             # format
+uv run pytest                    # unit tests (acceptance auto-skipped)
+uv run pytest --run-acceptance   # + live read-only API checks (needs BREWFATHER_* creds)
+```
+
+CI (GitHub Actions) runs the PR-title check, ruff lint/format, and the unit tests
+on every PR; the `CI Success` job is the aggregate gate. Acceptance tests are not
+run in CI — they need live credentials and stay local/manual. They are read-only
+and never modify your brewing data.
+
+Releases are automated: release-please keeps a release PR open from the
+conventional commits on `main`, and merging it tags `vX.Y.Z`, which triggers
+`release.yml` to publish to PyPI via trusted publishing.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_server_brewfather-0.1.0/README.md

@@ -0,0 +1,122 @@
+# mcp-server-brewfather
+
+An MCP server for the [Brewfather](https://brewfather.app) API. It lets an LLM read
+your batches, recipes, fermentation readings, and inventory, and make the routine
+writes that come up while brewing: advancing a batch's status, logging measured
+gravities and volumes, tweaking a recipe, and adjusting stock after brew day.
+
+Brewfather has no official MCP server; this wraps the public
+[v2 API](https://docs.brewfather.app/api) directly.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `find_batches(name?, status?)` | Find batches by name substring and/or status → `{id, name, batch_no, status, brewer, brew_date, recipe}` |
+| `get_batch(batch_id)` | Batch summary, measured values, and embedded recipe (stats + ingredient bill) |
+| `get_readings(batch_id, limit?)` | Most recent hydrometer/sensor readings, oldest→newest (`limit=0` for all; `limit=1` fetches only the latest reading, without `total`) |
+| `update_batch(batch_id, status?, measurements?)` | Set status and/or `measured*` values (validated before sending) |
+| `find_recipes(name?)` | Find recipes by name substring → `{id, name, author, type, style, equipment}` |
+| `get_recipe(recipe_id)` | Target stats (OG, FG, ABV, IBU, color, …) and ingredient bill |
+| `create_recipe(name, type?, fields?, ingredients?)` | New All Grain or Extract recipe with settings and an ingredient bill |
+| `update_recipe(recipe_id, fields?, ingredients?)` | Change settings (batch size, boil time, efficiency, …) and add/change/remove ingredients |
+| `list_inventory(kind, name?, in_stock_only?)` | Fermentables, hops, miscs, or yeasts in stock |
+| `set_inventory(kind, item_id, amount? \| adjust?)` | Set absolute stock, or add/subtract |
+
+All values are metric (SG, liters, kg/g, °C) — the API accepts nothing else.
+Timestamps are returned as ISO-8601 UTC.
+
+Brewfather computes recipe stats (OG, FG, ABV, IBU, color) in the app, not the API.
+After `create_recipe` or `update_recipe`, the app shows correct stats as soon as you
+open the recipe, but `get_recipe` returns the stored values, which the API never
+calculates (a new recipe has none).
+Stats can't be written through this server.
+
+## Setup
+
+### 1. Generate an API key
+
+In Brewfather: **Settings → API → Generate API Key**. Pick scopes to match what you
+want the server to do (see [Security posture](#security-posture)). Note the
+**User ID** shown alongside the key.
+
+### 2. Install
+
+Requires Python **3.12+**. With [uv](https://docs.astral.sh/uv/), there is nothing
+to install: `uvx` fetches and runs the published package. Otherwise:
+
+```bash
+pip install mcp-server-brewfather
+# or, isolated:
+pipx install mcp-server-brewfather
+```
+
+## Register with Claude
+
+Claude Code:
+
+```bash
+claude mcp add brewfather --scope user \
+  -e BREWFATHER_USER_ID=your_user_id -e BREWFATHER_API_KEY=your_api_key \
+  -- uvx mcp-server-brewfather
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "brewfather": {
+      "command": "uvx",
+      "args": ["mcp-server-brewfather"],
+      "env": {
+        "BREWFATHER_USER_ID": "your_user_id",
+        "BREWFATHER_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+## Security posture
+
+- **The API key's scopes are the trust boundary.** For read-only use, grant only
+  `batches.read`, `recipes.read`, `inventory.read`. Add `batches.write` /
+  `recipes.write` / `inventory.write` to enable `update_batch` / `create_recipe` and
+  `update_recipe` / `set_inventory`. **Never grant `*.delete`** — no tool uses it.
+- No delete tools. Every write is checked against an allowlist of fields before
+  it's sent, because the API silently accepts unknown fields.
+- **Two dependencies only** (`mcp`, `httpx` — the latter already required by `mcp`);
+  pinned via the committed `uv.lock`.
+- Credentials live in a gitignored `.env` / Claude config.
+
+## Rate limits
+
+Brewfather allows **500 calls per hour per API key**. List tools page 50 items per
+call, so `find_*`/`list_inventory` cost one call per 50 items. A rate-limited call
+surfaces as an error naming the `Retry-After` delay.
+
+## Development
+
+```bash
+cp .env.example .env             # then fill in your user id / API key
+source .env
+uv sync                          # install deps (incl. dev group)
+uv run ruff check .              # lint
+uv run ruff format .             # format
+uv run pytest                    # unit tests (acceptance auto-skipped)
+uv run pytest --run-acceptance   # + live read-only API checks (needs BREWFATHER_* creds)
+```
+
+CI (GitHub Actions) runs the PR-title check, ruff lint/format, and the unit tests
+on every PR; the `CI Success` job is the aggregate gate. Acceptance tests are not
+run in CI — they need live credentials and stay local/manual. They are read-only
+and never modify your brewing data.
+
+Releases are automated: release-please keeps a release PR open from the
+conventional commits on `main`, and merging it tags `vX.Y.Z`, which triggers
+`release.yml` to publish to PyPI via trusted publishing.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_server_brewfather-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "mcp-server-brewfather"
+version = "0.1.0"
+description = "MCP server for Brewfather: read batches, recipes, readings, and inventory; create and edit recipes; update batch status and stock"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Chris Clonch", email = "chris@theclonchs.com" }]
+keywords = ["brewfather", "homebrew", "brewing", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    # 2.x: MCPServer, and only ToolError messages reach the model (server.py).
+    "mcp[cli]>=2.2,<3",
+    # Already a transitive dependency of mcp; declared because client.py uses it directly.
+    "httpx>=0.28",
+]
+
+[project.urls]
+Homepage = "https://github.com/cacack/mcp-server-brewfather"
+Repository = "https://github.com/cacack/mcp-server-brewfather"
+Issues = "https://github.com/cacack/mcp-server-brewfather/issues"
+
+[project.scripts]
+mcp-server-brewfather = "mcp_server_brewfather.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_server_brewfather"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "acceptance: end-to-end tests that hit the live Brewfather API (require credentials; opt in with --run-acceptance)",
+]
+addopts = "--strict-markers"