Commerce Server

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

TypeScript Bun MCP PostgreSQL

📖 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 >= 1.0
• PostgreSQL >= 14
• Banco de dados Olist configurado

Instalação

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

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

bun run dev

Modo HTTP (Express server)

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.

---

🔐 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: Documentação detalhada de todas as 37 tools
• EXAMPLES.md: Exemplos práticos de uso e combinações de tools
• 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

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

curl http://localhost:3000/health

2. Chamada MCP (modo HTTP):

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:

{
  "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
• Bun Documentation
• PostgreSQL Documentation
• Zod Documentation
• TypeScript Documentation

---

💡 Suporte

Para questões e suporte:

• 📧 Abra uma issue no repositório
• 📖 Consulte a documentação em /docs
• 💬 Veja exemplos em EXAMPLES.md

---