stockspark-mcp-poc

loukach/stockspark-mcp-poc

3.1

If you are the rightful owner of stockspark-mcp-poc and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

StockSpark MCP Server is a production-ready Model Context Protocol server designed to transform AI agents into comprehensive vehicle dealership management systems.

Tools
5
Resources
0
Prompts
0

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

  • - For AI agents working with the codebase
  • - Complete documentation guide
  • - 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 for solutions
  4. Verify credentials in .env file

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