Cezzis Cocktails

Pesquise receitas de coquetéis usando a API do cezzis.com.

Documentação

Servidor MCP de Coquetéis Cezzis.com

Parte da experiência digital mais ampla do Cezzis.com para descobrir e compartilhar receitas de coquetéis com uma ampla comunidade de entusiastas e apreciadores de coquetéis.

Este repositório contém o servidor MCP baseado em Go para os coquetéis do Cezzis.com. Ele expõe uma interface MCP HTTP transmissível que permite que clientes MCP pesquisem dados de coquetéis, recuperem detalhes de coquetéis, autentiquem-se contra o Auth0 e enviem avaliações de usuários por meio das APIs da plataforma Cezzis.

Visão Geral

O servidor é uma camada de integração, não a fonte dos dados de coquetéis. Ele registra ferramentas MCP, encaminha solicitações para as APIs upstream de Coquetéis, Pesquisa por IA e Contas, armazena tokens de autenticação no PostgreSQL por sessão MCP e emite telemetria por meio do OpenTelemetry.

Principais capacidades:

Pesquisar coquetéis por texto livre.
Recuperar detalhes completos de coquetéis por ID do coquetel.
Iniciar e gerenciar autenticação de fluxo de dispositivo Auth0.
Enviar avaliações autenticadas de coquetéis.
Expor endpoints HTTP de saúde e MCP para ambientes locais e implantados.

Ambiente de Produção

Complete Diagram

Pilha Tecnológica

Go 1.25.1
Protocolo de Contexto de Modelo sobre HTTP transmissível via mark3labs/mcp-go
Clientes de API gerados por OpenAPI para serviços upstream do Cezzis
Fluxo de autorização de dispositivo Auth0
PostgreSQL para armazenamento de tokens de sessão MCP
OpenTelemetry e zerolog para observabilidade
Manifestos Kubernetes para ambientes locais implantados em .iac/k8s
Terraform para infraestrutura de produção no Azure em .iac/terraform

Estrutura do Repositório

.
├── .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	Caminho	Descrição
GET	`/mcp/v1/health/ping`	Verificação básica de saúde retornando `{"status": "ok"}`
GET	`/mcp/v1/health/readiness`	Sonda de prontidão retornando `{"status": "ready"}`
GET	`/mcp/v1/health/liveness`	Sonda de vivacidade retornando `{"status": "alive"}`
GET	`/mcp/v1/health/version`	Resposta de versão de build
GET	`/mcp/v1/mcp`	Endpoint de sonda MCP retornando `{"status":"ok", "sse":false}`
POST	`/mcp/v1/mcp`	Endpoint MCP HTTP transmissível usado por clientes MCP

As solicitações de execução de ferramentas dependem do cabeçalho Mcp-Session-Id para que o servidor possa associar solicitações a uma sessão MCP.

Ferramentas MCP

Ferramenta	Descrição
`search_cocktails`	Pesquisa dados de coquetéis usando a API upstream de Pesquisa por IA
`get_cocktail`	Retorna dados detalhados de coquetéis para um ID de coquetel específico
`convert_to_plaintext`	Converte conteúdo rico em markdown ou HTML em texto simples
`authentication_login_flow`	Inicia o fluxo de login de dispositivo Auth0
`auth_status`	Retorna o estado de autenticação para a sessão MCP atual
`authentication_logout_flow`	Limpa tokens para a sessão MCP atual
`cocktail_rate`	Envia uma avaliação de coquetel para um usuário autenticado

Começando: Configuração do Ambiente Go

Em uma máquina nova (por exemplo, uma nova instalação do Ubuntu), instale o Go a partir do tarball oficial upstream em vez do gerenciador de pacotes da distribuição, pois as versões do Go fornecidas pelo apt geralmente estão desatualizadas ou incompatíveis com a versão alvo deste projeto (Go 1.25.1+). Instale em /usr/local/go, o local padrão recomendado pela documentação oficial do Go, para que go esteja disponível para todos os usuários da 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 atualizar o Go no futuro: repita os passos 1–2 (sudo rm -rf /usr/local/go e depois extraia o novo tarball). A entrada no PATH não muda. Os binários go install de cada usuário ficam em seu próprio $HOME/go/bin, então adicione export PATH="$PATH:$HOME/go/bin" por usuário para ferramentas como golangci-lint.

Ferramentas Go necessárias

Os alvos makefile (lint, imports, cover, gen-*-api) dependem destas ferramentas:

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

Instale também make se ainda não estiver presente (sudo apt install build-essential).

Início Rápido

Pré-requisitos

Go 1.25.1+
PostgreSQL
Valores válidos para os hosts de API upstream e chaves de assinatura
Configurações do Auth0 se você quiser usar ferramentas autenticadas

1. Configurar o ambiente

Crie um arquivo .env em cocktails.mcp/src com os valores que seu ambiente precisa:

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 e executar

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

O servidor escuta no PORT configurado. Por padrão, isso é 7999.

3. Executar a partir do VS Code

Para depuração baseada em IDE, use a configuração de inicialização em .vscode/launch.json. Ela executa o aplicativo Go a partir de cocktails.mcp/src/cmd com carregamento de ambiente local habilitado.

4. Implantação opcional em Kubernetes local

Os manifestos em .iac/k8s são para um ambiente local implantado. Eles definem a conexão de Deployment, Service, Ingress, ConfigMap e ExternalSecret usada ao executar o aplicativo em um cluster local.

Para sincronizar essa configuração por meio do 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 Produção

A infraestrutura de produção para este aplicativo é definida em .iac/terraform. Em produção, o aplicativo MCP é hospedado no Azure Container Apps, fica atrás do Azure API Management e é acessado externamente por meio do Azure Front Door.