StockSpark MCP Server

# 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 ```bash git clone https://github.com/loukach/stockspark-mcp-poc.git cd stockspark-mcp-poc npm install ``` ### 2. Configure Create `.env` file with your credentials: ```bash # 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 ```bash 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` ```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 ```javascript // 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)](CLAUDE.md) - For AI agents working with the codebase - [Documentation Index](docs/INDEX.md) - Complete documentation guide - [Known Issues](KNOWN_ISSUES.md) - Current limitations and fixes ## 🧪 Testing ```bash 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](KNOWN_ISSUES.md) for solutions 4. Verify credentials in `.env` file --- **Production-ready MCP server providing complete vehicle dealership management for AI agents.**