Server Status Running
Version: v1.1.2
HTTP: https://brewsource.charlritter.com/mcp (Live MCP connection for LLM integration)
API: https://brewsource.charlritter.com/api (REST endpoint for server info and data)
Relevant Links: GitHub  |  BJCP
Modern REST API Real-time and RESTful endpoints for seamless integration with your brewing tools and LLMs.
Open Source & Extensible MIT-licensed, community-driven, and easy to extend for new beverage types and data models.
LLM-Ready Designed for AI/LLM integration, enabling smart queries and context-aware brewing assistance.

BrewSource MCP Server 🍺

A comprehensive Model Context Protocol (MCP) server for brewing resources, built with Go.

What is This?

BrewSource MCP is a specialized MCP server that gives AI assistants access to essential brewing knowledge and tools. Currently in Phase 1 MVP, it focuses on core public resources:

Future phases will expand with ingredient databases, personal analytics, recipe builders, and premium Brewfather integration.

Understanding MCP (Model Context Protocol)

MCP is a standardized way for AI assistants to access external tools and data. Instead of being limited to their training data, AI models can:

Our MCP server exposes resources (data) and tools (functions) that AI assistants can use to provide expert brewing assistance.

MCP Resources (Data Access) - Phase 1 MVP

Note: Enhanced resources and ingredient databases will be added in future phases.

MCP Tools (Functions) - Phase 1 MVP

Note: Additional tools will be released in future phases as outlined in the roadmap below.

Hybrid Data Storage Approach

BrewSource MCP uses a hybrid data storage strategy:

Project Structure

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

📚 Documentation

For comprehensive project documentation, see the docs/ directory and the Kubernetes deployment guide:

Quick Start

The “git clone && make up” experience:

git clone <repository-url>
cd brewsource-mcp
make up

That’s it! This will:

Prerequisites

Option 1: Using Nix (Recommended)

nix-shell  # Everything is included

Option 2: Manual Installation

Development Workflow

# Start everything
make up

# Explore cluster
make k9s

# Stop development (cluster stays)
make down

# Clean up everything
make clean

Services

Once running, you’ll have:

MCP Client Configuration (HTTP Mode)

The BrewSource MCP server now supports HTTP-based MCP communication for both local development and production.

Production/Remote Usage

To connect to the production MCP server, use the following configuration in your mcp.json:

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

Local Development Usage

To run and test the MCP server locally, use:

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

Quick Start for Local Development

git clone <repository-url>
cd brewsource-mcp
make up

4. Build and Run

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

# Use k9s for interactive cluster management
make k9s

5. Test the Server

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

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

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

6. Run Tests

# Run all tests
make test

Development Guide

Adding New Tools

  1. Define the tool function in 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
}
  1. Register the tool in RegisterToolHandlers():
server.RegisterToolHandler("my_new_tool", h.MyNewTool)
  1. Add tool definition in getToolDefinition() method in app/internal/mcp/server.go

Adding New Resources

  1. Create resource handler in 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
}
  1. Register the resource in RegisterResourceHandlers():
server.RegisterResourceHandler("my://resource/*", h.HandleMyResource)

BJCP Style Guide

The app/pkg/data package manages beer style 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,
})

Phase 1 Implementation Status

BrewSource MCP is currently in Phase 1 MVP with the following implemented features:

Core MCP Tools

MCP Resources

Infrastructure

Developer Experience

Architecture Deep Dive

MCP Protocol Flow

  1. Client Connection: MCP client connects via HTTP
  2. Initialization: Client and server exchange capabilities
  3. Resource/Tool Discovery: Client can list available resources and tools
  4. Request/Response: Client calls tools or requests resources
  5. JSON-RPC 2.0: All communication uses JSON-RPC 2.0 format

Database Design

The database schema supports:

Caching Strategy

Troubleshooting

Common Issues

Database Connection Errors

# Check if PostgreSQL is running
pg_isready

# Verify database exists
psql -l | grep brewsource

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

Port Already in Use

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

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

Missing Environment Variables

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

Build Errors

# Clean and rebuild
make clean
make build

Getting Help

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for new functionality
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Expanding or Correcting Datasets

The core datasets for beers and breweries are defined as Go source files:

To expand the beer or brewery data (add new entries or fix errors), edit the relevant Go file and open a Pull Request with your changes. For BJCP style data, update the appropriate JSON file in app/data/ and submit a PR. Please ensure your changes are well-formatted and include a clear description of the update.

Code Standards

Roadmap

We follow an Agile development methodology with iterative releases and continuous feedback to ensure the platform evolves effectively to meet user needs.

Overall Goal: To build a comprehensive and evolving platform that serves as a central resource for beer enthusiasts, brewers, and the wider beer community.

Guiding Principles:

Phase 1: Minimum Viable Product (MVP) - Core Public Resources

Goal: Launch a foundational public platform with essential beer knowledge and search capabilities to validate core concepts and attract initial users.

MVP Definition: An MCP server providing searchable BJCP style guidelines and a basic commercial beer catalogue.

Key Features:

Outcome: A functional, publicly accessible MCP Beer Server with core BJCP style lookup and basic beer/brewery search capabilities.

Phase 2: Expanding Public Resources & Usability

Goal: Enhance the public resources with more detailed information and improved search capabilities, laying the groundwork for future features.

Key Features:

Outcome: A more robust public resource with expanded BJCP details, initial ingredient information (including yeast), and better interconnected beer/brewery data.

Phase 3: Premium/Personal Features - Brewfather Integration & Personal Analytics

Goal: Introduce the first premium features, focusing on direct value for active brewers by integrating with Brewfather and offering basic personal analytics.

Key Features:

Outcome: Launch of the first premium tier, offering tangible value to brewers through Brewfather inventory synchronisation and initial personal analytics.

Phase 4: Advanced Features - Interactive Recipe Builder & Community Engagement

Goal: Introduce an initial version of the interactive recipe builder and foster community engagement through recipe sharing and event listings.

Key Features:

Outcome: A nascent interactive recipe builder with inventory-aware suggestions and the beginning of community features.

Phase 5: Continuous Improvement & Expansion (Future)

Goal: Iteratively enhance existing features, introduce more advanced functionalities, and respond to user feedback to continually grow the platform.

Key Areas for Future Development:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Current ToDos

Happy Brewing! 🍺