🍺 Brewteco MCP Server

Servidor MCP (Model Context Protocol) para integração das APIs do Brewteco com assistentes de IA como Claude Desktop.

📋 Índice

• O que é MCP?
• Instalação
• Configuração
• Ferramentas Disponíveis
• Uso com Claude Desktop
• Desenvolvimento
• Exemplos

---

🤔 O que é MCP?

Model Context Protocol (MCP) é um protocolo da Anthropic que permite que assistentes de IA (como Claude) se conectem a fontes de dados externas e executem ações através de "ferramentas".

Este servidor MCP expõe as 5 APIs principais do Brewteco como ferramentas que Claude pode usar:

1. Vendas - Dados de faturamento e transações
2. Produtos - Performance e ranking de produtos
3. Equipe - Performance de vendedores
4. Clientes - Filtros e segmentação de clientes
5. Perfil - Dados detalhados de clientes individuais

---

📦 Instalação

Pré-requisitos

• Node.js >= 18.0.0
• API Brewteco rodando (porta 3700)

Instalar dependências

npm install

Build

npm run build

Isso irá:

• Compilar TypeScript para JavaScript
• Gerar os arquivos em dist/
• Tornar o executável dist/index.js executável

---

⚙️ Configuração

Variáveis de Ambiente

Crie um arquivo .env (opcional):

BREWTECO_API_URL=http://localhost:3700/api/v1

Padrão: http://localhost:3700/api/v1

Configurar no Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione:

{
  "mcpServers": {
    "brewteco": {
      "command": "node",
      "args": ["/caminho/absoluto/para/brewteco-mcp-server/dist/index.js"],
      "env": {
        "BREWTECO_API_URL": "http://localhost:3700/api/v1"
      }
    }
  }
}

⚠️ IMPORTANTE: Use o caminho absoluto para o arquivo dist/index.js

Reiniciar Claude Desktop

Após configurar, reinicie completamente o Claude Desktop.

---

🛠️ Ferramentas Disponíveis

1. obter_vendas

Obtém dados gerais de vendas de uma loja em um período.

Parâmetros:

• data_inicio (obrigatório): Data inicial (YYYY-MM-DD)
• data_fim (obrigatório): Data final (YYYY-MM-DD)
• loja (opcional): Nome da loja

Exemplo:

Quanto vendemos em BOTAFOGO entre 01/12/2024 e 15/12/2024?

2. comparar_vendas_lojas

Compara vendas entre todas as lojas.

Parâmetros:

• data_inicio (obrigatório): Data inicial
• data_fim (obrigatório): Data final

Exemplo:

Compare as vendas de todas as lojas em dezembro

3. obter_produtos

Ranking de produtos mais/menos vendidos com filtros.

Parâmetros:

• periodo (obrigatório): hoje, ontem, semana_atual, mes_atual, custom
• data_inicio: Se periodo=custom
• data_fim: Se periodo=custom
• categoria (opcional): Filtro por categoria
• limite (opcional): Quantidade (1-100)
• ordem (opcional): mais_vendidos, menos_vendidos
• loja (opcional): Filtro por loja

Exemplo:

Quais os 10 produtos mais vendidos de CHOPE em BOTAFOGO esta semana?

4. obter_categorias

Lista todas as categorias de produtos.

Exemplo:

Quais categorias de produtos temos?

5. obter_performance_equipe

Ranking de vendas da equipe com análise de mix.

Parâmetros:

• periodo (obrigatório): hoje, ontem, semana_atual, mes_atual, custom
• data_inicio: Se periodo=custom
• data_fim: Se periodo=custom
• loja (opcional): Filtro por loja

Exemplo:

Quem são os melhores vendedores de GAVEA este mês?

6. obter_detalhe_funcionario

Detalhamento de vendas por categoria de um funcionário.

Parâmetros:

• nome (obrigatório): Nome do funcionário
• data_inicio (obrigatório): Data inicial
• data_fim (obrigatório): Data final

Exemplo:

Mostre as vendas detalhadas do Carlos Silva em dezembro

7. filtrar_clientes

Busca e filtra clientes por comportamento.

Parâmetros (todos opcionais):

• categorias_consumidas: Array de categorias
• produtos_consumidos: Array de produtos
• gasto_total_min: Gasto mínimo
• gasto_total_max: Gasto máximo
• dias_sem_visita_min: Dias sem visitar
• frequencia_min: Frequência mínima
• loja: Filtro por loja
• data_inicio: Período inicial
• data_fim: Período final
• limite: Quantidade de resultados

Exemplos:

Liste os clientes VIP de BOTAFOGO que gastaram mais de R$ 1000

Encontre clientes que não visitam há mais de 45 dias

Quem são os fãs de IPA em LEBLON?

8. obter_perfil_cliente

Perfil completo de um cliente específico.

Parâmetros:

• identificador (obrigatório): CPF, telefone ou email

Exemplo:

Mostre o perfil completo do cliente 11987654321

---

💬 Uso com Claude Desktop

Após configurar, você pode conversar naturalmente com Claude:

Exemplo 1: Dashboard Gerencial

Claude, me dê um resumo executivo de BOTAFOGO em dezembro de 2024:
- Faturamento total
- Top 5 produtos
- Melhor vendedor
- Quantos clientes VIP temos

Claude irá automaticamente:

1. Chamar obter_vendas com as datas corretas
2. Chamar obter_produtos para o top 5
3. Chamar obter_performance_equipe para ranking
4. Chamar filtrar_clientes para VIPs
5. Montar um relatório consolidado

Exemplo 2: Análise de Cliente

Preciso entender melhor o perfil do cliente João Silva (CPF: 12345678901).
Me mostre seu histórico completo e sugira ações de marketing.

Claude irá:

1. Chamar obter_perfil_cliente com o CPF
2. Analisar LTV, produtos favoritos, frequência
3. Sugerir ações personalizadas

Exemplo 3: Campanha de Marketing

Encontre clientes de GAVEA que:
- Gostam de IPA
- Visitam frequentemente (5+ vezes)
- Gastam entre R$ 500 e R$ 2000
- Estão ativos (visitaram nos últimos 30 dias)

Depois me sugira uma campanha para eles.

Claude irá:

1. Chamar filtrar_clientes com os critérios
2. Analisar o perfil dos clientes retornados
3. Sugerir campanha personalizada

---

🔧 Desenvolvimento

Estrutura do Projeto

brewteco-mcp-server/
├── src/
│   ├── index.ts          # Servidor MCP principal
│   ├── api-client.ts     # Cliente HTTP para API
│   ├── tools.ts          # Definição das ferramentas MCP
│   └── types.ts          # Types e schemas Zod
├── dist/                 # Código compilado
├── package.json
├── tsconfig.json
└── README.md

Comandos Disponíveis

# Desenvolvimento com hot-reload
npm run dev

# Build de produção
npm run build

# Iniciar servidor (após build)
npm start

# Testar com MCP Inspector
npm run inspector

Testar com MCP Inspector

O MCP Inspector é uma ferramenta da Anthropic para testar servidores MCP:

npm run inspector

Isso abre uma interface web onde você pode:

• Ver todas as ferramentas disponíveis
• Testar chamadas com diferentes parâmetros
• Ver respostas em tempo real
• Debug de problemas

---

🎯 Exemplos Práticos

Exemplo 1: Vendas do Dia

Pergunta ao Claude:

Quanto vendemos hoje em BOTAFOGO?

Ferramenta usada:

{
  "name": "obter_vendas",
  "arguments": {
    "data_inicio": "2024-12-18",
    "data_fim": "2024-12-18",
    "loja": "BOTAFOGO"
  }
}

Exemplo 2: Clientes Inativos

Pergunta ao Claude:

Liste clientes de LEBLON que não visitam há mais de 60 dias mas já gastaram mais de R$ 500

Ferramenta usada:

{
  "name": "filtrar_clientes",
  "arguments": {
    "dias_sem_visita_min": 60,
    "gasto_total_min": 500,
    "loja": "LEBLON",
    "limite": 50
  }
}

Exemplo 3: Análise de Performance

Pergunta ao Claude:

Compare a performance de vendas de todas as lojas em novembro e identifique a melhor

Ferramentas usadas:

{
  "name": "comparar_vendas_lojas",
  "arguments": {
    "data_inicio": "2024-11-01",
    "data_fim": "2024-11-30"
  }
}

---

🔒 Segurança

Boas Práticas

1. Validação de Dados: Todos os parâmetros são validados com Zod
2. Tratamento de Erros: Erros da API são capturados e formatados
3. Timeout: Requisições têm timeout de 30 segundos
4. Retry Logic: Falhas temporárias são retentadas 3 vezes
5. Logs: Todas as operações são logadas em stderr

Dados Sensíveis

• O servidor MCP não armazena dados
• Todas as requisições são stateless
• Logs não contêm informações sensíveis de clientes

---

🐛 Troubleshooting

Problema: Claude não vê as ferramentas

Solução:

1. Verifique se o caminho em claude_desktop_config.json está correto
2. Certifique-se de usar caminho absoluto
3. Reinicie completamente o Claude Desktop
4. Verifique os logs em: ~/Library/Logs/Claude/ (MacOS)

Problema: Erro "Connection refused"

Solução:

1. Verifique se a API Brewteco está rodando: curl http://localhost:3700/api/v1/health
2. Confirme a BREWTECO_API_URL na configuração
3. Teste a conexão manualmente

Problema: Ferramentas retornam erro

Solução:

1. Use o MCP Inspector para testar: npm run inspector
2. Verifique os logs do servidor MCP
3. Confirme que os parâmetros estão corretos

Problema: Build falha

Solução:

# Limpar e reinstalar
rm -rf node_modules dist
npm install
npm run build

---

📚 Recursos

• MCP Documentation
• MCP TypeScript SDK
• Claude Desktop

---

📄 Licença

Propriedade da Brewteco.

---

Versão: 1.0.0
Última Atualização: Dezembro 2024

echo "# brew_mcp" >> README.md git init git add README.md git commit -m "first commit" git branch -M main git remote add origin git@github.com:apiccelli/brew_mcp.git git push -u origin main