# MCP Server - Customer & Order Analytics

A **Model Context Protocol (MCP)** server implementation that provides AI-powered tools for querying customer and order data. This FastAPI-based server enables LLM clients to access structured business data through three specialized tools for customer analytics and order management.

## 🚀 Overview

This MCP server acts as a bridge between AI language models and business data, allowing LLMs to:
- Count customer orders by month
- Retrieve recent customers by country
- Calculate customer lifetime value and spending patterns

The server follows the Model Context Protocol specification, making it compatible with various AI clients and frameworks that support MCP integration.

## ✨ Features

### Core MCP Tools
1. **Order Count by Customer & Month** - Track customer ordering patterns over time
2. **Recent Customers by Country** - Discover new customers in specific markets
3. **Customer Total Spend** - Analyze customer lifetime value and spending behavior

### Technical Features
- **FastAPI Framework** - High-performance async API with automatic documentation
- **Pydantic Validation** - Type-safe data models with automatic validation
- **JSON Data Backend** - Simple file-based storage for customers and orders
- **Comprehensive Logging** - Full request/response logging for debugging
- **Health Monitoring** - Built-in health check endpoints
- **CORS Support** - Cross-origin requests enabled for web clients

## 🏗️ Architecture

```
mcp-server/
├── main.py                     # FastAPI application entry point
├── requirements.txt            # Python dependencies
├── data/                       # JSON data files
│   ├── customers.json          # Customer records
│   └── orders.json             # Order transactions
├── src/                        # Source code
│   ├── models/                 # Data models and schemas
│   │   ├── schemas.py          # Pydantic models for validation
│   │   └── data_loader.py      # Data loading utilities
│   └── tools/                  # MCP tools implementation
│       └── mcp_tools.py        # Tool implementations
├── tests/                      # Test suite
├── llm_client/                 # Example LLM client implementation
└── docs/                       # Documentation
```

## 🛠️ Available Tools

### 1. get_order_count_by_customer_and_month
Count orders for a specific customer in a given calendar month.

**Input:**
```json
{
  "customerName": "John Doe",
  "isoMonth": "2025-03"
}
```

**Output:**
```json
{
  "count": 2
}
```

### 2. list_recent_customers_by_country
Fetch the newest N customers from a specific country.

**Input:**
```json
{
  "country": "USA",
  "limit": 5
}
```

**Output:**
```json
{
  "customers": [
    {
      "id": 1,
      "name": "John Doe",
      "country": "USA",
      "joinedAt": "2025-01-15T10:30:00Z",
      "totalSpend": 1250.50,
      "orderCount": 3
    }
  ]
}
```

### 3. get_customer_total_spend
Calculate total spending and order statistics for a customer.

**Input:**
```json
{
  "customerName": "John Doe"
}
```

**Output:**
```json
{
  "customerName": "John Doe",
  "totalSpend": 1250.50,
  "orderCount": 3,
  "averageOrderValue": 416.83
}
```

## 🚦 Quick Start

### Prerequisites
- Python 3.9+
- pip or poetry for dependency management

### Installation

1. **Clone the repository:**
```bash
git clone <repository-url>
cd mcp-server
```

2. **Install dependencies:**
```bash
pip install -r requirements.txt
```

3. **Start the server:**
```bash
python main.py
```

The server will start on `http://localhost:8000`

### Production Deployment
```bash
uvicorn main:app --host 0.0.0.0 --port 8000
```

## 📡 API Endpoints

### Health Check
- **GET** `/` - Basic health check
- **GET** `/health` - Detailed health status

### MCP Protocol Endpoints
- **GET** `/tools/list` - List available MCP tools
- **POST** `/tools/call` - Execute a specific tool

### Example Usage

**List available tools:**
```bash
curl http://localhost:8000/tools/list
```

**Call a tool:**
```bash
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_order_count_by_customer_and_month",
    "arguments": {
      "customerName": "John Doe",
      "isoMonth": "2025-03"
    }
  }'
```

## 🧪 Testing

Run the test suite:
```bash
pytest tests/
```

Run with coverage:
```bash
pytest tests/ --cov=src --cov-report=html
```

## 🔧 Configuration

### Environment Variables
- `HOST` - Server host (default: 0.0.0.0)
- `PORT` - Server port (default: 8000)
- `LOG_LEVEL` - Logging level (default: INFO)

### Data Files
The server reads from JSON files in the `data/` directory:
- `customers.json` - Customer records with id, name, country, joinedAt
- `orders.json` - Order records with id, customerId, customerName, date, amount

## 🤝 Integration

### LLM Client Example
This repository includes an example LLM client (`llm_client/`) that demonstrates how to integrate with the MCP server using Mistral AI. The client:
- Connects to the MCP server
- Uses Mistral AI for natural language processing
- Automatically calls appropriate MCP tools based on user questions
- Returns AI-generated answers with real data

### Using with Other AI Frameworks
The server is compatible with any system that supports the Model Context Protocol, including:
- Claude Desktop
- Custom AI applications
- Other MCP-compatible frameworks

## 📚 Documentation

- [Setup Guide](SETUP.md) - Detailed setup and usage instructions
- [Architecture](ARCHITECTURE.md) - Technical architecture and design decisions
- [API Documentation](http://localhost:8000/docs) - Interactive API docs (when server is running)

## 🛡️ Error Handling

The server provides comprehensive error handling:
- **400 Bad Request** - Invalid input parameters
- **404 Not Found** - Unknown tool names
- **500 Internal Server Error** - Server-side errors

All errors follow the MCP protocol format with detailed error messages.

## 🔄 Development

### Adding New Tools
1. Define the tool schema in `src/tools/mcp_tools.py`
2. Implement the tool logic
3. Add input validation using Pydantic models
4. Update the tool definitions list
5. Add comprehensive tests

### Code Style
- Follow PEP 8 guidelines
- Use type hints throughout
- Add docstrings for all public methods
- Maintain test coverage above 80%