StockSpark MCP Server

A production-ready Model Context Protocol (MCP) server that provides AI agents with 36 specialized tools for complete vehicle dealership management through the StockSpark/Carspark API platform.

🚀 Quick Start

1. Install

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

2. Configure

Create .env file with your credentials:

# 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. Test Connection

npm test

4. Connect to Claude Desktop

Add to your Claude Desktop config:

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"
      }
    }
  }
}

📋 Available Tools (36 Total)

🏢 Organization Management (5 tools)

• get_user_context - View current company/dealer selection
• list_user_companies - List accessible companies
• select_company - Choose working company
• list_company_dealers - List company's dealers
• select_dealer - Choose working dealer

🔍 Vehicle Reference Data (10 tools)

• search_vehicle_versions - Progressive search for vehicle specifications
• compare_vehicle_versions - Compare similar trims/versions
• get_vehicle_version_template - Get complete vehicle data template
• get_vehicle_makes - List available manufacturers
• get_vehicle_models - Get models for a make
• get_vehicle_trims - Get trim levels with specifications
• get_vehicle_transmissions - Available transmission types
• get_vehicle_bodies - Body style options
• get_vehicle_fuels - Fuel type options
• get_vehicle_colors - Available colors

🚗 Vehicle Management (6 tools)

• add_vehicle - Create new vehicle (template or manual)
• get_vehicle - Retrieve vehicle details
• list_vehicles - Search/filter inventory with sorting
• update_vehicle - Modify vehicle data
• update_vehicle_price - Quick price updates
• delete_vehicle - Remove vehicle (with confirmation)

📸 Image Management (4 tools)

• upload_vehicle_images - Bulk upload from files/URLs
• get_vehicle_images - List vehicle images
• set_vehicle_main_image - Set primary display image
• delete_vehicle_image - Remove specific images

📊 Analytics & Intelligence (4 tools)

• get_underperforming_vehicles - Identify slow-moving inventory
• analyze_inventory_health - Overall stock metrics
• apply_bulk_discount - Strategic bulk pricing
• get_pricing_recommendations - AI-powered pricing suggestions

🌐 Publishing (4 tools)

• publish_vehicle - Push to portals (MyPortal, Automobile.it)
• unpublish_vehicle - Remove from portals
• get_publication_status - Check publishing status
• list_available_portals - Show configured channels

📈 Lead Analysis (2 tools)

• get_vehicle_leads - Customer inquiry tracking
• analyze_lead_trends - Lead performance insights

⚡ Performance (1 tool)

• get_mcp_performance - System performance metrics

💡 Common Workflows

Create a Vehicle (3 Steps)

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

Analyze & Optimize Inventory

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

Upload Images

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

🔧 Advanced Features

Enhanced Vehicle Search

// 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"
})

Natural Language Examples

"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"

📚 Documentation

• AI Agent Guide (CLAUDE.md) - For AI agents working with the codebase
• Documentation Index - Complete documentation guide
• Known Issues - Current limitations and fixes

🧪 Testing

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

🏗️ Architecture

• 36 MCP Tools across 8 specialized modules
• OAuth2 Authentication with auto-refresh
• Multi-tenant Support for companies/dealers
• Error Recovery with retry logic
• Structured Logging for debugging
• 70%+ Test Coverage with real API testing

⚙️ Environment Variables

Required

• STOCKSPARK_USERNAME - Your login email
• STOCKSPARK_PASSWORD - Your password

Optional

• STOCKSPARK_COUNTRY - Market (it/fr/de/es), default: it
• LOG_LEVEL - Logging detail (debug/info/warn/error)
• MYPORTAL_ACTIVATION_CODE - For MyPortal publishing
• AUTOMOBILE_IT_ACTIVATION_CODE - For Automobile.it
• STOCKSPARK_API_KEY - For lead tracking features

API Endpoints (Hardcoded Defaults)

The following are built into the code and rarely need override:

• Auth URL: https://auth.motork.io/realms/prod/protocol/openid-connect/token
• API URL: https://carspark-api.dealerk.com
• Client ID: carspark-api

📈 Recent Updates

✅ Completed

• Tool consolidation: 41 → 36 tools (12% reduction)
• Enhanced vehicle search with sorting and smart filtering
• Fixed date field mapping for proper creation dates
• Vehicle deletion with safety confirmation
• Hardcoded API defaults (only username/password required)

🔧 Known Issues

• Auto-main image not setting correctly on upload
• hasImages flag showing false even with images

📞 Support

1. Check test output: npm run test:verbose
2. Review logs with LOG_LEVEL=debug
3. See KNOWN_ISSUES.md for solutions
4. Verify credentials in .env file

---

Production-ready MCP server providing complete vehicle dealership management for AI agents.