BrewSource MCP 服务器 🍺

一个用Go语言构建的、用于酿造资源的综合模型上下文协议（MCP）服务器。

这是什么？

BrewSource MCP 翻译为中文是：“BrewSource 多客户平台（或特定模块/组件，具体根据上下文确定MCP的含义）”。不过，由于“MCP”可能是一个特定于BrewSource或其上下文环境的术语，没有统一的翻译标准，所以这里的翻译是基于一般理解给出的。如果“MCP”在BrewSource中有特定的含义，那么应该根据该含义来翻译这是一个专门的MCP服务器，为AI助手提供必要的酿酒知识和工具。目前在 第一阶段最小可行性产品（MVP），它聚焦于核心公共资源：

啤酒与酿酒厂探索之旅 - 搜索基本的商业啤酒和酿酒厂数据库
BJCP风格指南 - 完整的啤酒风格数据库，具备查询功能
公共API层 - 三个核心MCP工具，用于解答基本的酿酒问题

未来的阶段将扩展至包含原料数据库、个人分析、食谱构建器以及高级Brewfather集成等功能。

理解MCP（模型上下文协议）

MCP是一种标准化的方式，使AI助手能够访问外部工具和数据。 不仅局限于他们的训练数据，人工智能模型可以：

调用外部API （如Brewfather、BJCP数据）
访问数据库 （酿酒厂目录、原料数据库）
进行计算 （酿造配方，配方比例调整）
获取实时数据 （当前啤酒供应情况、活动信息）

我们的MCP服务器 暴露；揭露资源 (数据) 和工具（功能）AI助手可以用来提供专家级服务酿造协助。

MCP资源（数据访问）- 第一阶段最小可行性产品（MVP）

bjcp://styles - 完整的BJCP风格指南（基础查询）
breweries://directory - 基本酿酒厂数据库（名称、位置）
beers://catalog - 基本商业啤酒数据库（名称、风格、酿酒厂）

*注：在未来的阶段中，将增加增强的资源和原料数据库。*

MCP工具（功能）- 第一阶段最小可行性产品（MVP）

bjcp_lookup - 通过代码获取详细的BJCP风格信息
search_beers - 按名称、风格、酿酒厂搜索商业啤酒目录
find_breweries - 按位置或名称查找酿酒厂

*注：如下路线图所示，未来阶段将发布更多工具。*

混合数据存储方法

BrewSource MCP 采用混合数据存储策略：

BJCP风格及参考数据 存储为受版本控制的JSON文件在 app/data/。
应用程序数据 （啤酒、酿酒厂、用户等）信息存储在PostgreSQL数据库中。

项目结构

brewsource-mcp/
├── app/                 # Application code
│   ├── cmd/server/      # Main application entry point
│   ├── data/            # BJCP style data (JSON files)
│   ├── internal/        # Internal application code
│   │   ├── handlers/    # HTTP and MCP handlers
│   │   ├── mcp/         # MCP protocol implementation
│   │   ├── models/      # Database models and seed data
│   │   └── services/    # Business logic services
│   └── pkg/data/        # BJCP data utilities
├── docs/                # Project documentation
├── k8s/                 # Kubernetes manifests
├── .github/             # GitHub workflow and templates
├── go.mod               # Go module definition
├── Makefile             # Build and development commands
├── Tiltfile             # Tilt development configuration
└── README.md            # This file

📚 文档

如需全面的项目文档，请参阅 文档/ 目录和Kubernetes部署指南：

数据存储指南 – 数据存储方法、BJCP JSON格式、验证和初始化（或数据填充）
部署指南 – Docker 和基本 Kubernetes 部署指南
Kubernetes 生产环境部署（k8s/README.md） – 分步指南，确保安全且可投入生产的流程

在Oracle Cloud上使用K3s、Traefik和Cert-Manager进行部署

测试指南 – 全面的测试策略和用户故事
项目概述 – 愿景、目标和技术架构

快速入门

“git clone && make up”的体验：

git clone 
cd brewsource-mcp
make up

就是这么简单！这将会：

使用 Kind 创建本地 Kubernetes 集群
启动所有服务（PostgreSQL、Redis、MCP服务器）
使用 Tilt 设置实时重载开发环境
为本地访问转发端口

先决条件

选项1：使用Nix（推荐）

nix-shell  # Everything is included

选项2：手动安装

开发工作流程

# Start everything
make up

# Explore cluster
make k9s

# Stop development (cluster stays)
make down

# Clean up everything
make clean

服务

一旦运行起来，您将拥有：

MCP 服务器：
PostgreSQLlocalhost:5432（用户名：brewsource_user，数据库：brewsource）
Redislocalhost:6379 翻译为中文是：“本地主机：6379”
倾斜仪表盘：

MCP 客户端配置（HTTP 模式）

BrewSource MCP服务器现在支持基于HTTP的MCP通信，适用于本地开发和生产环境。

生产/远程使用

要连接到生产MCP服务器，请在您的配置中使用以下设置： mcp.json：

"brewsource": {
    "type": "http",
    "url": "https://brewsource.charlritter.com/mcp"
}

本地开发用途

要在本地运行和测试MCP服务器，请使用：

"brewsource": {
    "type": "http",
    "url": "http://localhost:8080/mcp"
}

本地开发快速入门

git clone 
cd brewsource-mcp
make up

4. 构建并运行

# Run development environment (Kubernetes + Tilt)
# Access the Tilt dashboard at http://localhost:10350
make up

# Use k9s for interactive cluster management
make k9s

5. 测试服务器

# Health check
curl http://localhost:8080/health

# Current version
curl http://localhost:8080/version

# Server info
curl http://localhost:8080/api

6. 运行测试

# Run all tests
make test

开发指南

添加新工具

定义工具函数 在里面 app/internal/handlers/tools.go：

func (h *ToolHandlers) MyNewTool(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
    // Your tool implementation
    return &mcp.ToolResult{
        Content: []mcp.ToolContent{{
            Type: "text",
            Text: "Tool result",
        }},
    }, nil
}

注册该工具 在 RegisterToolHandlers():

server.RegisterToolHandler("my_new_tool", h.MyNewTool)

添加工具定义 在 getToolDefinition() 方法在于 app/internal/mcp/server.go

添加新资源

创建资源处理器 在 app/internal/handlers/resources.go：

func (h *ResourceHandlers) HandleMyResource(ctx context.Context, uri string) (*mcp.ResourceContent, error) {
    // Your resource implementation
    return &mcp.ResourceContent{
        URI:      uri,
        MimeType: "application/json",
        Text:     "resource data",
    }, nil
}

注册资源 在 RegisterResourceHandlers():

server.RegisterResourceHandler("my://resource/*", h.HandleMyResource)

BJCP风格指南

该 app/pkg/data 该软件包管理啤酒风格数据：

// Load and search styles
styleGuide := bjcp.NewStyleGuide()
styleGuide.LoadFromJSON(bjcpData)

// Get specific style
style, err := styleGuide.GetStyle("21A") // American IPA

// Search styles
results := styleGuide.SearchStyles(bjcp.StyleSearchQuery{
    ABVMin: 5.0,
    ABVMax: 7.0,
    IBUMin: 40,
})

第一阶段实施情况

BrewSource MCP（可译为“BrewSource制造控制计划”或根据具体语境调整为更贴切的表述，如“BrewSource的制造规范与控制计划”） 目前正处于第一阶段的最小可行性产品（MVP）阶段，已实现的功能包括：

核心MCP工具

bjcp_lookup - 通过代码（例如，“21A”）或名称查找BJCP啤酒风格
search_beers - 按名称、风格、酿酒厂或地点搜索商业啤酒
find_breweries - 通过名称、位置、城市、州或国家查找酿酒厂

MCP Resources（公司名，可译为“MCP资源公司”）

bjcp://styles - 完整的BJCP风格指南数据库
bjcp://styles/{code} - 个人风格细节（例如，bjcp://styles/21A）
bjcp://categories - BJCP所有类别的列表
beers://catalog - 商业啤酒数据库
breweries://directory - 啤酒厂目录

基础设施

PostgreSQL 数据库 - 带有适当索引的持久化存储
Redis 缓存 - 可选的缓存层以提升性能
“Seed Data”翻译成中文是“种子数据” - 预填充了BJCP风格、酿酒厂和商业啤酒的信息
全面测试 - 对酿造计算和BJCP（美国啤酒竞赛委员会）工具的单元测试

开发者体验

Makefile - 常见的开发任务（make help （查看所有命令）
环境配置 - 通过 .envrc 和 direnv 管理
API 文档 - 明确的工具和资源架构
代码质量 - 正确的错误处理、日志记录以及遵循Go的最佳实践

深入探索建筑学

MCP协议流程

客户端连接MCP客户端通过HTTP连接
初始化客户端和服务器交换功能
资源/工具发现客户端可以列出可用的资源和工具
请求/响应客户端调用工具或请求资源
JSON-RPC 2.0所有通信均使用JSON-RPC 2.0格式

数据库设计

数据库模式支持：

酿酒厂 附有位置和联系方式
啤酒与具有风格分类的酿酒厂相关联
BJCP风格（或BJCP啤酒风格分类） 带有完整的风格指南
配料具有类型特定属性（JSON字段）
食谱附有成分列表和计算过程

缓存策略

Redis缓存频繁访问的数据（BJCP风格、原料查询）
数据库查询通过适当的索引进行了优化
静态数据（样式指南）在启动时一次性加载

故障排除

常见问题

数据库连接错误

# Check if PostgreSQL is running
pg_isready

# Verify database exists
psql -l | grep brewsource

# Test connection string
psql "your-database-url-here"

端口已被占用

# Check what's using port 8080
lsof -i :8080

# Run on different port
./bin/brewsource-mcp -port=8081

缺失的环境变量

# Check your environment variables (set via .envrc)
echo $DATABASE_URL

构建错误

# Clean and rebuild
make clean
make build

寻求帮助

检查一下 文档/ 详细文档的目录
评论 测试指南 对于用户故事和测试规范
看 部署指南 对于部署要求
使用我们的（工具/平台）打开一个问题 ****

做出贡献

为仓库创建分支（或：克隆仓库）
创建一个特性分支（git checkout -b feature/amazing-feature）
做出你的更改
为新功能添加测试
提交你的更改（git commit -m 'Add amazing feature'）
推送到分支（git push origin feature/amazing-feature)
提交一个拉取请求

扩展或修正数据集

啤酒和酿酒厂的核心数据集被定义为Go源文件：

要扩展啤酒或酿酒厂的数据（添加新条目或修正错误），请编辑相关的Go文件，并提交一个Pull Request 您的更改。对于BJCP风格数据，请更新相应的JSON文件中的内容 app/data/ 并提交一个拉取请求（PR）。请确保您的更改格式整齐，并包含了对更新的清晰描述。

代码标准

遵循Go的约定和最佳实践
使用有意义的变量和函数名称
为复杂的酿造计算添加注释
为新功能编写单元测试
更新新功能的文档

路线图

我们采用敏捷开发方法，通过迭代发布和持续反馈来确保平台不断演进有效满足用户需求。

总体目标： 构建一个全面且不断发展的平台，作为啤酒爱好者的中心资源，酿酒师以及更广泛的啤酒爱好者群体。

指导原则：

以用户为中心的设计 优先考虑为用户提供最大价值的功能
迭代开发： 定期发布功能增量以收集反馈
可扩展性： 设计架构以应对未来增长和新功能的加入
数据准确性： 确保所有与啤酒相关的数据的可靠性和时效性

第一阶段：最小可行性产品（MVP）——核心公共资源

目标： 推出一个基础性公共平台，提供必备的啤酒知识和搜索功能，以验证核心内容概念并吸引首批用户。

MVP定义： 一个提供可搜索的BJCP风格指南和基础商业啤酒目录的MCP服务器。

主要特点：

\[x\] BJCP风格指南整合（基础版）： 按编号或名称查找风格（显示如酒精度（ABV）等基本特性），

国际单位（IBU，颜色）

\[x\] 啤酒与酿酒厂目录（基础版）： 可搜索的商业啤酒数据库（名称、风格）及基本酿酒厂目录

（名称，位置）

\[x\] MCP 工具 - 公共图层（基础版）： bjcp_lookup， search_beers， find_breweries
\[x\] 手动数据输入： 初始风格、啤酒和酿酒厂种类有限
\[x\] HTTP 支持： MCP客户端的HTTP连接模式

结果： 一个功能齐全、公开可访问的MCP啤酒服务器，具备核心BJCP（美国啤酒分类系统）风格查询功能和基本的啤酒/酿酒厂搜索功能能力。

第二阶段：扩大公共资源及提升可用性

目标： 通过提供更详细的信息和增强搜索功能来优化公共资源，为（未来发展）奠定基础为未来功能预留。

主要特点：

\[ \] BJCP风格指南整合（增强版）：

- 风格对比（并排展示2-3种风格） - 详细风格搜索（按颜色、酒精度、啤酒花特性） - 多来源BJCP JSON支持： 从单独的JSON文件中加载并查询啤酒、蜜酒、苹果酒和特殊原料的信息（例如。， bjcp_2021_beer.json， bjcp_2015_mead.json， bjcp_2025_cider.json， bjcp_2015_special_ingredients.json）。

\[ \] 酿造原料数据库（基础版） 麦芽替代图表，啤酒花对比（基本特性），酵母菌株

数据库

\[ \] 啤酒与酿酒厂目录（增强版）： 啤酒厂与酿酒厂的关联，可用性信息（简单的“可用”标志）
\[ \] MCP 工具 - 公共层（扩展版）： bjcp_compare， ingredient_substitute， ingredient_compare， brewery_beers

结果： 一个更全面的公共资源，扩展了BJCP（美国精酿啤酒竞赛）的详细信息，以及初步的原料信息（包括酵母），以及更完善的啤酒/酿酒厂数据互联。

第三阶段：高级/个性化功能 - Brewfather集成与个人分析

目标： 介绍首批高级功能，重点通过与Brewfather的集成，为活跃酿酒师提供直接价值并提供基础的个人分析服务。

主要特点：

\[ \] Brewfather 集成（基础版）： 库存同步（从Brewfather拉取可发酵物、酒花、酵母 - 只读）
\[ \] 个人分析（基础版）： 酿造趋势（酿造批次数量、同步数据中最常用的风格）
\[ \] 用户身份验证与配置文件： 为高级功能提供安全的用户注册和登录，以及基本的用户资料管理

结果： 推出首个高级会员层级，通过Brewfather库存同步为酿酒师提供实质性价值以及初步的个人数据分析。

第四阶段：高级功能 - 互动食谱构建器与社区互动

目标： 推出交互式食谱构建器的初始版本，并通过食谱促进社区互动共享和活动列表。

主要特点：

\[ \] 交互式食谱构建器（基础版） 风格引导创作，基于Brewfather库存的原料建议
\[ \] 社区功能（基础版）： 啤酒厂与啤酒节活动（初期手动输入）
\[ \] MCP 工具 - 新端点： recipe_generate （交互式食谱生成向导）

结果： 一个新兴的互动食谱构建工具，具备库存感知建议功能，并初步具备社区特性。

阶段5：持续改进与扩展（未来）

目标： 迭代优化现有功能，引入更先进的功能，并根据用户反馈进行调整不断拓展平台。

未来发展的重点领域：

高级BJCP特性： 模糊匹配、历史风格数据、地区差异
全面的成分数据库： 按风味/酿造特性进行详细搜索，集成外部数据提供商
增强版啤酒目录： 本地发现，与Untappd集成
高级食谱生成： 水质化学、设备配置、成本优化、深度集成Brewfather（一款啤酒酿造管理软件）
高级分析 库存优化、详细成本分析、季节性建议
社区功能： 克隆食谱数据库，食物搭配建议，季节性酿造推荐

许可证

这个项目采用MIT许可证授权——详见许可证文件中有详细信息。

致谢

BJCP（美国精酿啤酒协会）关于全面的啤酒风格指南
开放啤酒厂数据库用于酿酒厂数据
模型上下文协议对于MCP规范
家庭酿酒爱好者社区，用于获取灵感和知识分享

当前待办事项

添加更多初始数据（风格、啤酒、酿酒厂）
增强MCP资源端点，实现更精细的过滤
添加更全面的错误处理和日志记录
为频繁访问的数据实现缓存

______________________________________________________________________

酿酒愉快！ 🍺 表示啤酒。

Brewsource MCP

快速接入

详细介绍

BrewSource MCP 服务器 🍺

这是什么？

理解MCP（模型上下文协议）

MCP资源（数据访问）- 第一阶段最小可行性产品（MVP）

MCP工具（功能）- 第一阶段最小可行性产品（MVP）

混合数据存储方法

项目结构

📚 文档

快速入门

先决条件

开发工作流程

服务

MCP 客户端配置（HTTP 模式）

生产/远程使用

本地开发用途

本地开发快速入门

4. 构建并运行

5. 测试服务器

6. 运行测试

开发指南

添加新工具

添加新资源

BJCP风格指南

第一阶段实施情况

核心MCP工具

MCP Resources（公司名，可译为“MCP资源公司”）

基础设施

开发者体验

深入探索建筑学

MCP协议流程

数据库设计

缓存策略

故障排除

常见问题

寻求帮助

做出贡献

扩展或修正数据集

代码标准

路线图

第一阶段：最小可行性产品（MVP）——核心公共资源

第二阶段：扩大公共资源及提升可用性

第三阶段：高级/个性化功能 - Brewfather集成与个人分析

第四阶段：高级功能 - 互动食谱构建器与社区互动

阶段5：持续改进与扩展（未来）

许可证

致谢

当前待办事项

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP