StockSpark MCP Server

Um servidor MCP para gerenciamento de concessionárias de veículos com inteligência artificial.

GitHub

Documentação

Servidor MCP StockSpark

Um servidor Model Context Protocol (MCP) pronto para produção que fornece aos agentes de IA 36 ferramentas especializadas para gerenciamento completo de concessionárias de veículos através da plataforma de API StockSpark/Carspark.

🚀 Início Rápido

1. Instalação

git clone https://github.com/loukach/stockspark-mcp-poc.git
cd stockspark-mcp-poc
npm install

2. Configuração

Crie o arquivo .env com suas credenciais:

# Required - Your StockSpark credentials
STOCKSPARK_USERNAME=your-email@dealership.com
STOCKSPARK_PASSWORD=your-password

# Optional - Override defaults if needed
# STOCKSPARK_COUNTRY=it  # Default: it
# LOG_LEVEL=debug  # Default: info

3. Teste de Conexão

npm test

4. Conecte ao Claude Desktop

Adicione à configuração do seu Claude Desktop:

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

{
  "mcpServers": {
    "stockspark": {
      "command": "node",
      "args": ["/absolute/path/to/stockspark-mcp-poc/src/index.js"],
      "env": {
        "STOCKSPARK_USERNAME": "your-email@dealership.com",
        "STOCKSPARK_PASSWORD": "your-password"
      }
    }
  }
}

📋 Ferramentas Disponíveis (36 no total)

🏢 Gerenciamento de Organização (5 ferramentas)

  • get_user_context - Visualizar seleção atual de empresa/concessionária
  • list_user_companies - Listar empresas acessíveis
  • select_company - Escolher empresa de trabalho
  • list_company_dealers - Listar concessionárias da empresa
  • select_dealer - Escolher concessionária de trabalho

🔍 Dados de Referência de Veículos (10 ferramentas)

  • search_vehicle_versions - Busca progressiva por especificações de veículos
  • compare_vehicle_versions - Comparar versões/acabamentos semelhantes
  • get_vehicle_version_template - Obter modelo completo de dados do veículo
  • get_vehicle_makes - Listar fabricantes disponíveis
  • get_vehicle_models - Obter modelos de uma marca
  • get_vehicle_trims - Obter níveis de acabamento com especificações
  • get_vehicle_transmissions - Tipos de transmissão disponíveis
  • get_vehicle_bodies - Opções de estilo de carroceria
  • get_vehicle_fuels - Opções de tipo de combustível
  • get_vehicle_colors - Cores disponíveis

🚗 Gerenciamento de Veículos (6 ferramentas)

  • add_vehicle - Criar novo veículo (modelo ou manual)
  • get_vehicle - Recuperar detalhes do veículo
  • list_vehicles - Buscar/filtrar inventário com ordenação
  • update_vehicle - Modificar dados do veículo
  • update_vehicle_price - Atualizações rápidas de preço
  • delete_vehicle - Remover veículo (com confirmação)

📸 Gerenciamento de Imagens (4 ferramentas)

  • upload_vehicle_images - Upload em lote a partir de arquivos/URLs
  • get_vehicle_images - Listar imagens do veículo
  • set_vehicle_main_image - Definir imagem principal de exibição
  • delete_vehicle_image - Remover imagens específicas

📊 Análise e Inteligência (4 ferramentas)

  • get_underperforming_vehicles - Identificar inventário de baixa rotatividade
  • analyze_inventory_health - Métricas gerais de estoque
  • apply_bulk_discount - Precificação estratégica em lote
  • get_pricing_recommendations - Sugestões de preço com IA

🌐 Publicação (4 ferramentas)

  • publish_vehicle - Enviar para portais (MyPortal, Automobile.it)
  • unpublish_vehicle - Remover de portais
  • get_publication_status - Verificar status de publicação
  • list_available_portals - Mostrar canais configurados

📈 Análise de Leads (2 ferramentas)

  • get_vehicle_leads - Rastreamento de consultas de clientes
  • analyze_lead_trends - Insights de desempenho de leads

⚡ Desempenho (1 ferramenta)

  • get_mcp_performance - Métricas de desempenho do sistema

💡 Fluxos de Trabalho Comuns

Criar um Veículo (3 etapas)

1. search_vehicle_versions → Find specifications
2. get_vehicle_version_template → Get complete data
3. add_vehicle → Create with template + price

Analisar e Otimizar Inventário

1. get_underperforming_vehicles → Find slow movers
2. get_pricing_recommendations → Get AI suggestions  
3. apply_bulk_discount → Execute pricing strategy

Enviar Imagens

For files: upload_vehicle_images with file paths
For pasted images: Save to disk first, then upload

🔧 Recursos Avançados

Busca Aprimorada de Veículos

// Sort by newest first
list_vehicles({ sort: "creationDate:desc" })

// Filter by make and model
list_vehicles({ make: "BMW", model: "Serie 3" })

// Find vehicles needing images
list_vehicles({ hasImages: false })

// Complex filtering
list_vehicles({ 
  vehicleType: "USED",
  kmMax: 50000,
  maxPrice: 25000,
  sort: "price:asc"
})

Exemplos de Linguagem Natural

"Add a 2023 BMW 320d with 15k km at €45,000"
"Show me vehicles over 90 days in stock"
"Upload these images to vehicle 12345"
"Apply 10% discount to all Mercedes over 60 days"
"Publish my best SUVs to all portals"

📚 Documentação

🧪 Testes

npm test              # Run all tests
npm run test:unit     # Unit tests only
npm run test:verbose  # Detailed output

🏗️ Arquitetura

  • 36 Ferramentas MCP em 8 módulos especializados
  • Autenticação OAuth2 com atualização automática
  • Suporte Multi-tenant para empresas/concessionárias
  • Recuperação de Erros com lógica de repetição
  • Registro Estruturado para depuração
  • Cobertura de Testes de 70%+ com testes reais de API

⚙️ Variáveis de Ambiente

Obrigatórias

  • STOCKSPARK_USERNAME - Seu e-mail de login
  • STOCKSPARK_PASSWORD - Sua senha

Opcionais

  • STOCKSPARK_COUNTRY - Mercado (it/fr/de/es), padrão: it
  • LOG_LEVEL - Nível de detalhe do registro (debug/info/warn/error)
  • MYPORTAL_ACTIVATION_CODE - Para publicação no MyPortal
  • AUTOMOBILE_IT_ACTIVATION_CODE - Para Automobile.it
  • STOCKSPARK_API_KEY - Para recursos de rastreamento de leads

Endpoints de API (Padrões Fixos)

Os seguintes estão embutidos no código e raramente precisam ser substituídos:

  • URL de Autenticação: https://auth.motork.io/realms/prod/protocol/openid-connect/token
  • URL da API: https://carspark-api.dealerk.com
  • ID do Cliente: carspark-api

📈 Atualizações Recentes

✅ Concluídas

  • Consolidação de ferramentas: 41 → 36 ferramentas (redução de 12%)
  • Busca aprimorada de veículos com ordenação e filtragem inteligente
  • Correção do mapeamento de campos de data para datas de criação adequadas
  • Exclusão de veículos com confirmação de segurança
  • Padrões fixos de API (apenas usuário e senha necessários)

🔧 Problemas Conhecidos

  • Imagem principal automática não sendo definida corretamente no upload
  • Sinalizador hasImages exibindo falso mesmo com imagens

📞 Suporte

  1. Verifique a saída do teste: npm run test:verbose
  2. Revise os registros com LOG_LEVEL=debug
  3. Consulte KNOWN_ISSUES.md para soluções
  4. Verifique as credenciais no arquivo .env

Servidor MCP pronto para produção fornecendo gerenciamento completo de concessionárias de veículos para agentes de IA.