# MCP WooCommerce Server

A Model Context Protocol (MCP) server that provides tools to interact with WooCommerce REST API.

## Features

- **Search Products**: Search for products by name or SKU
- **List Products**: Retrieve all products with pagination
- **Create Orders**: Create new orders with line items
- **Get Orders**: Retrieve specific orders by ID
- **List Orders**: List orders with optional filters
- **🔐 Authentication**: API Key-based authentication for secure access

## Setup

1. Clone this repository
2. Copy `.env.example` to `.env` and fill in your WooCommerce API credentials:
   ```bash
   WOO_URL=https://yourstore.com
   WOO_CONSUMER_KEY=your_consumer_key
   WOO_CONSUMER_SECRET=your_consumer_secret
   MCP_API_KEY=your_secure_api_key_here
   ```

3. Get your WooCommerce API credentials:
   - Go to WooCommerce > Settings > Advanced > REST API
   - Create a new key with read/write permissions
   - Copy the Consumer Key and Consumer Secret

4. Generate a secure API key for MCP authentication:
   ```bash
   # Generate a random API key (Linux/Mac)
   openssl rand -hex 32

   # Or use Python
   python -c "import secrets; print(secrets.token_hex(32))"
   ```

## Security

### Authentication

The server implements **API Key authentication** to protect against unauthorized access. When `MCP_API_KEY` is configured, all requests must include the API key in the `Authorization` header.

#### Without Authentication (Development Only)
If `MCP_API_KEY` is not set, the server runs without authentication for development purposes.

#### With Authentication (Production Recommended)
When `MCP_API_KEY` is set, clients must include:
```
Authorization: Bearer YOUR_API_KEY_HERE
```

### Security Best Practices

- **Always set `MCP_API_KEY`** in production environments
- Use strong, randomly generated API keys (32+ characters)
- Rotate API keys regularly
- Use HTTPS in production
- Limit network access to trusted sources only
- Monitor access logs for suspicious activity

## Running Locally

### With Docker Compose

```bash
docker-compose up --build
```

The server will start on `http://localhost:8200/mcp` with modular architecture.

### With Python

```bash
pip install -r requirements.txt
python -m src.server
```

## Architecture

The project uses a modular architecture with the following structure:

- `src/server.py` - FastAPI application with MCP integration and authentication
- `src/tools.py` - MCP tools implementation (5 tools for WooCommerce operations)
- `src/config.py` - Environment configuration and validation
- `src/woo_client.py` - WooCommerce API client wrapper
- `src/models.py` - Pydantic models for structured data
- `test/client_authenticated.py` - Full-featured authenticated MCP client (recommended)
- `test/client_example.py` - Basic MCP client using official libraries (limited auth support)
- `test/list_tools.py` - Simple tool listing script

## Client Compatibility Matrix

| Component | With API Key (Production) | Without API Key (Development) | Notes |
|-----------|---------------------------|-------------------------------|-------|
| **`test/client_authenticated.py`** | ✅ **Fully Supported** | ❌ Requires API key | Recommended client with full auth support |
| **Curl Scripts** (`test/*.sh`) | ✅ **Fully Supported** | ❌ Requires API key | Manual testing with proper auth headers |
| **`test/test_auth.sh`** | ✅ **Fully Supported** | ❌ Requires API key | Authentication validation script |
| **`test/list_tools.py`** | ❌ Limited support¹ | ✅ **Works** | Uses official MCP libraries |
| **`test/client_example.py`** | ❌ Limited support¹ | ✅ **Works** | Uses official MCP libraries |

¹ *Limited support: May fail with authentication errors when API key is required*

## API Endpoints

The server exposes the following MCP tools:

- `search_products(query: str, per_page: int = 10)` - Search products
- `list_products(per_page: int = 20, page: int = 1)` - List all products
- `create_order(customer_id: int, line_items: List[Dict], billing: Dict, shipping: Optional[Dict])` - Create order
- `get_order(order_id: int)` - Get specific order
- `list_orders(customer_id: Optional[int], status: Optional[str], per_page: int = 10)` - List orders

## WooCommerce API Requirements

- WooCommerce 3.5+
- WordPress 4.4+
- Pretty permalinks enabled
- REST API enabled (default)

## Testing the MCP Server

### Using the Example Clients

The project includes example MCP clients to test the server:

#### Authenticated Client (Recommended)

```bash
python test/client_authenticated.py
```

This is the **recommended client** for testing. It provides:
- ✅ Full API key authentication support
- ✅ Proper SSE response parsing
- ✅ Complete tool testing (list_products, search_products, etc.)
- ✅ Detailed output with product information
- ✅ Error handling and session management

#### Simple Tool Lister

```bash
python test/list_tools.py
```

This script connects to the MCP server and lists all available tools with their descriptions and parameters.

#### Basic Example Client (Limited)

```bash
python test/client_example.py
```

This client uses official MCP libraries but has limitations:
- ❌ Limited authentication support (may fail with API key auth)
- ❌ May encounter connection errors with authenticated servers
- ✅ Good for understanding MCP protocol structure

### Testing Scripts

The project includes curl scripts for easy testing:

```bash
# Update the AUTH_HEADER in the scripts with your API key
# Then run:
./test/curl_list_products.sh
./test/curl_search_products.sh pulseras
./test/curl_create_order.sh
```

These scripts demonstrate proper authentication and SSE response handling.

### Authentication Testing

```bash
# Run authentication tests
./test/test_auth.sh
```

This script validates that authentication is working correctly by testing different scenarios.

## Data Ingestion Examples

The project includes example scripts for ingesting product data from the MCP server:

### Bash Script (Recommended for Automation)

```bash
# Run the ingestion script
./ingestion_example.sh
```

This script demonstrates the correct format for MCP requests and handles SSE responses.

### Python Script

```bash
# Activate virtual environment and run
source .venv/bin/activate
python ingestion_example.py
```

This Python client shows how to programmatically ingest data with proper error handling.

### MCP Request Format

When building your own ingestion scripts, use this format to avoid 406 errors:

```bash
# 1. Initialize session (required)
curl -X POST http://localhost:8200/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "ingestion-client", "version": "1.0.0"}}}'

# 2. Call tools with session ID
curl -X POST http://localhost:8200/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "list_products", "arguments": {"per_page": 50}}}'
```

**Important Headers:**
- `Content-Type: application/json`
- `Accept: application/json, text/event-stream`
- `Authorization: Bearer YOUR_API_KEY`
- `Mcp-Session-Id: YOUR_SESSION_ID` (after initialization)