StockSpark MCP Server

# StockSpark MCP - AI Agent Guide ## 🎯 Project Overview StockSpark MCP is a Model Context Protocol server providing 36 specialized tools for vehicle dealership management. This guide helps AI agents work effectively with the codebase. ## 🏗️ Project Structure ``` stockspark-mcp-poc/ ├── src/ │ ├── index.js # MCP server entry point │ ├── auth.js # OAuth2 authentication │ ├── api/ # API client modules │ │ ├── client.js # Base HTTP client │ │ ├── vehicles.js # Vehicle CRUD │ │ ├── images.js # Image management │ │ ├── reference.js # Reference data │ │ ├── publications.js # Multi-channel publishing │ │ ├── organization.js # Company/dealer management │ │ └── leads.js # Customer leads │ ├── tools/ # MCP tool implementations (36 tools) │ │ ├── vehicle-tools.js # 6 tools │ │ ├── image-tools.js # 4 tools │ │ ├── reference-tools.js # 10 tools │ │ ├── organization-tools.js # 5 tools │ │ ├── analytics-tools.js # 4 tools │ │ ├── leads-tools.js # 2 tools │ │ ├── publish-tools.js # 4 tools │ │ └── performance-tools.js # 1 tool │ └── utils/ # Utilities ├── tests/ # Test suites └── .env # Configuration (user/pass only) ``` ## 🛠️ Key Implementation Patterns ### Tool Structure ```javascript { name: "tool_name", description: "What it does", inputSchema: { /* JSON schema */ }, handler: async (params) => { /* implementation */ } } ``` ### API Calls ```javascript // All API calls use the authenticated client const response = await makeApiRequest('/endpoint', { method: 'POST', body: data }); ``` ### Error Handling ```javascript // Always provide user-friendly messages throw new ApiError('User-friendly message', statusCode, details); ``` ## 📋 Development Guidelines ### When Adding Features 1. Check similar tools for patterns 2. Use existing utilities (errors, logging, mappers) 3. Run tests first: `npm test` 4. Validate inputs with JSON schema 5. Provide helpful error messages ### Testing ```bash npm test # Run all tests npm run test:unit # Unit tests npm run test:verbose # Debug mode ``` ## 🔑 Configuration ### Required in `.env` ```bash STOCKSPARK_USERNAME=email@dealer.com STOCKSPARK_PASSWORD=password ``` ### Optional ```bash STOCKSPARK_COUNTRY=it # Default: it LOG_LEVEL=debug # Default: info ``` ### Hardcoded Defaults (in code) - Auth URL: `https://auth.motork.io/realms/prod/protocol/openid-connect/token` - API URL: `https://carspark-api.dealerk.com` - Client ID: `carspark-api` ## 🎯 Common Workflows ### Vehicle Creation (Simplified) ```javascript // 1. Search specifications await search_vehicle_versions({ make: "BMW", model: "320d" }); // 2. Get template const template = await get_vehicle_version_template({ providerCode: "trim-id" }); // 3. Create vehicle await add_vehicle({ template: template.template, userOverrides: { price: 35000, condition: "NEW" } }); ``` ### Image Upload ```javascript // Files or URLs only await upload_vehicle_images({ vehicleId: 12345, imageInputs: ["/path/to/image.jpg", "https://url.com/image.jpg"] }); ``` ### Multi-tenant Operations ```javascript // Check context await get_user_context(); // Select company/dealer if needed await list_user_companies(); await select_company({ companyId: 123 }); await select_dealer({ dealerId: 456 }); ``` ## 🚨 Important Notes 1. **Authentication**: OAuth2 tokens auto-refresh 2. **Rate Limiting**: Client handles retries automatically 3. **Image Uploads**: Use bulk upload for efficiency 4. **Multi-tenancy**: Tools auto-detect company/dealer 5. **Error Recovery**: Built-in retry logic ## 🐛 Known Issues ### High Priority 1. **Auto-main image not working** - First image not set as main 2. **hasImages always false** - Flag incorrect in list response ### Recent Fixes - ✅ Organization tools fixed (listCompanies → getUserCompanies) - ✅ Hardcoded API defaults (only user/pass required) - ✅ Tool consolidation (41 → 36 tools) - ✅ Enhanced vehicle search with sorting - ✅ Vehicle deletion with confirmation ## 💡 Best Practices 1. **Batch Operations**: Use bulk endpoints when available 2. **Reference Data**: Use exact IDs from reference tools 3. **Image Optimization**: Auto-handled, no pre-processing needed 4. **Error Messages**: Always provide context 5. **Tool Naming**: Follow `category_action` pattern ## 📚 Tool Categories Summary | Category | Count | Purpose | |----------|-------|---------| | Organization | 5 | Multi-tenant management | | Reference | 10 | Vehicle specifications | | Vehicle | 6 | CRUD operations | | Image | 4 | Media management | | Analytics | 4 | Business intelligence | | Publishing | 4 | Portal distribution | | Leads | 2 | Customer tracking | | Performance | 1 | System metrics | | **TOTAL** | **36** | Complete dealership management | ## 🔄 Maintenance - Run tests before commits: `npm test` - Update dependencies: `npm update` - Check security: `npm audit` - Keep docs in sync with code --- **This guide is for AI agents working with the StockSpark MCP codebase. For user documentation, see README.md**