# 🛍️ Commerce MCP Server

> Servidor MCP (Model Context Protocol) para análise avançada de dados de e-commerce com inteligência artificial

[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
[![Bun](https://img.shields.io/badge/Bun-1.0-orange.svg)](https://bun.sh/)
[![MCP](https://img.shields.io/badge/MCP-1.20-green.svg)](https://modelcontextprotocol.io/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-blue.svg)](https://www.postgresql.org/)

## 📖 Visão Geral

**Commerce MCP Server** é um servidor MCP completo e robusto que oferece **37 ferramentas especializadas** para análise profunda de dados de e-commerce. Projetado para integração com agentes de IA (como Claude, GPT-4, etc.), fornece insights acionáveis através de consultas otimizadas ao banco de dados Olist.

### 🎯 Principais Características

- **37 Tools MCP** organizadas em 10 categorias funcionais
- **50+ Métricas** de negócio disponíveis
- **Análises Avançadas** incluindo NPS, cross-selling, detecção de anomalias e cohorts
- **Queries Otimizadas** em SQL para performance máxima
- **Validação Rigorosa** com Zod schemas
- **Dois Modos de Operação**: stdio (direto) e HTTP (servidor Express)
- **Type-Safe** com TypeScript em modo strict

---

## 🚀 Quick Start

### Pré-requisitos

- [Bun](https://bun.sh/) >= 1.0
- [PostgreSQL](https://www.postgresql.org/) >= 14
- Banco de dados Olist configurado

### Instalação

```bash
# Clone o repositório
git clone <repository-url>
cd commerce-mcp

# Instale as dependências
bun install

# Configure as variáveis de ambiente
cp .env.example .env
# Edite o arquivo .env com suas configurações
```

### Configuração

Crie um arquivo `.env` na raiz do projeto:

```env
# Database Configuration
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=commerce_intelligence
DATABASE_USER=postgres
DATABASE_PASSWORD=sua_senha

# Server Configuration (para modo HTTP)
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=0.0.0.0

# Connection Pool Configuration
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=10
DATABASE_IDLE_TIMEOUT_MS=10000
DATABASE_CONNECTION_TIMEOUT_MS=5000

# Logging
LOG_LEVEL=info
```

### Execução

#### Modo STDIO (MCP direto)
```bash
bun run dev
```

#### Modo HTTP (Express server)
```bash
bun run dev:server
```

O servidor HTTP estará disponível em `http://localhost:3000/mcp`

---

## 📊 Categorias de Ferramentas

### 1. 📈 KPI Tools (3 tools)
Métricas principais do negócio para dashboards executivos

- `dashboard-kpis` - KPIs gerais (pedidos, clientes, receita, ticket médio)
- `monthly-revenue` - Análise de receita mensal com breakdown
- `order-status-distribution` - Distribuição de status de pedidos

### 2. 👥 Customer Tools (4 tools)
Análise profunda de comportamento e segmentação de clientes

- `customer-geographic-distribution` - Distribuição geográfica por estado
- `top-cities` - Top cidades por volume e receita
- `customer-segmentation` - Segmentação por perfil de compra
- `top-customers-by-value` - Clientes de maior valor

### 3. 📦 Product Tools (4 tools)
Performance de produtos e otimização de portfólio

- `top-products` - Produtos mais vendidos e rentáveis
- `category-performance` - Performance por categoria
- `products-by-review-score` - Produtos por avaliação
- `product-dimension-analysis` - Análise de dimensões e peso

### 4. 🚚 Delivery Tools (3 tools)
Logística e eficiência de entregas

- `delivery-performance-by-state` - Performance por estado
- `freight-analysis-by-distance` - Análise de frete por distância
- `most-common-routes` - Rotas mais utilizadas

### 5. 🏪 Seller Tools (3 tools)
Análise e ranking de vendedores

- `seller-performance` - Performance geral de vendedores
- `sellers-by-state` - Agrupamento por estado
- `seller-delivery-performance` - Eficiência de entrega

### 6. 💳 Payment Tools (3 tools)
Métodos de pagamento e comportamento financeiro

- `payment-methods-analysis` - Análise por método de pagamento
- `installment-analysis` - Análise de parcelamento
- `multiple-payment-orders` - Pedidos com múltiplos pagamentos

### 7. ⭐ Review Tools (4 tools)
Análise de satisfação e qualidade

- `review-score-distribution` - Distribuição de notas
- `negative-review-factors` - Fatores de insatisfação
- `delivery-impact-on-reviews` - Impacto da entrega nas avaliações
- `categories-by-review-problems` - Categorias problemáticas

### 8. 📅 Temporal Tools (3 tools)
Padrões temporais e sazonalidade

- `sales-by-day-of-week` - Vendas por dia da semana
- `sales-by-hour` - Vendas por hora do dia
- `month-over-month-growth` - Crescimento mês a mês

### 9. 🔄 Cohort Tools (1 tool)
Análise de retenção de clientes

- `customer-cohorts` - Cohorts mensais de retenção

### 10. 🧠 Advanced Tools (4 tools)
Análises avançadas e machine learning

- `cross-selling-categories` - Categorias compradas juntas
- `price-elasticity-by-category` - Elasticidade de preço
- `potential-fraud-anomalies` - Detecção de anomalias
- `nps-analysis` - Cálculo de Net Promoter Score

---

## 🏗️ Arquitetura

```
commerce-mcp/
├── src/
│   ├── index.ts                    # Entry point (modo STDIO)
│   ├── server.ts                   # Entry point (modo HTTP)
│   ├── tools/                      # MCP Tools
│   │   ├── index.ts                # Registro de todas as tools
│   │   ├── kpi-tool.ts
│   │   ├── customer-tool.ts
│   │   ├── product-tool.ts
│   │   ├── delivery-tool.ts
│   │   ├── seller-tool.ts
│   │   ├── payment-tool.ts
│   │   ├── review-tool.ts
│   │   ├── temporal-tool.ts
│   │   ├── cohort-tool.ts
│   │   └── advanced-tool.ts
│   ├── services/
│   │   ├── database.ts             # Database Manager (Singleton)
│   │   ├── database/               # Queries SQL organizadas
│   │   │   ├── kpi.ts
│   │   │   ├── customer.ts
│   │   │   ├── product.ts
│   │   │   ├── delivery.ts
│   │   │   ├── seller.ts
│   │   │   ├── payment-review.ts
│   │   │   └── advanced.ts
│   │   └── mcp/
│   │       └── create-mcp-server.ts
│   ├── types/                      # TypeScript types
│   │   ├── database-config.type.ts
│   │   └── database-types.ts
│   └── lib/
│       └── utils/
│           └── utils.ts
├── docs/
│   ├── README_TOOLS.md             # Documentação detalhada das tools
│   └── TOOLS.md                    # Referência rápida
├── EXAMPLES.md                     # Exemplos de uso
├── package.json
├── tsconfig.json
└── .env.example
```

### 🎨 Design Patterns

- **Singleton Pattern**: Database Manager único para pool de conexões eficiente
- **Factory Pattern**: Criação do servidor MCP encapsulada
- **Strategy Pattern**: Diferentes transportes (stdio, HTTP)
- **Repository Pattern**: Separação de queries SQL em módulos específicos

---

## 💻 Tecnologias

| Tecnologia | Versão | Uso |
|------------|--------|-----|
| **Bun** | 1.0+ | Runtime JavaScript de alta performance |
| **TypeScript** | 5.0+ | Tipagem estática e type safety |
| **MCP SDK** | 1.20.0 | Model Context Protocol |
| **PostgreSQL** | 14+ | Banco de dados relacional |
| **pg** | 8.17.2 | Client PostgreSQL |
| **Zod** | 3.25.30 | Validação de schemas e runtime type checking |
| **Express** | 5.2.1 | Servidor HTTP (modo server) |
| **Axios** | 1.12.2 | Cliente HTTP |

---

## 📚 Uso com Agentes IA

Este servidor foi especificamente otimizado para uso com agentes inteligentes como Claude, oferecendo:

### ✅ Benefícios para Agentes IA

1. **Descrições Semânticas**: Cada tool possui título e descrição clara do seu propósito
2. **Parâmetros Documentados**: Schemas Zod com descrições detalhadas de cada campo
3. **Retornos Estruturados**: JSON formatado, consistente e fácil de interpretar
4. **Flexibilidade**: Filtros opcionais para diferentes níveis de granularidade
5. **Performance**: Queries otimizadas para respostas rápidas
6. **Error Handling**: Tratamento robusto de erros com mensagens claras

### 🤖 Exemplos de Prompts

#### Análise Exploratória
```
"Faça uma análise exploratória completa do e-commerce. 
Comece pelos KPIs principais e depois explore:
1. Performance de produtos e categorias
2. Distribuição geográfica de clientes  
3. Padrões temporais de vendas
4. Satisfação dos clientes via reviews e NPS"
```

#### Investigação de Problemas
```
"Identifique os principais problemas do negócio analisando:
1. Categorias com mais reviews negativos
2. Estados com piores métricas de entrega
3. Potenciais anomalias e fraudes
4. Vendedores com baixa performance
Sugira ações corretivas baseadas nos dados."
```

#### Oportunidades de Crescimento
```
"Identifique oportunidades de crescimento através de:
1. Cross-selling entre categorias
2. Clientes de alto valor que compram pouco
3. Estados/cidades com baixa penetração mas alto potencial
4. Produtos bem avaliados com baixo volume"
```

Para mais exemplos, consulte o arquivo [`EXAMPLES.md`](./EXAMPLES.md).

---

## 🔐 Segurança

- ✅ **Prepared Statements**: Proteção contra SQL injection
- ✅ **Validação de Entrada**: Zod schemas em todas as tools
- ✅ **Connection Pool**: Gerenciamento seguro de conexões
- ✅ **Error Handling**: Tratamento apropriado sem exposição de dados sensíveis
- ✅ **Environment Variables**: Credenciais em variáveis de ambiente
- ✅ **Type Safety**: TypeScript strict mode

---

## 📖 Documentação Adicional

- **[TOOLS.md](./docs/TOOLS.md)**: Documentação detalhada de todas as 37 tools
- **[EXAMPLES.md](./EXAMPLES.md)**: Exemplos práticos de uso e combinações de tools
- **[README_TOOLS.md](./docs/README_TOOLS.md)**: Guia técnico das ferramentas

---

## 🎯 Casos de Uso

### 1. Dashboard Executivo
Combine `dashboard-kpis`, `monthly-revenue` e `order-status-distribution` para visão geral do negócio.

### 2. Análise de Performance
Use `seller-performance`, `top-products` e `category-performance` para identificar top performers.

### 3. Otimização Logística
Analise `delivery-performance-by-state`, `most-common-routes` e `freight-analysis-by-distance`.

### 4. Customer Intelligence
Explore `customer-segmentation`, `customer-cohorts` e `top-customers-by-value`.

### 5. Gestão de Qualidade
Monitore `review-score-distribution`, `nps-analysis` e `negative-review-factors`.

---

## 🛠️ Desenvolvimento

### Padrões de Código

- **TypeScript strict mode** habilitado
- **Código auto-explicativo** sem comentários desnecessários
- **Separação de responsabilidades** clara
- **Queries SQL** otimizadas e legíveis
- **Error handling** consistente

### Estrutura de uma Tool

```typescript
server.registerTool(
  "tool-name",
  {
    title: "Título Descritivo",
    description: "Descrição clara do que a tool faz",
    inputSchema: {
      param1: z.string().optional().describe("Descrição do parâmetro"),
      param2: z.number().min(1).describe("Outro parâmetro"),
    },
  },
  async (args) => {
    const result = await db.executeQuery("query_name", args);
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);
```

### Adicionando Novas Tools

1. Crie a query SQL em `src/services/database/[categoria].ts`
2. Adicione a tool em `src/tools/[categoria]-tool.ts`
3. Registre no `src/tools/index.ts`
4. Documente em `docs/TOOLS.md`

---

## 🧪 Testing

O servidor pode ser testado através de:

1. **Health Check** (modo HTTP):
```bash
curl http://localhost:3000/health
```

2. **Chamada MCP** (modo HTTP):
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

3. **Integração com Claude Desktop**:
Configure no arquivo `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "commerce": {
      "command": "bun",
      "args": ["run", "/path/to/commerce-mcp/src/index.ts"]
    }
  }
}
```

---

## 📊 Performance

- **Connection Pool**: 2-10 conexões simultâneas
- **Query Optimization**: Índices apropriados e agregações eficientes
- **Timeout**: 5 segundos para conexão, 10 segundos para idle
- **Response Time**: < 500ms para maioria das queries

---

## 🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add: amazing feature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request

### Convenções

- Siga os padrões TypeScript do projeto
- Adicione documentação para novas tools
- Mantenha queries SQL legíveis e otimizadas
- Teste suas mudanças

---

## 📝 Changelog

### [1.0.0] - 2024
- ✨ Versão inicial
- 📊 37 tools MCP em 10 categorias
- 🚀 Suporte para stdio e HTTP
- 🔒 Validação com Zod
- 📚 Documentação completa

---

## 📄 Licença

Este projeto é privado e proprietário.

---

## 👨‍💻 Autor

Desenvolvido com ❤️ para análise profissional de dados de e-commerce com foco em integração com agentes de IA.

---

## 🔗 Links Úteis

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Bun Documentation](https://bun.sh/docs)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [Zod Documentation](https://zod.dev/)
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)

---

## 💡 Suporte

Para questões e suporte:
- 📧 Abra uma issue no repositório
- 📖 Consulte a documentação em `/docs`
- 💬 Veja exemplos em `EXAMPLES.md`

---

<div align="center">

**Commerce MCP Server** - Transforme dados em insights acionáveis com IA

</div>