StockSpark MCP Server

# Vehicle Color Update Guide ## ✅ **Issue Fixed** The vehicle color update functionality has been improved to handle the API's color structure correctly. ### **Problem** Previously, updating a vehicle's color would only update the `color` field, leaving the `colorBase` object inconsistent, causing API validation errors. ### **Solution** The `updateVehicle` method now: 1. **Looks up colors** from the API's color reference data 2. **Updates both fields** consistently: - `color`: The display name (e.g., "Rosso") - `colorBase`: The structured object with name and description 3. **Handles fallbacks** gracefully when colors aren't found ## **How to Use** ### **Step 1: Get Available Colors** ```javascript // Use the MCP tool to see available colors get_vehicle_colors() ``` This returns colors like: ``` 🎨 Available Vehicle Colors: 1. **Bianco** (Bianco) 2. **Nero** (Nero) 3. **Rosso** (Rosso) 4. **Blu** (Blu) 5. **Grigio** (Grigio) ... ``` ### **Step 2: Update Vehicle Color** ```javascript // Use the exact color name from the list update_vehicle({ vehicleId: 9765338, updates: { color: "Rosso" } }) ``` ### **What Happens Behind the Scenes** ```javascript // Before (incorrect): { "color": "Rosso", "colorBase": { "name": "PINK", // ❌ Inconsistent! "description": "Rosa" } } // After (correct): { "color": "Rosso", "colorBase": { "name": "RED", // ✅ Consistent! "description": "Rosso" } } ``` ## **Advanced Usage** ### **Case-Insensitive Matching** The system now handles case-insensitive color matching: ```javascript // All of these work: update_vehicle({vehicleId: 123, updates: {color: "rosso"}}) update_vehicle({vehicleId: 123, updates: {color: "ROSSO"}}) update_vehicle({vehicleId: 123, updates: {color: "Rosso"}}) ``` ### **Fallback Behavior** If a color isn't found in the reference data: - The provided color is used as-is - `colorBase` is set to `null` to avoid inconsistency - The API will validate the color value ### **Error Handling** Improved error messages guide users to correct usage: ``` ❌ Color update failed: Invalid color value 💡 Tip: Use get_vehicle_colors to see all available color options, then use the exact color name. ``` ## **Technical Implementation** ### **Enhanced `updateVehicle` Method** ```javascript // In src/api/vehicles.js async updateVehicle(vehicleId, updates) { // Get current vehicle const currentVehicle = await this.getVehicle(vehicleId); // Special handling for color updates if (updates.color) { const colorsResponse = await this.client.get('/refdata/colors'); const colors = Array.isArray(colorsResponse) ? colorsResponse : (colorsResponse.values || []); const matchingColor = colors.find(c => c.name.toLowerCase() === updates.color.toLowerCase() || (c.description && c.description.toLowerCase() === updates.color.toLowerCase()) ); if (matchingColor) { updates.color = matchingColor.description || matchingColor.name; updates.colorBase = { name: matchingColor.name, description: matchingColor.description || matchingColor.name }; } } // Continue with update... } ``` ### **Improved Tool Description** ```javascript // In src/tools/vehicle-tools.js description: `Update multiple vehicle attributes (POC - no validation) Available fields: mileage, numberPlate, description, color, any vehicle attribute 💡 For color updates: Use get_vehicle_colors first to see available options, then use the exact color name.` ``` ## **Benefits** ✅ **Consistent data**: Both `color` and `colorBase` are always synchronized ✅ **Better UX**: Clear guidance and helpful error messages ✅ **Robust**: Handles edge cases and API inconsistencies gracefully ✅ **Case-insensitive**: Flexible input handling ✅ **Backward compatible**: Existing code continues to work ## **Usage Examples** ### **Example 1: Update Toyota Yaris to Red** ```javascript // 1. Check available colors get_vehicle_colors() // 2. Update to red update_vehicle({ vehicleId: 9765338, updates: {color: "Rosso"} }) // Response: // ✅ Vehicle 9765338 updated successfully! // 📝 Updated fields: color // // 💡 Color updated to: Rosso // Note: Both color and colorBase fields were updated for consistency. ``` ### **Example 2: Multiple Field Update Including Color** ```javascript update_vehicle({ vehicleId: 9765338, updates: { color: "Blu", mileage: 45000, numberPlate: "AB123CD" } }) ``` ### **Example 3: Error Handling** ```javascript // Invalid color update_vehicle({ vehicleId: 9765338, updates: {color: "Purple"} }) // Response: // ❌ Color update failed: Invalid color value // // 💡 Tip: Use get_vehicle_colors to see all available color options, then use the exact color name. ``` ## **Testing** All existing tests continue to pass, ensuring the fix doesn't break other functionality: ```bash npm test # 🎯 OVERALL: 8/8 tests passed (100.0%) ```