🍺 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

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):

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:

⚠️ 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:

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:

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:

4. obter_categorias

Lista todas as categorias de produtos.

Exemplo:

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:

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:

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:

8. obter_perfil_cliente

Perfil completo de um cliente específico.

Parâmetros:

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

Exemplo:

💬 Uso com Claude Desktop

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

Exemplo 1: Dashboard Gerencial

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

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

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

Comandos Disponíveis

Testar com MCP Inspector

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

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:

Ferramenta usada:

Exemplo 2: Clientes Inativos

Pergunta ao Claude:

Ferramenta usada:

Exemplo 3: Análise de Performance

Pergunta ao Claude:

Ferramentas usadas:

🔒 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:

📚 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