# π Installation Guide
Complete installation and setup guide for the Stevia Store MCP Server.
## Table of Contents
- [System Requirements](#-system-requirements)
- [Quick Installation](#-quick-installation)
- [Detailed Setup](#-detailed-setup)
- [Claude Desktop Integration](#-claude-desktop-integration)
- [Environment Configuration](#-environment-configuration)
- [Database Setup](#-database-setup)
- [Troubleshooting](#-troubleshooting)
- [Verification](#-verification)
---
## π₯οΈ System Requirements
### Minimum Requirements
- **Python:** 3.11 or higher
- **RAM:** 512MB available memory
- **Storage:** 100MB free disk space
- **OS:** Windows 10+, macOS 10.15+, or Linux Ubuntu 20.04+
### Recommended Requirements
- **Python:** 3.12+
- **RAM:** 2GB available memory
- **Storage:** 1GB free disk space
- **OS:** Latest stable versions
### Dependencies
- `mcp` - Model Context Protocol SDK
- `sqlite3` - Database (included with Python)
- `fastmcp` - FastMCP server framework
- `asyncio` - Async support (included with Python)
---
## β‘ Quick Installation
For users who want to get started immediately:
```bash
# 1. Clone the repository
git clone https://github.com/yairbarak22/MCPServerStevia.git
cd MCPServerStevia
# 2. Install dependencies
pip install -r requirements.txt
# 3. Initialize database
python scripts/init_database.py
# 4. Start the server
python src/stevia_store_server.py
```
That's it! The server should now be running.
---
## π§ Detailed Setup
### Step 1: Environment Preparation
**Check Python Version:**
```bash
python --version
# Should return 3.11.0 or higher
```
**Create Virtual Environment (Recommended):**
```bash
# Create virtual environment
python -m venv stevia_env
# Activate it
# On Windows:
stevia_env\Scripts\activate
# On macOS/Linux:
source stevia_env/bin/activate
```
### Step 2: Download and Install
**Option A: Clone from GitHub**
```bash
git clone https://github.com/yairbarak22/MCPServerStevia.git
cd MCPServerStevia
```
**Option B: Download ZIP**
1. Go to [GitHub repository](https://github.com/yairbarak22/MCPServerStevia)
2. Click "Code" β "Download ZIP"
3. Extract to desired location
4. Navigate to the folder
### Step 3: Install Dependencies
```bash
# Install required packages
pip install -r requirements.txt
# Verify installation
pip list | grep mcp
```
**Manual Installation (if requirements.txt fails):**
```bash
pip install mcp
pip install fastmcp
pip install sqlite3
```
### Step 4: Database Initialization
```bash
# Run the database setup script
python scripts/init_database.py
# Verify database was created
ls -la stevia_store.db
```
You should see output like:
```
Initializing database: stevia_store.db
Creating tables...
Loading sample data...
Database initialized successfully!
- Products: 5
- Customers: 2
```
---
## π Claude Desktop Integration
### Step 1: Locate Configuration File
Find your Claude Desktop configuration file:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
### Step 2: Update Configuration
Add this configuration to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"stevia-store": {
"command": "python",
"args": ["FULL_PATH_TO/MCPServerStevia/src/stevia_store_server.py"],
"env": {
"DATABASE_PATH": "FULL_PATH_TO/MCPServerStevia/stevia_store.db"
}
}
}
}
```
**Important:** Replace `FULL_PATH_TO` with the actual path to your installation.
**Example (macOS):**
```json
{
"mcpServers": {
"stevia-store": {
"command": "python",
"args": ["/Users/john/MCPServerStevia/src/stevia_store_server.py"],
"env": {
"DATABASE_PATH": "/Users/john/MCPServerStevia/stevia_store.db"
}
}
}
}
```
### Step 3: Restart Claude Desktop
1. Completely close Claude Desktop
2. Restart the application
3. You should see the Stevia Store tools available
---
## βοΈ Environment Configuration
### Environment Variables
Create a `.env` file in your project root:
```bash
# Database configuration
DATABASE_PATH=./stevia_store.db
# Server configuration
MCP_SERVER_PORT=3000
LOG_LEVEL=INFO
# Security (for production)
ENCRYPTION_KEY=your-32-character-encryption-key-here
# Business settings
DEFAULT_CURRENCY=ILS
DEFAULT_LANGUAGE=he
COMPANY_NAME=ΧΧΧ¨ΧΧ ΧΧΧ
```
### Loading Environment Variables
The server automatically loads environment variables. For manual loading:
```python
import os
from dotenv import load_dotenv
load_dotenv()
database_path = os.getenv('DATABASE_PATH', 'stevia_store.db')
```
---
## ποΈ Database Setup
### Automatic Setup (Recommended)
```bash
python scripts/init_database.py
```
### Manual Database Setup
If you need to create the database manually:
```bash
# Connect to SQLite
sqlite3 stevia_store.db
# Run SQL commands (see scripts/init_database.py for full schema)
CREATE TABLE products (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
category TEXT NOT NULL,
price REAL NOT NULL,
-- ... more fields
);
-- Exit SQLite
.exit
```
### Database Backup
Create regular backups:
```bash
# Create backup
cp stevia_store.db stevia_store_backup_$(date +%Y%m%d).db
# Restore from backup
cp stevia_store_backup_20241225.db stevia_store.db
```
---
## π Troubleshooting
### Common Issues
**Issue: "mcp module not found"**
```bash
# Solution: Install MCP SDK
pip install mcp
```
**Issue: "Permission denied" on database**
```bash
# Solution: Fix file permissions
chmod 664 stevia_store.db
```
**Issue: "Python version not supported"**
```bash
# Solution: Upgrade Python
python --version # Check current version
# Install Python 3.11+ from python.org
```
**Issue: "Port already in use"**
```bash
# Solution: Kill process on port
lsof -ti:3000 | xargs kill -9
# Or change port in environment variables
```
### Debug Mode
Run the server in debug mode:
```bash
# Enable debug logging
export LOG_LEVEL=DEBUG
python src/stevia_store_server.py
```
### Check Logs
View server logs:
```bash
# If using systemd (Linux)
journalctl -u stevia-store -f
# Or check application logs
tail -f stevia_store.log
```
---
## β
Verification
### Test Installation
**1. Check Server Start:**
```bash
python src/stevia_store_server.py
# Should show: "Stevia Store MCP Server started"
```
**2. Test Database Connection:**
```bash
python -c "import sqlite3; print('Database OK' if sqlite3.connect('stevia_store.db') else 'Database Error')"
```
**3. Test MCP Tools:**
```bash
python examples/sample_usage.py
# Should show available tools and sample data
```
### Integration Test with Claude
1. Open Claude Desktop
2. Type: "List all stevia products"
3. You should see product information
4. Try: "Add a new customer named Test User with email test@example.com"
### Performance Test
```bash
# Run performance test
python -m timeit -n 100 -s "import sqlite3; conn=sqlite3.connect('stevia_store.db')" "cursor=conn.cursor(); cursor.execute('SELECT COUNT(*) FROM products'); conn.close()"
```
---
## π¦ Next Steps
After successful installation:
1. **π Read the [API Documentation](API.md)**
2. **π§ͺ Try the [Examples](../examples/)**
3. **βοΈ Customize your [Configuration](#environment-configuration)**
4. **π Set up [Security Features](security.md)** (for production)
5. **π Configure [Monitoring](monitoring.md)** (optional)
---
## π Support
If you encounter issues:
1. **Check this troubleshooting guide**
2. **Search [GitHub Issues](https://github.com/yairbarak22/MCPServerStevia/issues)**
3. **Create a new issue with:**
- Your operating system
- Python version (`python --version`)
- Error messages
- Steps to reproduce
---
**Happy coding! πΏ**
