StockSpark MCP Server

# Tool Consolidation Analysis for Stockspark MCP ## Executive Summary This document analyzes the current implementation of high-priority tools in the Stockspark MCP and proposes consolidation strategies to reduce redundancy, improve user experience, and optimize performance. ## 1. Image Upload Tools Analysis ### Current Implementation (3 Tools) #### 1.1 `upload_vehicle_images_claude` - **Purpose**: Optimized for Claude UI pasted/dropped images - **API Endpoint**: `POST /{country}/vehicle/{vehicleId}/images/gallery/upload` - **Input**: Claude image objects with base64 data - **Processing Logic**: 1. Saves base64 images to temp files using filesystem MCP 2. Uploads files via multipart/form-data 3. Cleans up temp files 4. Falls back to base64 upload if filesystem fails - **Performance**: 70-90% faster than base64 methods - **Special Features**: Auto-sets first image as main if vehicle has no images #### 1.2 `upload_vehicle_images` - **Purpose**: Upload from file paths or URLs - **API Endpoint**: Same as above - **Input**: Array of file paths or URLs - **Processing Logic**: 1. Separates file paths from URLs 2. For files: Creates FormData with file stream 3. For URLs: Downloads image first, then uploads 4. Handles MCP resource objects (data URIs) - **Performance**: 2-5s per image - **Special Features**: Batch upload support (1-50 images) #### 1.3 `upload_vehicle_images_from_data` - **Purpose**: Direct base64 upload (fallback method) - **API Endpoint**: Same as above - **Input**: Array of objects with base64 data, mimeType, filename - **Processing Logic**: 1. Validates base64 data 2. Converts to Buffer 3. Creates FormData and uploads - **Performance**: 70-90% slower than file-based methods - **Special Features**: Used as fallback when filesystem MCP unavailable ### Consolidation Proposal for Image Upload (COMPLETED) **✅ Successfully created a single `upload_vehicle_images` tool that:** 1. Auto-detects input type (file paths, URLs, MCP resources) 2. Handles batch uploads efficiently 3. Provides clear feedback about which method was used 4. Maintains all current functionality **Benefits:** - Single tool for all image upload scenarios - Automatic optimization without user intervention - Clearer error messages and fallback handling ## 2. Vehicle Creation Tools Analysis ### Current Implementation (4 Tools) #### 2.1 `start_vehicle_creation` - **Purpose**: Step 1 of recommended workflow - find make/model/trims - **API Endpoints**: - `GET /vehicle/models` (if make provided) - `GET /vehicle/trims` (if model provided) - **Input**: make_name, optional model_name, filters - **Processing Logic**: 1. Find models for make using fuzzy matching 2. If model specified, get trims with filters 3. Suggest next steps based on results - **Output**: List of models or trims with detailed specs #### 2.2 `create_vehicle_from_trim` - **Purpose**: Step 3 - Create vehicle with complete specifications - **API Endpoints**: - `GET /vehicle/compileByTrim` (compile template) - `POST /vehicle` (create vehicle) - **Input**: providerCode, provider, price, condition, optional overrides - **Processing Logic**: 1. Compile vehicle template from trim 2. Clean/minimize data structure 3. Add user inputs (price, condition, etc.) 4. Create vehicle - **Special Features**: Includes all technical specs automatically #### 2.3 `compare_trim_variants` - **Purpose**: Step 2 (optional) - Compare similar trims - **API Endpoint**: `GET /vehicle/trims` - **Input**: model_id, base_model_name, filters - **Processing Logic**: 1. Get all trims for model 2. Filter by base name 3. Format comparison table 4. Provide selection guidance - **Output**: Side-by-side comparison of variants #### 2.4 `add_vehicle` - **Purpose**: Manual vehicle creation (last resort) - **API Endpoint**: `POST /vehicle` - **Input**: Basic vehicle data (make, model, price, etc.) - **Processing Logic**: Direct creation with minimal data - **Limitations**: No technical specs, emissions, or equipment details ### Consolidation Proposal for Vehicle Creation **Create a single `create_vehicle` tool that:** 1. Accepts flexible input (trim ID or manual data) 2. Automatically determines best creation method 3. Guides through trim selection if needed 4. Falls back to manual creation only when necessary **Workflow Integration:** - If trim ID provided → use compile + create flow - If make/model provided → show trims → use compile + create - If only basic data → warn about limitations, create manually ## 3. Reference Data Tools Analysis ### Current Duplicate Tools #### 3.1 Makes - `get_available_makes`: Uses `/refdata/CAR/makes` (reference data API) - `get_vehicle_makes`: Uses `/vehicle/makes` (navigation API) - **Difference**: Navigation API supports country and vehicle class #### 3.2 Models - `get_available_models`: Uses `/refdata/CAR/makes/{make}/models` - `get_vehicle_models`: Uses `/vehicle/models` - **Difference**: Navigation API includes body type, fuel type metadata #### 3.3 Fuel Types - `get_fuel_types`: Uses `/refdata/CAR/fuels` - `get_vehicle_fuels`: Uses `/vehicle/fuels` - **Difference**: Navigation API supports country/class filtering ### Consolidation Proposal for Reference Data **Keep only the navigation API tools:** 1. Rename to be more intuitive: - `get_vehicle_makes` → `get_makes` - `get_vehicle_models` → `get_models` - `get_vehicle_fuels` → `get_fuel_types` 2. Make country/class parameters optional with smart defaults 3. Remove the duplicate reference data API tools **Benefits:** - Single source of truth for each data type - More features (country/class support) - Consistent API usage ## 4. Implementation Priority ### Phase 1: Image Upload Consolidation (High Impact, Low Risk) 1. Create unified `upload_vehicle_images` tool 2. Deprecate the three existing tools 3. Update documentation and examples ### Phase 2: Reference Data Cleanup (Medium Impact, Low Risk) 1. Remove duplicate reference tools 2. Rename navigation tools for clarity 3. Update all dependent tools ### Phase 3: Vehicle Creation Simplification (High Impact, Medium Risk) 1. Design unified `create_vehicle` interface 2. Implement smart workflow detection 3. Maintain backward compatibility initially 4. Gradual migration and deprecation ## 5. API Endpoint Summary ### Core Endpoints Used 1. **Vehicle Management** - `POST /vehicle` - Create vehicle - `GET /vehicle/{id}` - Get vehicle details - `PUT /vehicle/{id}` - Update vehicle - `GET /vehicle` - List vehicles 2. **Image Management** - `POST /{country}/vehicle/{id}/images/gallery/upload` - Upload image - Images stored in vehicle object under `images.GALLERY_ITEM` 3. **Reference/Navigation** - `GET /vehicle/makes` - Get makes - `GET /vehicle/models` - Get models - `GET /vehicle/trims` - Get trims - `GET /vehicle/compileByTrim` - Compile vehicle template 4. **Legacy Reference (to be removed)** - `GET /refdata/CAR/makes` - `GET /refdata/CAR/makes/{make}/models` - `GET /refdata/CAR/fuels` ## 6. Error Handling Patterns ### Common Error Scenarios 1. **Missing Organization Context**: Tools check for company/dealer selection 2. **Invalid Vehicle ID**: Validation before API calls 3. **Upload Failures**: Graceful fallback from filesystem to base64 4. **Missing Trim Data**: Fallback to manual creation with warnings ### Consistent Error Response Format ```javascript { content: [{ type: 'text', text: '❌ Error message with guidance' }], isError: true } ``` ## 7. Performance Considerations ### Image Upload Performance - **Filesystem method**: 1-2s per image - **URL download**: 2-5s per image - **Base64 upload**: 5-10s per image - **Batch processing**: Optimal at 10-20 images ### API Call Optimization - Minimize compile + create to single workflow - Cache reference data where possible - Use batch operations for multiple vehicles ## 8. Conclusion The proposed consolidations will: 1. Reduce tool count from 11 to approximately 6-7 2. Improve user experience with smarter automation 3. Maintain all current functionality 4. Provide clearer upgrade paths 5. Reduce maintenance burden The phased approach allows for gradual migration with minimal disruption to existing users.