# Brewfather MCP

[English Documentation](README.en.md)

这是一个在个人电脑上运行的模型上下文协议服务，可通过 Brewfather API v2 和 Brewfather 3.1 公开测试接口读取、搜索、创建及安全修改 Brewfather 配方。

服务使用本地标准输入输出通信。Brewfather 凭据只保存在用户自己的电脑中；创建和修改配方前，必须使用短时间有效的预览确认令牌。本服务有意不提供删除配方功能。

## 最简单的安装方式：让智能助手帮你安装（推荐）

这款工具主要面向不熟悉终端命令的家酿爱好者。你可以让能够访问本地终端并支持模型上下文协议的智能助手完成安装，例如 Codex、Claude Code、Cursor、Visual Studio Code 中的智能助手或 Gemini 命令行工具。

新建一个对话，复制下面这段话发给agent：

```text
请帮我安装https://github.com/plane636/brewfather-mcp.git项目，并注册到我正在使用的agent。

请你：
1. 检查本机是否有 Node.js 20 或更高版本；
2. 在当前项目目录安装依赖、构建项目并安装 brewfather-mcp 命令；
3. 自动识别我正在使用的agent，运行对应的 brewfather-mcp install 命令；
4. 如果打开本机授权页面，让我自己在页面中输入 Brewfather 用户编号和应用程序接口密钥。不要让我把密钥发到对话里，也不要输出或读取密钥内容；
5. 等我提交授权页面后，运行 brewfather-mcp doctor，并检查模型上下文协议服务是否已成功注册。

请直接开始执行；只有在必须由我操作授权页面时再提醒我。
```

3. 智能助手会打开一个仅本机可访问的授权页面。在页面中输入 Brewfather API ID和密钥key，然后提交。
4. 安装成功后，重启智能助手或新建对话，然后直接说：

```text
使用 Brewfather 工具列出我最近的 5 个配方。
```

> 纯网页智能助手通常无法安装运行在你电脑上的本地服务。请使用能够访问本地项目和终端的桌面版、集成开发环境智能助手或命令行智能助手。

## 使用条件

- Node.js 20 或更高版本
- Brewfather 高级版或有效的高级版试用
- 创建或修改配方时，需要加入 Brewfather 3.1 公开测试
- 具有 `recipes.read` 权限的 Brewfather 应用程序接口密钥；写入配方还需要 `recipes.write` 权限

## 从源代码安装

```bash
cd /path/to/brewfather-mcp
npm install
npm run build
npm link
```

打开本地凭据页面，并将服务注册到指定的智能助手：

```bash
brewfather-mcp install codex
```

设置页面只监听 `127.0.0.1` 的随机端口。它会通过只读请求验证凭据、在本机保存凭据，然后自动退出。请在 Brewfather 的“设置 → 应用程序接口”中生成密钥。无需授予 `recipes.delete` 权限，本服务不会使用该权限。

## 凭据保存位置

凭据以 JSON 格式保存在操作系统的用户配置目录中：

| 操作系统 | 默认路径 |
| --- | --- |
| macOS | `~/Library/Application Support/brewfather-mcp/config.json` |
| Windows | `%APPDATA%\\brewfather-mcp\\config.json` |
| Linux | `$XDG_CONFIG_HOME/brewfather-mcp/config.json`，未设置时使用 `~/.config/brewfather-mcp/config.json` |

可以通过 `BREWFATHER_MCP_CONFIG` 指定其他路径。在类 Unix 系统上，配置目录权限设为 `0700`，配置文件权限设为 `0600`。文件中包含明文凭据，请勿同步、分享或提交到版本库。容器和持续集成环境可以同时使用 `BREWFATHER_USER_ID` 和 `BREWFATHER_API_KEY` 环境变量。

常用命令：

```bash
brewfather-mcp setup
brewfather-mcp doctor
brewfather-mcp config path
brewfather-mcp auth logout
```

## 安装到不同智能助手

安装程序支持以下智能助手：

```bash
brewfather-mcp install codex
brewfather-mcp install claude
brewfather-mcp install cursor
brewfather-mcp install vscode
brewfather-mcp install gemini
brewfather-mcp install all
brewfather-mcp install generic
```

安装程序会尽量使用各智能助手的官方命令行工具：

- Codex：`codex mcp add`
- Claude Code：`claude mcp add --scope user`
- Cursor：`agent mcp add`
- Visual Studio Code：`code --add-mcp`
- Gemini：`gemini mcp add --scope user`

`generic` 会输出供其他兼容客户端使用的标准 `mcpServers` JSON 配置。注册命令使用当前 Node.js 可执行文件和本软件编译入口的绝对路径，因此智能助手配置中不会出现 Brewfather 凭据。

## 在新对话中使用

新建一个智能助手对话，然后说：

```text
使用 Brewfather 工具列出我最近的 5 个配方，只读取，不要修改。
```

如需修改配方，可以说：

```text
使用 Brewfather 工具找到“West Coast IPA”，把其中的 Citra 干投增加 20 克。先显示修改预览，等我明确确认后再写入。
```

## 可用工具

- `brewfather_connection_status`
- `brewfather_list_recipes`
- `brewfather_search_recipes`
- `brewfather_get_recipe`
- `brewfather_preview_recipe_create`
- `brewfather_apply_recipe_create`
- `brewfather_preview_recipe_update`
- `brewfather_apply_recipe_update`

为避免 Brewfather 在写入时拒绝或静默改变数据，生成预览时会先执行以下检查：

- Brewfather 写入接口不接受字符串标签。除非从现有配方中复制完整的标签对象，否则应省略 `tags`。
- 添加剂单位限为 `g`、`mg`、`kg`、`ml`、`l`、`tsp`、`tbsp`、`pkg`、`items` 或 `drops`。`tablet` 和 `dose` 等常用别名会自动转为 `items`。
- 麦芽只有 Lovibond 色度而没有 `color` 时，工具会自动计算 EBC，避免 Brewfather 将色度保存为 0。
- 所有自动转换都会在预览的 `normalizations` 中列出，应与其他更改一起交由用户确认。

创建和修改配方的确认令牌在十分钟后失效，并且只能使用一次。修改配方前，服务会再次读取配方；如果配方在生成预览后发生了变化，本次写入将被拒绝。

修改参数中的嵌套对象会在本地进行深度合并。由于 Brewfather 的配方部分更新接口只对顶层字段进行浅合并，数组会被完整替换。修改前应先读取当前配方，并传入完整的 `fermentables`、`hops`、`yeasts` 或 `miscs` 数组。

Brewfather 数值统一使用公制单位：升、千克、克、摄氏度和比重。

## 开发

```bash
npm run typecheck
npm test
npm run build
```

构建完成后，可运行模型上下文协议检查器：

```bash
npx @modelcontextprotocol/inspector node dist/cli.js serve
```

协议通信使用标准输出。运行诊断只写入标准错误，授权请求头和应用程序接口密钥不会被记录。

## 接口说明

- REST 接口路径版本仍为 `/v2`；配方写入功能属于 Brewfather 3.1 公开测试。
- 应用程序接口使用 HTTP 基本认证，Brewfather 用户编号作为用户名。
- Brewfather 目前限制每个密钥每小时最多调用 500 次。
- 本服务不提供配方版本创建、锁定、恢复、回滚或删除功能。

请参阅 [Brewfather 应用程序接口文档](https://docs.brewfather.app/api)和[版本 3.1 公开测试说明](https://docs.brewfather.app/beta)。