StockSpark MCP Server

Un servidor MCP para la gestión de concesionarios de vehículos impulsada por IA.

GitHub

Documentación

Servidor MCP StockSpark

Un servidor de Protocolo de Contexto de Modelo (MCP) listo para producción que proporciona a los agentes de IA 36 herramientas especializadas para la gestión completa de concesionarios de vehículos a través de la plataforma API StockSpark/Carspark.

🚀 Inicio Rápido

1. Instalación

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

2. Configuración

Crea el archivo .env con tus credenciales:

# 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. Probar Conexión

npm test

4. Conectar a Claude Desktop

Añade a tu configuración de 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"
      }
    }
  }
}

📋 Herramientas Disponibles (36 en Total)

🏢 Gestión de Organización (5 herramientas)

  • get_user_context - Ver selección actual de empresa/concesionario
  • list_user_companies - Listar empresas accesibles
  • select_company - Elegir empresa de trabajo
  • list_company_dealers - Listar concesionarios de la empresa
  • select_dealer - Elegir concesionario de trabajo

🔍 Datos de Referencia de Vehículos (10 herramientas)

  • search_vehicle_versions - Búsqueda progresiva de especificaciones de vehículos
  • compare_vehicle_versions - Comparar versiones/acabados similares
  • get_vehicle_version_template - Obtener plantilla completa de datos de vehículo
  • get_vehicle_makes - Listar fabricantes disponibles
  • get_vehicle_models - Obtener modelos de una marca
  • get_vehicle_trims - Obtener niveles de acabado con especificaciones
  • get_vehicle_transmissions - Tipos de transmisión disponibles
  • get_vehicle_bodies - Opciones de carrocería
  • get_vehicle_fuels - Opciones de tipo de combustible
  • get_vehicle_colors - Colores disponibles

🚗 Gestión de Vehículos (6 herramientas)

  • add_vehicle - Crear nuevo vehículo (plantilla o manual)
  • get_vehicle - Recuperar detalles del vehículo
  • list_vehicles - Buscar/filtrar inventario con ordenación
  • update_vehicle - Modificar datos del vehículo
  • update_vehicle_price - Actualizaciones rápidas de precio
  • delete_vehicle - Eliminar vehículo (con confirmación)

📸 Gestión de Imágenes (4 herramientas)

  • upload_vehicle_images - Carga masiva desde archivos/URLs
  • get_vehicle_images - Listar imágenes del vehículo
  • set_vehicle_main_image - Establecer imagen principal de visualización
  • delete_vehicle_image - Eliminar imágenes específicas

📊 Analítica e Inteligencia (4 herramientas)

  • get_underperforming_vehicles - Identificar inventario de baja rotación
  • analyze_inventory_health - Métricas generales de stock
  • apply_bulk_discount - Precios estratégicos por volumen
  • get_pricing_recommendations - Sugerencias de precios impulsadas por IA

🌐 Publicación (4 herramientas)

  • publish_vehicle - Publicar en portales (MyPortal, Automobile.it)
  • unpublish_vehicle - Eliminar de portales
  • get_publication_status - Verificar estado de publicación
  • list_available_portals - Mostrar canales configurados

📈 Análisis de Prospectos (2 herramientas)

  • get_vehicle_leads - Seguimiento de consultas de clientes
  • analyze_lead_trends - Información sobre rendimiento de prospectos

⚡ Rendimiento (1 herramienta)

  • get_mcp_performance - Métricas de rendimiento del sistema

💡 Flujos de Trabajo Comunes

Crear un Vehículo (3 Pasos)

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

Analizar y Optimizar Inventario

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

Subir Imágenes

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

🔧 Funciones Avanzadas

Búsqueda Mejorada de Vehí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"
})

Ejemplos de Lenguaje 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"

📚 Documentación

🧪 Pruebas

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

🏗️ Arquitectura

  • 36 Herramientas MCP en 8 módulos especializados
  • Autenticación OAuth2 con renovación automática
  • Soporte Multi-tenant para empresas/concesionarios
  • Recuperación de Errores con lógica de reintentos
  • Registro Estructurado para depuración
  • Cobertura de Pruebas del 70%+ con pruebas reales de API

⚙️ Variables de Entorno

Requeridas

  • STOCKSPARK_USERNAME - Tu correo de inicio de sesión
  • STOCKSPARK_PASSWORD - Tu contraseña

Opcionales

  • STOCKSPARK_COUNTRY - Mercado (it/fr/de/es), predeterminado: it
  • LOG_LEVEL - Detalle de registro (debug/info/warn/error)
  • MYPORTAL_ACTIVATION_CODE - Para publicación en MyPortal
  • AUTOMOBILE_IT_ACTIVATION_CODE - Para Automobile.it
  • STOCKSPARK_API_KEY - Para funciones de seguimiento de prospectos

Endpoints de API (Valores Predeterminados Fijos)

Los siguientes están integrados en el código y rara vez necesitan sobrescribirse:

  • URL de Autenticación: https://auth.motork.io/realms/prod/protocol/openid-connect/token
  • URL de API: https://carspark-api.dealerk.com
  • ID de Cliente: carspark-api

📈 Actualizaciones Recientes

✅ Completadas

  • Consolidación de herramientas: 41 → 36 herramientas (reducción del 12%)
  • Búsqueda mejorada de vehículos con ordenación y filtrado inteligente
  • Corrección del mapeo de campos de fecha para fechas de creación adecuadas
  • Eliminación de vehículos con confirmación de seguridad
  • Valores predeterminados de API fijos (solo se requieren nombre de usuario/contraseña)

🔧 Problemas Conocidos

  • La imagen principal automática no se establece correctamente al cargar
  • El indicador hasImages muestra falso incluso con imágenes

📞 Soporte

  1. Verificar salida de pruebas: npm run test:verbose
  2. Revisar registros con LOG_LEVEL=debug
  3. Consultar KNOWN_ISSUES.md para soluciones
  4. Verificar credenciales en el archivo .env

Servidor MCP listo para producción que proporciona gestión completa de concesionarios de vehículos para agentes de IA.