# E-commerce MCP Server

A FastMCP server for managing products, customers, and orders with full CRUD operations and data analysis capabilities.

## Installation

```bash
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install fastmcp sqlalchemy aiosqlite
```

## Running the Server

```bash
# Using fastmcp CLI
fastmcp run ecommerce_server.py

# Or directly with Python
python ecommerce_server.py
```

## Configuring with Claude Desktop

Add this to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ecommerce": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/ecommerce_server.py"],
      "env": {
        "ECOMMERCE_DB_PATH": "/path/to/ecommerce.db"
      }
    }
  }
}
```

## Available Tools (25 total)

### Product Management
| Tool | Description |
|------|-------------|
| `add_product` | Add a new product to inventory |
| `get_product` | Get product by ID or SKU |
| `list_products` | List products with filtering (category, stock level) |
| `update_product` | Update product details |
| `delete_product` | Soft delete (deactivate) a product |
| `update_stock` | Add or subtract stock quantity |
| `search_products` | Search products by name/description |

### Customer Management
| Tool | Description |
|------|-------------|
| `add_customer` | Add a new customer |
| `get_customer` | Get customer by ID or email |
| `list_customers` | List customers with filtering |
| `update_customer` | Update customer details |
| `delete_customer` | Soft delete (deactivate) a customer |
| `search_customers` | Search customers by name/email |

### Order Management
| Tool | Description |
|------|-------------|
| `create_order` | Create a new order for a customer |
| `add_order_item` | Add a product to an order |
| `remove_order_item` | Remove a product from an order |
| `get_order` | Get order by ID or order number |
| `list_orders` | List orders with filtering (customer, status, date range) |
| `update_order_status` | Update order status (pending → confirmed → shipped → delivered) |

### Data Analysis & Reporting
| Tool | Description |
|------|-------------|
| `get_sales_summary` | Revenue, order count, average order value for a period |
| `get_top_products` | Top selling products by quantity and revenue |
| `get_top_customers` | Top customers by spend and order count |
| `get_inventory_report` | Stock levels, out-of-stock items, category breakdown |
| `get_customer_order_history` | Complete order history for a customer |
| `get_profit_analysis` | Profit margins by product (requires cost data) |

## Example Usage

### Adding Products
```
"Add a product: iPhone 15 Pro, SKU: IP15PRO, price $999, cost $750, 50 in stock, category Electronics"
```

### Managing Customers
```
"Add customer John Doe, email john@example.com, phone 555-1234"
"Find all customers in New York"
```

### Creating Orders
```
"Create an order for customer ID 1"
"Add 2 units of product ID 3 to order ID 1"
"Mark order 1 as shipped"
```

### Data Analysis
```
"Show me the sales summary for this month"
"What are the top 5 selling products?"
"Which products are low on stock?"
"Show profit analysis for Q4"
```

## Database

The server uses SQLite by default. The database file location can be configured via the `ECOMMERCE_DB_PATH` environment variable.

### Schema
- **Products**: id, name, description, sku, price, cost, quantity_in_stock, category, is_active
- **Customers**: id, email, first_name, last_name, phone, address, city, state, postal_code, country, is_active
- **Orders**: id, customer_id, order_number, status, total_amount, shipping_address, notes
- **OrderItems**: id, order_id, product_id, quantity, unit_price

## Order Statuses
- `pending` - Order created, awaiting confirmation
- `confirmed` - Order confirmed, stock reserved
- `shipped` - Order shipped to customer
- `delivered` - Order delivered
- `cancelled` - Order cancelled, stock restored