# StockSpark MCP Server

A production-ready Model Context Protocol (MCP) server that provides AI agents with 36 specialized tools for complete vehicle dealership management through the StockSpark/Carspark API platform.

## 🚀 Quick Start

### 1. Install
```bash
git clone https://github.com/loukach/stockspark-mcp-poc.git
cd stockspark-mcp-poc
npm install
```

### 2. Configure
Create `.env` file with your credentials:
```bash
# Required - Your StockSpark credentials
STOCKSPARK_USERNAME=your-email@dealership.com
STOCKSPARK_PASSWORD=your-password

# Optional - Override defaults if needed
# STOCKSPARK_COUNTRY=it  # Default: it
# LOG_LEVEL=debug  # Default: info
```

### 3. Test Connection
```bash
npm test
```

### 4. Connect to Claude Desktop

Add to your Claude Desktop config:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "stockspark": {
      "command": "node",
      "args": ["/absolute/path/to/stockspark-mcp-poc/src/index.js"],
      "env": {
        "STOCKSPARK_USERNAME": "your-email@dealership.com",
        "STOCKSPARK_PASSWORD": "your-password"
      }
    }
  }
}
```

## 📋 Available Tools (36 Total)

### 🏢 Organization Management (5 tools)
- `get_user_context` - View current company/dealer selection
- `list_user_companies` - List accessible companies  
- `select_company` - Choose working company
- `list_company_dealers` - List company's dealers
- `select_dealer` - Choose working dealer

### 🔍 Vehicle Reference Data (10 tools)
- `search_vehicle_versions` - Progressive search for vehicle specifications
- `compare_vehicle_versions` - Compare similar trims/versions
- `get_vehicle_version_template` - Get complete vehicle data template
- `get_vehicle_makes` - List available manufacturers
- `get_vehicle_models` - Get models for a make
- `get_vehicle_trims` - Get trim levels with specifications
- `get_vehicle_transmissions` - Available transmission types
- `get_vehicle_bodies` - Body style options
- `get_vehicle_fuels` - Fuel type options
- `get_vehicle_colors` - Available colors

### 🚗 Vehicle Management (6 tools)
- `add_vehicle` - Create new vehicle (template or manual)
- `get_vehicle` - Retrieve vehicle details
- `list_vehicles` - Search/filter inventory with sorting
- `update_vehicle` - Modify vehicle data
- `update_vehicle_price` - Quick price updates
- `delete_vehicle` - Remove vehicle (with confirmation)

### 📸 Image Management (4 tools)
- `upload_vehicle_images` - Bulk upload from files/URLs
- `get_vehicle_images` - List vehicle images
- `set_vehicle_main_image` - Set primary display image
- `delete_vehicle_image` - Remove specific images

### 📊 Analytics & Intelligence (4 tools)
- `get_underperforming_vehicles` - Identify slow-moving inventory
- `analyze_inventory_health` - Overall stock metrics
- `apply_bulk_discount` - Strategic bulk pricing
- `get_pricing_recommendations` - AI-powered pricing suggestions

### 🌐 Publishing (4 tools)
- `publish_vehicle` - Push to portals (MyPortal, Automobile.it)
- `unpublish_vehicle` - Remove from portals
- `get_publication_status` - Check publishing status
- `list_available_portals` - Show configured channels

### 📈 Lead Analysis (2 tools)
- `get_vehicle_leads` - Customer inquiry tracking
- `analyze_lead_trends` - Lead performance insights

### ⚡ Performance (1 tool)
- `get_mcp_performance` - System performance metrics

## 💡 Common Workflows

### Create a Vehicle (3 Steps)
```
1. search_vehicle_versions → Find specifications
2. get_vehicle_version_template → Get complete data
3. add_vehicle → Create with template + price
```

### Analyze & Optimize Inventory
```
1. get_underperforming_vehicles → Find slow movers
2. get_pricing_recommendations → Get AI suggestions  
3. apply_bulk_discount → Execute pricing strategy
```

### Upload Images
```
For files: upload_vehicle_images with file paths
For pasted images: Save to disk first, then upload
```

## 🔧 Advanced Features

### Enhanced Vehicle Search
```javascript
// Sort by newest first
list_vehicles({ sort: "creationDate:desc" })

// Filter by make and model
list_vehicles({ make: "BMW", model: "Serie 3" })

// Find vehicles needing images
list_vehicles({ hasImages: false })

// Complex filtering
list_vehicles({ 
  vehicleType: "USED",
  kmMax: 50000,
  maxPrice: 25000,
  sort: "price:asc"
})
```

### Natural Language Examples
```
"Add a 2023 BMW 320d with 15k km at €45,000"
"Show me vehicles over 90 days in stock"
"Upload these images to vehicle 12345"
"Apply 10% discount to all Mercedes over 60 days"
"Publish my best SUVs to all portals"
```

## 📚 Documentation

- [AI Agent Guide (CLAUDE.md)](CLAUDE.md) - For AI agents working with the codebase
- [Documentation Index](docs/INDEX.md) - Complete documentation guide
- [Known Issues](KNOWN_ISSUES.md) - Current limitations and fixes

## 🧪 Testing

```bash
npm test              # Run all tests
npm run test:unit     # Unit tests only
npm run test:verbose  # Detailed output
```

## 🏗️ Architecture

- **36 MCP Tools** across 8 specialized modules
- **OAuth2 Authentication** with auto-refresh
- **Multi-tenant Support** for companies/dealers
- **Error Recovery** with retry logic
- **Structured Logging** for debugging
- **70%+ Test Coverage** with real API testing

## ⚙️ Environment Variables

### Required
- `STOCKSPARK_USERNAME` - Your login email
- `STOCKSPARK_PASSWORD` - Your password

### Optional
- `STOCKSPARK_COUNTRY` - Market (it/fr/de/es), default: it
- `LOG_LEVEL` - Logging detail (debug/info/warn/error)
- `MYPORTAL_ACTIVATION_CODE` - For MyPortal publishing
- `AUTOMOBILE_IT_ACTIVATION_CODE` - For Automobile.it
- `STOCKSPARK_API_KEY` - For lead tracking features

### API Endpoints (Hardcoded Defaults)
The following are built into the code and rarely need override:
- Auth URL: `https://auth.motork.io/realms/prod/protocol/openid-connect/token`
- API URL: `https://carspark-api.dealerk.com`
- Client ID: `carspark-api`

## 📈 Recent Updates

### ✅ Completed
- Tool consolidation: 41 → 36 tools (12% reduction)
- Enhanced vehicle search with sorting and smart filtering
- Fixed date field mapping for proper creation dates
- Vehicle deletion with safety confirmation
- Hardcoded API defaults (only username/password required)

### 🔧 Known Issues
- Auto-main image not setting correctly on upload
- `hasImages` flag showing false even with images

## 📞 Support

1. Check test output: `npm run test:verbose`
2. Review logs with `LOG_LEVEL=debug`
3. See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for solutions
4. Verify credentials in `.env` file

---

**Production-ready MCP server providing complete vehicle dealership management for AI agents.**