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

2. Configure

Create .env file with your credentials:

3. Test Connection

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

📋 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)

Analyze & Optimize Inventory

Upload Images

🔧 Advanced Features

Enhanced Vehicle Search

Natural Language Examples

📚 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

🏗️ 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.