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
git clone https://github.com/loukach/stockspark-mcp-poc.git
cd stockspark-mcp-poc
npm install
2. Configure
Create .env file with your credentials:
# 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
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
{
"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 selectionlist_user_companies- List accessible companiesselect_company- Choose working companylist_company_dealers- List company's dealersselect_dealer- Choose working dealer
🔍 Vehicle Reference Data (10 tools)
search_vehicle_versions- Progressive search for vehicle specificationscompare_vehicle_versions- Compare similar trims/versionsget_vehicle_version_template- Get complete vehicle data templateget_vehicle_makes- List available manufacturersget_vehicle_models- Get models for a makeget_vehicle_trims- Get trim levels with specificationsget_vehicle_transmissions- Available transmission typesget_vehicle_bodies- Body style optionsget_vehicle_fuels- Fuel type optionsget_vehicle_colors- Available colors
🚗 Vehicle Management (6 tools)
add_vehicle- Create new vehicle (template or manual)get_vehicle- Retrieve vehicle detailslist_vehicles- Search/filter inventory with sortingupdate_vehicle- Modify vehicle dataupdate_vehicle_price- Quick price updatesdelete_vehicle- Remove vehicle (with confirmation)
📸 Image Management (4 tools)
upload_vehicle_images- Bulk upload from files/URLsget_vehicle_images- List vehicle imagesset_vehicle_main_image- Set primary display imagedelete_vehicle_image- Remove specific images
📊 Analytics & Intelligence (4 tools)
get_underperforming_vehicles- Identify slow-moving inventoryanalyze_inventory_health- Overall stock metricsapply_bulk_discount- Strategic bulk pricingget_pricing_recommendations- AI-powered pricing suggestions
🌐 Publishing (4 tools)
publish_vehicle- Push to portals (MyPortal, Automobile.it)unpublish_vehicle- Remove from portalsget_publication_status- Check publishing statuslist_available_portals- Show configured channels
📈 Lead Analysis (2 tools)
get_vehicle_leads- Customer inquiry trackinganalyze_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
// 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) - For AI agents working with the codebase
- Documentation Index - Complete documentation guide
- Known Issues - Current limitations and fixes
🧪 Testing
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 emailSTOCKSPARK_PASSWORD- Your password
Optional
STOCKSPARK_COUNTRY- Market (it/fr/de/es), default: itLOG_LEVEL- Logging detail (debug/info/warn/error)MYPORTAL_ACTIVATION_CODE- For MyPortal publishingAUTOMOBILE_IT_ACTIVATION_CODE- For Automobile.itSTOCKSPARK_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
hasImagesflag showing false even with images
📞 Support
- Check test output:
npm run test:verbose - Review logs with
LOG_LEVEL=debug - See KNOWN_ISSUES.md for solutions
- Verify credentials in
.envfile
Production-ready MCP server providing complete vehicle dealership management for AI agents.