Cezzis Cocktails

Busca recetas de cócteles usando la API de cezzis.com.

Documentación

Servidor MCP de Cócteles Cezzis.com

Parte de la experiencia digital más amplia de Cezzis.com para descubrir y compartir recetas de cócteles con una amplia comunidad de entusiastas y aficionados a los cócteles.

Este repositorio contiene el servidor MCP basado en Go para los cócteles de Cezzis.com. Expone una interfaz MCP HTTP transmisible que permite a los clientes MCP buscar datos de cócteles, recuperar detalles de cócteles, autenticarse contra Auth0 y enviar calificaciones de usuarios a través de las APIs de la plataforma Cezzis.

Descripción general

El servidor es una capa de integración, no la fuente de los datos de cócteles. Registra herramientas MCP, reenvía solicitudes a las APIs upstream de Cócteles, Búsqueda con IA y Cuentas, almacena tokens de autenticación en PostgreSQL por sesión MCP y emite telemetría a través de OpenTelemetry.

Capacidades principales:

Buscar cócteles por texto libre.
Recuperar detalles completos de cócteles por ID de cóctel.
Iniciar y gestionar la autenticación de flujo de dispositivo Auth0.
Enviar calificaciones de cócteles autenticadas.
Exponer endpoints HTTP de salud y MCP para entornos locales y desplegados.

Entorno de producción

Complete Diagram

Stack tecnológico

Go 1.25.1
Protocolo de Contexto de Modelo sobre HTTP transmisible vía mark3labs/mcp-go
Clientes API generados con OpenAPI para los servicios upstream de Cezzis
Flujo de autorización de dispositivo Auth0
PostgreSQL para almacenamiento de tokens de sesión MCP
OpenTelemetry y zerolog para observabilidad
Manifiestos de Kubernetes para entornos locales desplegados bajo .iac/k8s
Terraform para infraestructura de producción en Azure bajo .iac/terraform

Estructura del repositorio

.
├── .iac/
│   ├── argocd/      # Argo CD manifests for cluster sync
│   ├── k8s/         # Local Kubernetes deployment manifests
│   └── terraform/   # Production Azure infrastructure
├── .vscode/         # IDE launch configuration
├── cocktails.mcp/
│   ├── http-client.env.json
│   └── src/
│       ├── cmd/         # Application entry point
│       └── internal/
│           ├── api/     # Generated API clients
│           ├── auth/    # Auth0 flow and token handling
│           ├── db/      # PostgreSQL connection and setup
│           ├── mcpserver/
│           ├── middleware/
│           ├── repos/
│           ├── telemetry/
│           └── tools/   # MCP tool definitions and handlers
├── Dockerfile
├── makefile
└── mcp.http

Endpoints HTTP

Método	Ruta	Descripción
GET	`/mcp/v1/health/ping`	Verificación básica de salud que devuelve `{"status": "ok"}`
GET	`/mcp/v1/health/readiness`	Sonda de preparación que devuelve `{"status": "ready"}`
GET	`/mcp/v1/health/liveness`	Sonda de actividad que devuelve `{"status": "alive"}`
GET	`/mcp/v1/health/version`	Respuesta de versión de compilación
GET	`/mcp/v1/mcp`	Endpoint de sonda MCP que devuelve `{"status":"ok", "sse":false}`
POST	`/mcp/v1/mcp`	Endpoint MCP HTTP transmisible utilizado por los clientes MCP

Las solicitudes de ejecución de herramientas dependen del encabezado Mcp-Session-Id para que el servidor pueda asociar solicitudes con una sesión MCP.

Herramientas MCP

Herramienta	Descripción
`search_cocktails`	Busca datos de cócteles utilizando la API upstream de Búsqueda con IA
`get_cocktail`	Devuelve datos detallados de cócteles para un ID de cóctel específico
`convert_to_plaintext`	Convierte contenido enriquecido en markdown o HTML a texto plano
`authentication_login_flow`	Inicia el flujo de inicio de sesión de dispositivo Auth0
`auth_status`	Devuelve el estado de autenticación para la sesión MCP actual
`authentication_logout_flow`	Limpia los tokens de la sesión MCP actual
`cocktail_rate`	Envía una calificación de cóctel para un usuario autenticado

Primeros pasos: Configuración del entorno Go

En una máquina nueva (por ejemplo, una instalación nueva de Ubuntu), instale Go desde el tarball oficial upstream en lugar del gestor de paquetes de la distribución, ya que las versiones de Go proporcionadas por apt suelen estar desactualizadas o no coincidir con la versión que este proyecto requiere (Go 1.25.1+). Instale en /usr/local/go, la ubicación estándar recomendada por la documentación oficial de Go, para que go esté disponible para todos los usuarios de la máquina.

# 1. Download the official Go tarball (check https://go.dev/dl/ for the latest version)
cd /tmp
curl -LO https://go.dev/dl/go1.27.1.linux-amd64.tar.gz

# 2. Remove any previous install and extract the new one to /usr/local
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.27.1.linux-amd64.tar.gz

# 3. Make Go available to all users via a system-wide PATH entry
echo 'export PATH="$PATH:/usr/local/go/bin"' | sudo tee /etc/profile.d/go.sh
sudo chmod +x /etc/profile.d/go.sh

# 4. Re-login or source it, then verify
source /etc/profile.d/go.sh
go version

Para actualizar Go en el futuro: repita los pasos 1–2 (sudo rm -rf /usr/local/go y luego extraiga el nuevo tarball). La entrada de PATH no cambia. Los binarios de go install de cada usuario se ubican en su propio $HOME/go/bin, así que agregue export PATH="$PATH:$HOME/go/bin" por usuario para herramientas como golangci-lint.

Herramientas Go requeridas

Los objetivos de makefile (lint, imports, cover, gen-*-api) dependen de estas herramientas:

go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
go install golang.org/x/tools/...@latest
go install github.com/incu6us/goimports-reviser/v3@latest
go install github.com/quantumcycle/go-ignore-cov@latest
go install github.com/t-yuki/gocover-cobertura@latest
cd /usr/local && sudo curl -sSfL https://raw.githubusercontent.com/dotenv-linter/dotenv-linter/master/install.sh | sudo sh -s

También instale make si aún no está presente (sudo apt install build-essential).

Inicio rápido

Requisitos previos

Go 1.25.1+
PostgreSQL
Valores válidos para los hosts de API upstream y las claves de suscripción
Configuración de Auth0 si desea utilizar herramientas autenticadas

1. Configurar el entorno

Cree un archivo .env en cocktails.mcp/src con los valores que su entorno necesite:

PORT=7999
ENV=loc

COCKTAILS_API_HOST=https://your-host/cocktails
COCKTAILS_API_XKEY=replace-me

ACCOUNTS_API_HOST=https://your-host/accounts
ACCOUNTS_API_XKEY=replace-me

AISEARCH_API_HOST=https://your-host/search
AISEARCH_API_XKEY=replace-me

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_NATIVE_CLIENT_ID=replace-me
AUTH0_ACCOUNTS_API_AUDIENCE=https://api.cezzis.com/accounts
AUTH0_SCOPES=openid offline_access profile email read:owned-account write:owned-account

CEZZIS_BASE_URL=https://www.cezzis.com

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=cezzis_cocktails_mcp
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace-me
POSTGRES_USE_TLS=false

2. Compilar y ejecutar

make compile
./cocktails.mcp/dist/linux/cezzis-cocktails

El servidor escucha en el PORT configurado. Por defecto, ese es 7999.

3. Ejecutar desde VS Code

Para depuración basada en IDE, use la configuración de lanzamiento en .vscode/launch.json. Ejecuta la aplicación Go desde cocktails.mcp/src/cmd con la carga de entorno local habilitada.

4. Despliegue local opcional en Kubernetes

Los manifiestos en .iac/k8s son para un entorno local desplegado. Definen el cableado de Deployment, Service, Ingress, ConfigMap y ExternalSecret utilizado al ejecutar la aplicación en un clúster local.

Para sincronizar esa configuración a través de Argo CD:

# loc app
kubectl apply -f https://raw.githubusercontent.com/mtnvencenzo/cezzis-com-cocktails-mcp/refs/heads/main/.iac/argocd/cezzis-com-cocktails-mcp-loc.yaml

# loc image updater
kubectl apply -f https://raw.githubusercontent.com/mtnvencenzo/cezzis-com-cocktails-mcp/refs/heads/main/.iac/argocd/image-updater-loc.yaml

# cloudsync app
kubectl apply -f https://raw.githubusercontent.com/mtnvencenzo/cezzis-com-cocktails-mcp/refs/heads/main/.iac/argocd/cezzis-com-cocktails-mcp-cloudsync.yaml

# cloudsync image updater
kubectl apply -f https://raw.githubusercontent.com/mtnvencenzo/cezzis-com-cocktails-mcp/refs/heads/main/.iac/argocd/image-updater-cloudsync.yaml

Notas de producción

La infraestructura de producción para esta aplicación está definida en .iac/terraform. En producción, la aplicación MCP está alojada en Azure Container Apps, detrás de Azure API Management, y se accede externamente a través de Azure Front Door.