StockSpark MCP Server

# Current Vehicle Creation Implementation Analysis ## Tool Inventory ### 1. `start_vehicle_creation` (reference-tools.js) - **Handler**: Lines 422-467 - **APIs**: - `referenceAPI.findModelsByMake()` → GET /vehicle/models - `referenceAPI.getVehicleTrims()` → GET /vehicle/trims - **Key Logic**: Fuzzy matching for make names, progressive year filtering ### 2. `compare_trim_variants` (reference-tools.js) - **Handler**: Lines 469-520 - **APIs**: `referenceAPI.getVehicleTrims()` with filtering - **Key Logic**: Groups and compares similar trim names ### 3. `compile_vehicle_by_trim` (reference-tools.js) - **Handler**: Lines 522-542 - **APIs**: `referenceAPI.compileVehicleByTrim()` → GET /vehicle/compileByTrim - **Returns**: Preview of vehicle data ### 4. `create_vehicle_from_trim` (reference-tools.js) - **Handler**: Lines 544-614 - **APIs**: - `referenceAPI.compileVehicleByTrim()` (internal) - `vehicleAPI.addVehicle()` → POST /vehicle - **Key Logic**: Merges trim data with user inputs ### 5. `add_vehicle` (vehicle-tools.js) - **Handler**: Lines 176-201 - **APIs**: `vehicleAPI.addVehicle()` → POST /vehicle - **Key Logic**: Basic vehicle creation without trim data ## API Layer Details ### ReferenceAPI Methods - `findModelsByMake()`: Includes fuzzy matching fallback - `getVehicleTrims()`: Handles year-to-manufacture date conversion - `compileVehicleByTrim()`: Fetches complete vehicle template ### VehicleAPI Methods - `addVehicle()`: Direct POST to /vehicle endpoint - Includes organization context injection ## Data Flow Patterns ### Fuzzy Matching (reference.js:315-318) ```javascript make.name.toLowerCase().includes(makeName.toLowerCase()) || makeName.toLowerCase().includes(make.name.toLowerCase()) ``` ### Year to Date Conversion (reference.js:245) ```javascript if (year && !manufactureDate) { params.set('manufactureDate', `01-${year}`); } ``` ### Template Merging (reference-tools.js:584-592) - Preserves trim data structure - Overlays user inputs for price, mileage, condition - Maintains equipment and technical specifications ## Current Pain Points 1. **Naming Confusion** - `start_vehicle_creation` doesn't create - `compile_vehicle_by_trim` vs `create_vehicle_from_trim` 2. **Hidden Dependencies** - `create_vehicle_from_trim` calls compile internally - Organization context required but not obvious 3. **Inconsistent Patterns** - Some tools return formatted text, others return JSON - Error handling varies between tools 4. **API Inefficiencies** - Multiple calls for single workflow - No caching of reference data ## Test Coverage ### Unit Tests - `test-vehicle-creation.js`: Basic creation flow - `test-reference-data.js`: Reference API calls - Missing: Fuzzy matching tests, error scenarios ### Integration Tests - `test-complete-workflow.js`: Full creation workflow - Good coverage of happy path - Missing: Edge cases, partial data scenarios ## Migration Considerations 1. **Data Structures** - Current tools expect specific ID formats - Provider codes are tightly coupled - Organization context is implicit 2. **Error Messages** - Currently embedded in handlers - Need to preserve helpful guidance 3. **Workflow Dependencies** - Many users rely on exact tool names - Documentation references current flow ## Key Files Reference 1. `/src/tools/reference-tools.js` - Lines 1-614 2. `/src/tools/vehicle-tools.js` - Lines 1-322 3. `/src/api/reference.js` - Lines 307-331 (fuzzy matching) 4. `/src/api/vehicles.js` - Lines 13-89 (addVehicle) 5. `/src/utils/mappers.js` - Vehicle data transformation