🛍️ Commerce MCP Server

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

📖 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

Related MCP server: MCP Shopline

🚀 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

📚 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

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