Superprecio MCP Server

# Superprecio MCP V2 - New Features 🚀 ## Summary We've added **9 powerful new MCP tools** to supercharge your price comparison experience! Now you can create shopping lists, set price alerts, and find nearby supermarkets - all through Claude. --- ## 🆕 What's New ### **15 Total Tools** (6 from V1 + 9 new in V2) #### V1 Tools (Existing) 1. `search_products` - Search products by description 2. `search_by_code` - Search by barcode/EAN 3. `compare_prices` - Compare prices across supermarkets 4. `get_best_deals` - Find current offers 5. `send_notification` - Send push notifications 6. `subscribe_device` - Subscribe to notifications #### ✨ V2 Tools (NEW!) **Shopping Lists** (5 tools) 7. `create_shopping_list` - Create a new shopping list 8. `add_items_to_list` - Add products to a list 9. `get_shopping_lists` - View all your lists 10. **`optimize_shopping_list`** - 🔥 **FIND THE BEST SUPERMARKET FOR YOUR ENTIRE LIST!** 11. `remove_shopping_list` - Delete a list **Price Alerts** (3 tools) 12. `set_price_alert` - Get notified when products reach target price 13. `get_my_alerts` - View all active alerts with status 14. `remove_price_alert` - Delete an alert **Location** (1 tool) 15. `find_nearby_supermarkets` - Find stores near your GPS location --- ## 🔥 The Star Feature: `optimize_shopping_list` This is the game-changer! Instead of comparing individual products, now you can: 1. Create a complete shopping list (e.g., 10-20 products) 2. Run `optimize_shopping_list` with the list ID 3. Get instant results showing which supermarket gives you the **lowest total price** 4. See **exactly how much you save** by shopping at the best store ### Example Use Case ``` User: "I need to buy: milk, bread, eggs, rice, chicken, tomatoes, lettuce" Claude uses create_shopping_list: - Creates list "Weekly Groceries" - Adds all 7 items Claude uses optimize_shopping_list: - Searches ALL supermarkets for each item - Calculates total cost at each store - Result: "Shop at Carrefour for $4,523 - Save $876 vs. Disco!" ``` ### What Makes It Powerful? - **Real-time price checking** across 11+ Argentinian supermarkets - **Complete basket optimization** (not just individual items) - **Actual savings calculation** in pesos and percentage - **Missing item detection** (tells you if a store doesn't have something) - **Detailed breakdown** per item with quantities --- ## 📊 API Changes (Backend) ### New Database Tables (4 tables) ```sql -- Shopping lists shopping_lists (id, user_id?, name, description?, created_at, updated_at) -- List items shopping_list_items (id, list_id, product_name, barcode?, quantity, notes?, created_at) -- User price alerts user_price_alerts (id, user_id?, product_name, barcode?, target_price, current_price?, is_active, notify_enabled, last_checked_at, created_at, updated_at) -- Supermarket locations supermarket_locations (id, supermarket_id, branch_name, address, city, latitude, longitude, phone?, opening_hours?, created_at) ``` ### New API Endpoints (14 routes) **Shopping Lists** - `POST /api/lists` - Create list - `GET /api/lists` - Get all lists - `GET /api/lists/:id` - Get specific list - `DELETE /api/lists/:id` - Delete list - `POST /api/lists/:id/items` - Add items - `POST /api/lists/:id/optimize` - 🔥 Optimize (find best supermarket) **Price Alerts** - `POST /api/alerts` - Create alert - `GET /api/alerts` - Get alerts - `PUT /api/alerts/:id` - Update alert - `DELETE /api/alerts/:id` - Delete alert - `POST /api/alerts/check` - Check current prices **Locations** - `GET /api/locations/nearby` - Find nearby stores (Haversine formula) - `GET /api/locations` - Get all locations --- ## 🏗️ Architecture Highlights ### Smart Design Decisions 1. **Reuses existing infrastructure** - `optimize_shopping_list` uses the same `Search.description()` service - No new scraping code needed - Leverages existing VTEX API integration 2. **Database efficiency** - Soft deletes for lists (can recover) - Indexes on lat/lng for fast location queries - Indexes on alert status for quick filtering 3. **Backwards compatible** - All V1 tools still work - No breaking changes - Additive API design 4. **Type-safe** - TypeScript throughout - Explicit types in MCP tools - Adonis models with relationships --- ## 📝 Usage Examples ### Example 1: Complete Shopping Workflow ```typescript // 1. Create a list create_shopping_list({ name: "Weekend BBQ", items: [ { productName: "Carne picada", quantity: 2 }, { productName: "Pan hamburguesa", quantity: 1 }, { productName: "Coca Cola 2.25L", quantity: 2 } ] }) // Returns: List ID 42 // 2. Add more items add_items_to_list({ listId: 42, items: [ { productName: "Lechuga", quantity: 1 }, { productName: "Tomate", quantity: 1 } ] }) // 3. Find best supermarket optimize_shopping_list({ listId: 42 }) // Result: "Best price at Carrefour: $3,245 (vs $3,890 at Jumbo)" // 4. Find nearest Carrefour find_nearby_supermarkets({ latitude: -34.6037, longitude: -58.3816, radiusKm: 5 }) // Returns: Carrefour locations sorted by distance ``` ### Example 2: Price Alert Workflow ```typescript // 1. Set alert for expensive item set_price_alert({ productName: "Aceite Cocinero 1.5L", targetPrice: 1200 }) // Returns: Alert ID 15 // 2. Check if price dropped get_my_alerts() // Shows: "Current: $1,450 (+$250 from target)" // Later... get_my_alerts() // Shows: "🎉 TRIGGERED! Current: $1,150 (-$50 from target)" ``` --- ## 🔧 Setup & Migration ### For API (Superprecio) ```bash # Run migrations cd ~/Development/superprecio node ace migration:run # Start server npm run dev ``` ### For MCP Server ```bash # Build cd ~/Development/superprecio_mcp npm run build # Test (optional) npm test ``` ### Claude Desktop Configuration No changes needed! The MCP server automatically exposes all 15 tools. --- ## 💡 Implementation Details ### The Optimization Algorithm When you run `optimize_shopping_list`, here's what happens: 1. **Fetch list** from database with all items 2. **For each item**: - Search across ALL supermarkets using `Search.description()` - Use barcode if available (exact match) - Otherwise use product name (fuzzy match) 3. **Aggregate results** by supermarket: - Track total cost per market - Count found vs missing items - Store per-item prices 4. **Sort by total cost** (lowest first) 5. **Calculate savings** (best vs worst) 6. **Return detailed breakdown** ### Performance Considerations - **Parallel searches**: Uses `Promise.all()` for concurrent API calls - **Caching opportunity**: Could cache product prices for 1-2 hours - **Rate limiting**: Built into VTEX APIs (respects server limits) - **Timeout handling**: 30s default timeout per request --- ## 🚀 Future Enhancements ### Potential V3 Features 1. **Historical price tracking** - Store price history over time - Show price trends (↗️ rising, ↘️ falling) - Predict best time to buy 2. **Smart recommendations** - AI-powered product suggestions - "Users who bought X also bought Y" - Category-based deals 3. **Social features** - Share lists with family/friends - Collaborative shopping - Community price reports 4. **Advanced analytics** - Monthly spending reports - Category breakdown - Savings tracker --- ## 📊 Performance Metrics ### V2 Scale - **Database**: 4 new tables, ~50 columns total - **API**: 14 new endpoints - **MCP Tools**: 9 new tools (150% increase) - **Code**: ~2,500 lines added (API + MCP) - **File count**: ~31 new files ### Response Times (estimated) - `create_shopping_list`: < 100ms - `optimize_shopping_list` (10 items): 2-5 seconds - `set_price_alert`: < 100ms - `find_nearby_supermarkets`: < 200ms --- ## 🎉 Summary V2 transforms Superprecio MCP from a **product search tool** into a **complete shopping assistant**! **Before V2**: Search individual products, compare prices **After V2**: Create lists, optimize entire shopping baskets, get alerts, find stores This makes the MCP incredibly useful for real-world shopping in Argentina, with plans to expand to all Latin America. --- **Developed with ❤️ for the Argentinian community** **Ready for npm publication and Claude Desktop integration**