Cezzis.com Cocktails MCP Server

Part of the broader Cezzis.com digital experience for discovering and sharing cocktail recipes with a broad community of cocktail enthusiasts and aficionados.

An MCP (Model Context Protocol) server that gives AI agents secure, first‑class access to Cezzis.com cocktail data. It provides high‑level tools for searching cocktails, retrieving detailed recipes and metadata, authenticating users, and submitting ratings. The server runs over HTTP only and exposes a streamable MCP endpoint.

🧩 Cezzis.com Project Ecosystem

This server works alongside several sibling repositories:

• cocktails-mcp (this repo) – Model Context Protocol services that expose cocktail data to AI agents
• cocktails-api – ASP.NET Core backend and REST API consumed by the site and integrations
• cocktails-web – React SPA for the public experience
• cocktails-common – Shared libraries and utilities reused across frontends, APIs, and tooling
• cocktails-images (private) – Source of curated cocktail imagery and CDN assets
• cocktails-shared-infra – Terraform compositions specific to the cocktails platform
• shared-infrastructure – Global Terraform modules that underpin multiple Cezzis.com workloads

☁️ Cloud-Native Footprint (Azure)

Infrastructure is provisioned with Terraform (/terraform) and deployed into Azure using shared modules:

• Azure Container Apps – Hosts the MCP service (HTTP mode) with HTTPS ingress
• Azure API Management – Optional façade when exposing HTTP endpoints; routes and policies managed via Terraform
• Azure Container Registry – Stores container images published from CI/CD
• Azure Key Vault – Holds secrets (Cezzis API subscription keys)
• Azure Monitor – Telemetry collection (logs/traces) via OpenTelemetry and OTLP exporter over HTTP/protobuf
• Shared Infrastructure Modules – Sourced from the reusable Terraform modules repo for consistency

📚 MCP Tools

The server exposes the following MCP tools:

search_cocktails

• Purpose: Search cocktails by natural language query
• Parameters:
  • freeText (string, required): Search terms (name, ingredients, style)
• Returns: Array of cocktails with IDs, titles, images, and summaries

get_cocktail

• Purpose: Retrieve full details for a specific cocktail
• Parameters:
  • cocktailId (string, required): ID from search results
• Returns: Full recipe with ingredients, instructions, images, ratings, and notes

auth_login

• Purpose: Initiate login using Auth0 Device Authorization flow
• Parameters: none
• Returns: Verification URL and user code to complete in your browser

auth_status

• Purpose: Check if you’re authenticated
• Parameters: none
• Returns: Text status

auth_logout

• Purpose: Log out and clear stored tokens
• Parameters: none
• Returns: Text confirmation

cocktail_rate

• Purpose: Rate a cocktail (requires authentication)
• Parameters:
  • cocktailId (string, required)
  • stars (string, required, 1–5)
• Returns: Text confirmation of submitted rating

HTTP Endpoints

• GET /healthz – Health check
• GET /version – Version info
• GET|POST /mcp – Streamable MCP endpoint over HTTP

🛠️ Technology Stack

Core

• Language: Go 1.25+
• Protocol: Model Context Protocol over HTTP (streamable)
• Server: Lightweight MCP server with tool registry and health/version endpoints
• Logging: zerolog (structured JSON logs)

Integrations

• Cezzis.com Cocktails API: Upstream data source (requires subscription key)
• Azure AI Search: Powers semantic/lucene queries in the upstream API
• Azure CosmosDB: Used for secure token storage and account-related data (see internal/repos/cosmos_token_repository.go).
• Auth0: Used for OAuth 2.1 / OIDC authentication and secure token management (see internal/auth/).
• Telemetry: All telemetry (logs, traces, metrics) is sent via OpenTelemetry using OTLP exporters over HTTP/protobuf.

Authentication & Security

• API Access: COCKTAILS_API_XKEY subscription key injected via env/Key Vault
• Auth0 OAuth 2.1 / OIDC: End‑user authentication for personalized features (e.g., ratings). Auth0 is used for device code login, token issuance, and secure refresh flows. See internal/auth/oauth_manager.go and internal/auth/token_storage.go for implementation details.
• CosmosDB: Used for secure storage of user tokens and account data. See internal/repos/cosmos_token_repository.go.
• Secrets: Managed via environment files locally and Azure Key Vault in cloud
• Transport: HTTP/HTTPS for MCP endpoint

🏗️ Project Structure

cocktails.mcp/
├── src/
│   ├── cmd/                    # Application entry point
│   ├── internal/
│   │   ├── api/               # Generated API client code
│   │   ├── config/            # Configuration management
│   │   ├── logging/           # Structured logging helpers
│   │   ├── middleware/        # HTTP middleware (HTTP mode)
│   │   ├── server/            # MCP server and protocol wiring
│   │   ├── testutils/         # Testing utilities
│   │   └── tools/             # MCP tool implementations
│   ├── .env                   # Environment configuration (local)
│   └── go.mod                 # Go module definition
├── dist/                      # Build outputs
└── terraform/                 # Azure resources (ACA, APIM, Key Vault, etc.)

🚀 Development Setup

1. Prerequisites

   • Go 1.25.1 or newer
   • Make (build automation)
   • Optional: Docker (container builds), Azure CLI / Terraform (infrastructure)

2. Install Dependencies

   make tidy
   

3. Environment Setup Create a .env file in ./cocktails.mcp/src/:

# Required: Cezzis.com API Configuration
COCKTAILS_API_HOST=https://api.cezzis.com/prd/cocktails
COCKTAILS_API_XKEY=your_api_subscription_key_here

# Auth0 (required for user-authenticated features)
AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your_public_client_id
AUTH0_AUDIENCE=https://cezzis-cocktails-api
AUTH0_SCOPES="openid offline_access profile email read:owned-account write:owned-account"


# Optional: OpenTelemetry/OTLP (telemetry)
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otlp-endpoint
OTEL_EXPORTER_OTLP_HEADERS=key1=value1,key2=value2

# Optional: Logging
LOG_LEVEL=info
ENV=local

Supported environment files: .env, .env.local, .env.test.

4. Run locally (HTTP)

# Build binary
make compile

# Run HTTP server (choose a port)
./cocktails.mcp/dist/linux/cezzis-cocktails --http :8080

5. Testing

   make test
   

   Generates coverage artifacts (coverage.out, cobertura.xml).

🔐 OAuth and Authentication

This server uses Auth0 for end‑user authentication to enable personalized features (e.g., ratings).

Flow (HTTP): Device Authorization Grant

• The auth_login tool returns a verification URL and user code.
• Visit the URL, enter the code, and complete login.
• The server polls Auth0 and stores tokens securely once available.

Token handling:

• Access and refresh tokens are stored encrypted under ~/.cezzis/.cezzis_tokens.enc.
• Tokens are automatically refreshed using the refresh token when near expiry.
• Logout clears stored tokens.

Required settings:

• AUTH0_DOMAIN – e.g., your-tenant.us.auth0.com
• AUTH0_CLIENT_ID – public SPA/native client ID configured in Auth0
• Optional: AUTH0_AUDIENCE if the API expects a specific audience
• Optional: AUTH0_SCOPES (default: openid profile email offline_access)

Auth tools available to MCP clients:

• auth_login – Initiates device code login and returns instructions.
• auth_status – Returns whether you’re currently authenticated.
• auth_logout – Clears stored tokens.

�💻 MCP Client Setup

Claude Desktop

Configure ~/.config/Claude/claude_desktop_config.json for HTTP MCP:

{
  "mcpServers": {
    "cezzis-cocktails": {
      "url": "http://localhost:3001/mcp",
      "type": "http"
    }
  }
}

Cursor

Configure ~/.cursor/mcp.json or via Settings UI for HTTP MCP:

{
  "mcpServers": {
    "cezzis-cocktails": {
      "url": "http://localhost:3001/mcp",
      "type": "http"
    }
  }
}

GitHub Copilot (HTTP MCP)

Configure VS Code User/mcp.json (Copilot MCP servers):

{
  "servers": {
    "cezzis-mcp": {
      "url": "http://localhost:3001/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

Start the server locally with --http :8080 and Copilot Chat can call its tools over HTTP.

📦 Build & Deployment

• Build: make compile (outputs ./cocktails.mcp/dist/linux/cezzis-cocktails)
• Container: make docker-build (builds image for ACA)
• Infra: Terraform under /terraform for ACA, APIM, Key Vault, etc.
• CI/CD: GitHub Workflows build, test, and publish artifacts/images

🔍 Code Quality

• golangci-lint for static analysis
• gofmt and imports tooling enforced via Make targets
• Unit tests with coverage reports

🔒 Security Features

• API subscription key required for upstream API access
• Secrets sourced from env files locally and Azure Key Vault in cloud
• HTTP/HTTPS transport for MCP endpoint
• Validated tool inputs and structured error handling

📈 Monitoring

• Telemetry (logs, traces, metrics) is collected using OpenTelemetry and exported via the OTLP protocol over HTTP/protobuf. This enables integration with Azure Monitor and other observability platforms that support OTLP over HTTP.
• Health checks exposed in HTTP mode for probes

🤖 What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect with external data sources and tools. Using MCP here allows agents to:

• Ask for cocktails in natural language
• Get contextual recommendations based on ingredients and styles
• Retrieve rich recipe data with measurements and techniques
• Integrate seamlessly across MCP‑compatible tools and IDEs

🌐 Community & Support

• 🤝 Contributing Guide – see CONTRIBUTING.md
• 🤗 Code of Conduct – see CODE_OF_CONDUCT.md
• 🆘 Support Guide – see SUPPORT.md
• 🔒 Security Policy – see SECURITY.md

📄 License

This project is proprietary software. All rights reserved. See LICENSE for details.