StockSpark MCP Server

# Simplified Vehicle Creation Redesign - Clean Implementation ## Overview Clean implementation of 4 new vehicle creation tools, replacing the current 5 confusing tools. No migration needed - we'll delete the old code. ## Implementation Plan ### Step 1: Delete Old Tools Remove from `reference-tools.js`: - `start_vehicle_creation` - `compare_trim_variants` - `compile_vehicle_by_trim` - `create_vehicle_from_trim` Keep from `vehicle-tools.js`: - `add_vehicle` (will be enhanced) ### Step 2: Implement New Tools #### 1. `search_vehicle_specs` ```javascript { name: "search_vehicle_specs", description: "Smart search for vehicle specifications. Returns makes, models, or trims based on input.", inputSchema: { type: "object", properties: { make: { type: "string", description: "Make name (optional)" }, model: { type: "string", description: "Model name (optional)" }, year: { type: "number", description: "Year filter (optional)" }, fuel: { type: "string", description: "Fuel type filter (optional)" }, vehicleClass: { type: "string", default: "car" }, country: { type: "string", default: "it" } } } } ``` #### 2. `compare_vehicle_options` ```javascript { name: "compare_vehicle_options", description: "Compare multiple vehicle trim options side-by-side", inputSchema: { type: "object", properties: { trimIds: { type: "array", items: { type: "string" }, description: "Array of trim IDs to compare" } }, required: ["trimIds"] } } ``` #### 3. `get_vehicle_template` ```javascript { name: "get_vehicle_template", description: "Get enriched vehicle specifications from trim code", inputSchema: { type: "object", properties: { providerCode: { type: "string", description: "Trim ID" }, provider: { type: "string", description: "Data provider (optional)" }, vehicleClass: { type: "string", default: "car" } }, required: ["providerCode"] } } ``` #### 4. `add_vehicle` (enhanced) ```javascript { name: "add_vehicle", description: "Create vehicle with template or basic data", inputSchema: { type: "object", oneOf: [ { properties: { template: { type: "object" }, userOverrides: { type: "object", properties: { price: { type: "number" }, mileage: { type: "number" }, condition: { type: "string", enum: ["NEW", "USED", "KM0"] }, color: { type: "string" }, numberPlate: { type: "string" } } } }, required: ["template", "userOverrides"] }, { properties: { basicData: { type: "object", properties: { make: { type: "string" }, model: { type: "string" }, version: { type: "string" }, year: { type: "number" }, price: { type: "number" }, fuel: { type: "string" }, transmission: { type: "string" }, condition: { type: "string" } }, required: ["make", "model", "year", "price", "fuel", "transmission", "condition"] } }, required: ["basicData"] } ] } } ``` ### Step 3: Implementation Details #### `search_vehicle_specs` Logic ```javascript async function searchVehicleSpecs(args, { referenceAPI }) { const { make, model, year, fuel, country = 'it', vehicleClass = 'car' } = args; // No input - return all makes if (!make) { return await referenceAPI.getVehicleMakes(country); } // Only make - return models if (make && !model) { return await referenceAPI.findModelsByMake(country, make, vehicleClass); } // Make + model - return trims if (make && model) { // First find model ID const models = await referenceAPI.findModelsByMake(country, make, vehicleClass); const modelMatch = models.models.find(m => m.name.toLowerCase().includes(model.toLowerCase()) ); if (modelMatch) { return await referenceAPI.getVehicleTrims(country, modelMatch.id, { year, fuel, page: 0, size: 100 }); } } return { found: 0, message: "No matches found" }; } ``` ### Step 4: Clean Implementation Benefits 1. **No backward compatibility needed** 2. **Clean, consistent API** 3. **No deprecation warnings** 4. **Simplified testing** 5. **Clear documentation** ### Step 5: File Changes 1. **Delete from `reference-tools.js`**: - Lines 8-169 (old vehicle creation tools) - Lines 421-614 (old handlers) 2. **Add to `reference-tools.js`**: - New tool definitions - New handler implementations 3. **Update `vehicle-tools.js`**: - Enhance `add_vehicle` to accept templates 4. **Update tests**: - Remove old tool tests - Add new tool tests ### Step 6: Testing Strategy 1. **Unit tests for each tool** 2. **Integration test for complete flow** 3. **Edge case testing** 4. **Performance comparison** ### Step 7: Documentation Updates 1. Update `CLAUDE.md` with new workflow 2. Update `README.md` with new examples 3. Remove references to old tools 4. Add clear examples for each new tool ## Example Usage ### Find and Create Vehicle ```javascript // Search for vehicle const results = await search_vehicle_specs({ make: "BMW", model: "320i", year: 2023 }); // Get template for selected trim const template = await get_vehicle_template({ providerCode: results.trims[0].id }); // Create vehicle await add_vehicle({ template: template.template, userOverrides: { price: 35000, condition: "NEW" } }); ``` ### Quick Basic Creation ```javascript await add_vehicle({ basicData: { make: "Fiat", model: "500", year: 2023, price: 15000, fuel: "PETROL", transmission: "MANUAL", condition: "NEW" } }); ``` ## Success Metrics 1. Reduced code complexity 2. Clearer tool purposes 3. Better AI agent experience 4. Improved maintainability 5. Consistent patterns ## No Migration = Faster Implementation Since we're not migrating: - Week 1: Implement and test all new tools - Week 2: Update documentation and deploy - No compatibility layer needed - No deprecation timeline - Clean, fresh start!