Stevia Store MCP Server

# 🔧 API Reference Complete documentation for all MCP tools available in the Stevia Store server. ## Table of Contents - [Product Management](#-product-management) - [Customer Management](#-customer-management) - [Order Processing](#-order-processing) - [Inventory Control](#-inventory-control) - [Analytics & Reporting](#-analytics--reporting) - [Error Handling](#-error-handling) - [Response Formats](#-response-formats) --- ## 🛍️ Product Management ### `add_product` Add a new product to the catalog. **Parameters:** - `name` (string, required) - Product name - `category` (string, required) - Product category - `price` (float, required) - Selling price in ₪ - `cost` (float, required) - Cost price in ₪ - `description` (string, optional) - Product description - `sku` (string, optional) - Stock Keeping Unit identifier **Example:** ```json { "name": "סטיביה אורגנית מיוחדת", "category": "חמרי גלם", "price": 42.90, "cost": 25.00, "description": "סטיביה איכותית במיוחד", "sku": "STEV-SPEC-001" } ``` **Response:** ``` ✅ המוצר 'סטיביה אורגנית מיוחדת' נוסף בהצלחה עם ID: 6 ``` --- ### `get_products` Retrieve product catalog with optional filtering. **Parameters:** - `category` (string, optional) - Filter by category **Example:** ```json { "category": "חמרי גלם" } ``` **Response:** ``` 🛍️ **רשימת המוצרים:** **חמרי גלם:** • **סטיביה טבעית אורגנית** (#1) מק"ט: STEV-ORG-100 | מחיר: ₪45.90 | רווח: 45.5% מלאי: 150 יחידות ✅ במלאי תיאור: סטיביה טבעית 100% אורגנית ללא תוספות כימיות ``` --- ## 👥 Customer Management ### `add_customer` Register a new customer. **Parameters:** - `name` (string, required) - Customer full name - `email` (string, required) - Email address - `phone` (string, optional) - Phone number - `address` (string, optional) - Street address - `city` (string, optional) - City name **Example:** ```json { "name": "אברהם כהן", "email": "avraham@example.com", "phone": "050-1234567", "address": "רחוב הרצל 15", "city": "תל אביב" } ``` **Response:** ``` ✅ הלקוח 'אברהם כהן' נוסף בהצלחה עם ID: 3 ``` --- ## 🛒 Order Processing ### `create_order` Create a new order for a customer. **Parameters:** - `customer_id` (integer, required) - Customer ID - `products` (string, required) - JSON array of products - `shipping_address` (string, optional) - Delivery address - `notes` (string, optional) - Order notes **Products Format:** ```json [ {"product_id": 1, "quantity": 2}, {"product_id": 3, "quantity": 1} ] ``` **Example:** ```json { "customer_id": 1, "products": "[{\"product_id\": 1, \"quantity\": 2}, {\"product_id\": 2, \"quantity\": 1}]", "shipping_address": "רחוב בן גוריון 10, חיפה", "notes": "משלוח מהיר" } ``` **Response:** ``` ✅ **הזמנה #5 נוצרה בהצלחה!** 👤 לקוח: יוסי כהן 💰 סה"כ: ₪121.70 📦 **פריטים בהזמנה:** • סטיביה טבעית אורגנית x2 - ₪91.80 • סטיביה בטבליות x1 - ₪29.90 📍 כתובת משלוח: רחוב בן גוריון 10, חיפה ``` --- ## 📦 Inventory Control ### `update_inventory` Update product stock levels. **Parameters:** - `product_id` (integer, required) - Product ID - `quantity` (integer, required) - Quantity to adjust - `operation` (string, optional) - Operation type: "set", "add", "subtract" **Example:** ```json { "product_id": 1, "quantity": 50, "operation": "add" } ``` **Response:** ``` ✅ מלאי עודכן: סטיביה טבעית אורגנית 📊 מלאי קודם: 150 → מלאי חדש: 200 ``` --- ### `get_low_stock_alerts` Get alerts for products with low inventory. **Parameters:** None **Response:** ``` ⚠️ **התראות מלאי נמוך:** 🟡 נמוך **סטיביה נוזלית ונילה** 📦 מלאי נוכחי: 8 | סף מינימום: 10 🏷️ מק"ט: STEV-LIQ-50 | קטגוריה: מוצרים מוכנים 🔴 קריטי **אבקת אפיה מיוחדת** 📦 מלאי נוכחי: 0 | סף מינימום: 5 🏷️ מק"ט: STEV-BAK-200 | קטגוריה: בישול ואפיה ``` --- ## 📈 Analytics & Reporting ### `get_sales_summary` Generate sales reports for specified time period. **Parameters:** - `days` (integer, optional) - Number of days to analyze (default: 30) **Example:** ```json { "days": 7 } ``` **Response:** ``` 📊 **סיכום מכירות - 7 ימים אחרונים** 💰 **סה"כ מכירות:** ₪1,247.50 📦 **מספר הזמנות:** 15 💳 **ממוצע הזמנה:** ₪83.17 🏆 **מוצרים מובילים:** 1. סטיביה טבעית אורגנית - 28 יחידות (₪1,285.20) 2. סטיביה בטבליות - 22 יחידות (₪657.80) 3. סטיביה נוזלית - 15 יחידות (₪598.50) 📈 **ביצועים לפי קטגוריה:** • חמרי גלם: 28 יחידות (₪1,285.20) • מוצרים מוכנים: 37 יחידות (₪1,256.30) ``` --- ## ⚠️ Error Handling All tools return error messages in Hebrew with appropriate emoji indicators: ### Common Error Types **Validation Errors:** ``` ❌ שגיאה: פורמט מוצרים לא תקין. השתמש בפורמט JSON ``` **Not Found Errors:** ``` ❌ לא נמצא לקוח עם ID: 999 ``` **Duplicate Entry Errors:** ``` ❌ שגיאה: כתובת אימייל example@test.com כבר קיימת במערכת ``` **Database Errors:** ``` ❌ שגיאה בקבלת רשימת מוצרים: connection timeout ``` --- ## 📋 Response Formats ### Success Responses - Always include ✅ emoji for successful operations - Provide clear confirmation of what was accomplished - Include relevant IDs and values for reference ### Data Responses - Use appropriate emojis for categories (🛍️📦👥💰) - Format prices with ₪ symbol - Include Hebrew text with proper RTL formatting - Use bullet points and clear structure ### Error Responses - Always start with ❌ emoji - Provide clear, actionable error messages in Hebrew - Include context about what went wrong - Suggest corrections when possible --- ## 🔗 Integration Examples ### Using with Claude Desktop Ask Claude natural language questions like: ``` "הוסף מוצר חדש: סטיביה קריסטלים, בקטגוריית חמרי גלם, במחיר 38 שקלים" "בדוק איזה מוצרים חסרים במלאי" "צור הזמנה חדשה ללקוח מספר 3 עם 2 יחידות מהמוצר הראשון" "תן לי סיכום מכירות של השבוע האחרון" ``` ### Programmatic Usage ```python import asyncio from mcp.client import stdio_client async def add_stevia_product(): async with stdio_client("python", ["src/stevia_store_server.py"]) as client: result = await client.call_tool("add_product", { "name": "סטיביה פרמיום", "category": "חמרי גלם", "price": 52.90, "cost": 28.00, "description": "סטיביה איכותית ביותר", "sku": "STEV-PREM-001" }) return result # Execute response = asyncio.run(add_stevia_product()) print(response) ``` --- *For more examples and advanced usage, see the [examples/](../examples/) directory.*