StockSpark MCP Server

# Vehicle Search Functionality Bug Report **StockSpark MCP Server - Critical Issue** ## Executive Summary The vehicle version search functionality is completely broken due to a pagination parameter issue in the `/vehicle/trims` API endpoint. This prevents users from creating vehicles with complete technical specifications and forces fallback to basic manual data entry. ## Impact Assessment - **Severity:** HIGH - Core functionality unavailable - **User Impact:** Cannot access vehicle templates with complete specs - **Business Impact:** Reduced data quality, manual data entry required - **Affected Operations:** Vehicle creation with templates, version lookup, technical specifications ## Technical Details ### Failing Endpoints - `GET /vehicle/trims` - All calls fail with SERVER_ERROR or socket hang up - Affects all model IDs tested (1551, 1552, 28830, 1236, 1037) - Occurs across all vehicle makes (Toyota, BMW, Fiat, etc.) ### Working Endpoints - `GET /vehicle/makes` ✅ - `GET /vehicle/models` ✅ - Basic vehicle creation ✅ ### Root Cause Analysis The MCP is making API calls with an excessive page size parameter: ```http GET /vehicle/trims?modelId=1551&page=0&size=2147483647 ``` **Problem:** `size=2147483647` (Integer.MAX_VALUE) causes: 1. Memory allocation failures on server 2. Database query timeouts 3. HTTP response size limits exceeded 4. API gateway timeouts ### Error Messages Observed ``` StockSpark API server error during GET /vehicle/trims 💡 Tip: This is a server-side issue. Try again in a few minutes. 🔍 Error Code: SERVER_ERROR ``` ``` Unexpected error during GET /vehicle/trims: request to https://carspark-api.dealerk.com/it/vehicle/trims failed, reason: socket hang up ``` ## Affected MCP Functions ### Completely Broken - `search_vehicle_versions(make, model)` - Cannot retrieve version lists - `get_vehicle_trims(model_id)` - All calls fail - `get_vehicle_version_template(provider_code)` - Cannot get vehicle templates ### Functional Workarounds - `add_vehicle(basicData)` - Manual data entry (missing technical specs) - `search_vehicle_versions(make)` - Returns model list only ## Business Logic Impact ### What Users Cannot Do - Create vehicles with complete technical specifications - Access emissions data, equipment lists, engine details - Use vehicle templates for accurate data population - Browse available versions/trims for specific models ### Current Workaround Users must manually enter vehicle data using `basicData` mode, resulting in: - Incomplete vehicle specifications - Missing technical details - Reduced data quality - Increased manual work ## Required Fixes ### Priority 1: Immediate Fix **File:** MCP Server pagination logic **Change:** Replace `size=2147483647` with reasonable pagination ```javascript // Current (broken) const params = { modelId: id, page: 0, size: 2147483647 // This breaks everything } // Proposed fix const params = { modelId: id, page: 0, size: 50 // Reasonable page size } ``` ### Priority 2: API Protection **File:** API server validation **Add:** Maximum page size validation ```javascript // Validate page size limits if (req.query.size > 1000) { return res.status(400).json({ error: "Page size too large. Maximum allowed: 1000" }); } ``` ### Priority 3: Pagination Implementation **File:** MCP client logic **Add:** Proper pagination handling to fetch all results ```javascript // Implement pagination loop let allTrims = []; let page = 0; const pageSize = 50; do { const response = await fetchTrims(modelId, page, pageSize); allTrims.push(...response.data); page++; } while (response.hasMore); ``` ## Testing Requirements ### Test Cases 1. **Basic trim lookup:** `get_vehicle_trims(1551)` should return results 2. **Version search:** `search_vehicle_versions("Toyota", "Yaris")` should work 3. **Template creation:** `get_vehicle_version_template(code)` should succeed 4. **Pagination:** Verify large result sets are handled properly 5. **Error handling:** Test with invalid model IDs ### Success Criteria - All trim lookups complete without SERVER_ERROR - Vehicle templates contain complete technical specifications - No timeout errors on large datasets - Proper pagination for models with many versions ## Timeline Recommendations - **Immediate (< 24h):** Fix page size parameter in MCP - **Short term (< 1 week):** Add API validation and limits - **Medium term (< 1 month):** Implement proper pagination ## Dependencies - MCP Server codebase access - API server configuration access - Database performance review (if queries are actually slow) ## Contact Information - **Reporter:** Vehicle Manager (MCP User) - **Date:** June 27, 2025 - **Environment:** Production StockSpark MCP - **API Base:** https://carspark-api.dealerk.com/it/ --- *This report contains all necessary technical details for the development team to reproduce and fix the issue.*