README.md•8.27 kB
# 🌿 Stevia Store MCP Server
A comprehensive Model Context Protocol (MCP) server for managing an organic stevia products e-commerce store. This server enables seamless integration with Claude to provide natural language interfaces for product management, customer service, and order processing.
## 🎯 Overview
The Stevia Store MCP Server is designed for **Organital**, a health-focused company specializing in natural stevia-based products. It provides a complete e-commerce backend that can be controlled through natural language using Claude's AI capabilities.
### Key Features
- 🛍️ **Product Management** - Complete catalog with detailed product information
- 👥 **Customer Management** - Customer profiles, preferences, and order history
- 📦 **Inventory Control** - Stock tracking with low-inventory alerts
- 🛒 **Order Processing** - Full order lifecycle from cart to delivery
- 📊 **Sales Analytics** - Comprehensive reporting and insights
- 🔒 **Security Features** - Encrypted data and secure payment processing
- 🌍 **Hebrew Language Support** - Full RTL support and Hebrew interface
## 📋 Product Catalog
Our curated selection of premium stevia products:
| Product | Price (₪) | Category | Description |
|---------|-----------|----------|-------------|
| Natural Organic Stevia 100g | 45.90 | Raw Materials | 100% pure organic stevia from Paraguay |
| Stevia Tablets (60 units) | 29.90 | Ready Products | Convenient tablets for beverages |
| Liquid Stevia Vanilla 50ml | 39.90 | Ready Products | Vanilla-flavored liquid stevia extract |
| Baking Stevia Powder 200g | 55.90 | Cooking & Baking | Heat-stable stevia for recipes |
| Tasting Bundle (4 types) | 89.90 | Gift Sets | Perfect starter pack with 4 varieties |
## 🚀 Quick Start
### Prerequisites
- Python 3.11+
- MCP SDK (`pip install mcp`)
- SQLite3
### Installation
1. **Clone the repository:**
```bash
git clone https://github.com/yairbarak22/MCPServerStevia.git
cd MCPServerStevia
```
2. **Install dependencies:**
```bash
pip install -r requirements.txt
```
3. **Initialize the database:**
```bash
python scripts/init_database.py
```
4. **Start the server:**
```bash
python src/stevia_store_server.py
```
### Configuration with Claude Desktop
Add this configuration to your Claude Desktop config file:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"stevia-store": {
"command": "python",
"args": ["path/to/MCPServerStevia/src/stevia_store_server.py"],
"env": {
"DATABASE_PATH": "path/to/your/stevia_store.db"
}
}
}
}
```
## 🛠️ Available Tools
The server provides these MCP tools for natural language interaction:
### Product Management
- `add_product` - Add new products to the catalog
- `get_products` - List products with filtering options
- `update_inventory` - Manage stock levels
- `get_low_stock_alerts` - Monitor inventory warnings
### Customer Management
- `add_customer` - Register new customers
- `get_customer_profile` - Access customer information
- `update_customer_info` - Modify customer details
### Order Processing
- `create_order` - Process new orders
- `track_order` - Monitor order status
- `calculate_cart_total` - Compute order totals
### Analytics & Reporting
- `get_sales_summary` - Generate sales reports
- `get_product_performance` - Analyze product metrics
- `get_customer_insights` - Customer behavior analysis
## 💬 Usage Examples
### Natural Language Queries
**Product Information:**
> "Show me all stevia products under 40 shekels"
**Inventory Management:**
> "Which products are running low on stock?"
**Customer Service:**
> "Create an order for customer ID 5 with 2 stevia tablets and 1 liquid vanilla"
**Sales Analysis:**
> "What were our top selling products last month?"
### Programmatic Usage
```python
import asyncio
from mcp.client import stdio_client
async def get_products():
async with stdio_client("python", ["src/stevia_store_server.py"]) as client:
result = await client.call_tool("get_products", {})
return result
# Run the async function
products = asyncio.run(get_products())
print(products)
```
## 📁 Project Structure
```
MCPServerStevia/
├── README.md # This file
├── requirements.txt # Python dependencies
├── .gitignore # Git ignore rules
├── src/ # Source code
│ ├── stevia_store_server.py # Basic MCP server
│ ├── complete_stevia_store.py # Full-featured server
│ └── secure_stevia_store.py # Enterprise security version
├── docs/ # Documentation
│ ├── API.md # API documentation
│ ├── installation.md # Setup instructions
│ └── stevia-products-spec.md # Product specifications
├── examples/ # Usage examples
│ ├── sample_usage.py # Basic usage examples
│ └── sample_data.json # Sample product data
├── scripts/ # Utility scripts
│ └── init_database.py # Database setup
└── tests/ # Test files
└── test_server.py # Unit tests
```
## 🔧 Environment Variables
Configure the server using these environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_PATH` | `stevia_store.db` | SQLite database file path |
| `MCP_SERVER_PORT` | `3000` | Server port for HTTP transport |
| `ENCRYPTION_KEY` | `None` | Key for sensitive data encryption |
| `LOG_LEVEL` | `INFO` | Logging verbosity level |
## 🔐 Security Features
- 🔒 **Data Encryption** - Sensitive customer data is encrypted at rest
- 🛡️ **Input Validation** - All inputs are sanitized and validated
- 🔐 **Access Control** - Role-based permissions system
- 📝 **Audit Logging** - Complete activity logs for compliance
- 🚫 **SQL Injection Protection** - Parameterized queries only
## 🧪 Testing
Run the test suite:
```bash
# Run all tests
python -m pytest tests/
# Run with coverage
python -m pytest tests/ --cov=src
# Run specific test
python -m pytest tests/test_server.py::test_add_product
```
## 📈 Performance
The server is optimized for:
- **10,000+ concurrent users**
- **Sub-200ms response times**
- **99.9% uptime availability**
- **Automatic database optimization**
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📚 Documentation
- [API Reference](docs/API.md) - Complete API documentation
- [Installation Guide](docs/installation.md) - Detailed setup instructions
- [Product Specifications](docs/stevia-products-spec.md) - Product catalog details
- [MCP Protocol Guide](https://modelcontextprotocol.io/) - Official MCP documentation
## 📞 Support
Need help? We're here for you:
- 📧 **Email:** support@organital.co.il
- 🐛 **Bug Reports:** [GitHub Issues](https://github.com/yairbarak22/MCPServerStevia/issues)
- 💬 **Discussions:** [GitHub Discussions](https://github.com/yairbarak22/MCPServerStevia/discussions)
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🌟 About Organital
[Organital](https://organital.co.il) is Israel's leading provider of natural stevia products, committed to promoting healthy living through pure, organic sweetening solutions. Our products are:
- ✅ **100% Natural** - No artificial additives
- 🌱 **Organic Certified** - Sustainably sourced
- 💚 **Health Focused** - Zero calories, diabetic-friendly
- 🏅 **Premium Quality** - Rigorous quality control
---
<div align="center">
<p>Made with 💚 by the Organital team</p>
<p><strong>🌿 Sweet. Natural. Healthy. 🌿</strong></p>
</div>