# Magento MCP Server

A Model Context Protocol (MCP) server that provides dynamic access to Magento e-commerce data for ChatGPT and other AI assistants. This server enables natural language queries about your Magento store's catalog, sales, and customer data.

## Features

### 🛍️ Catalog Analysis
- **Dynamic Product Queries**: Ask questions like "How many products don't have images?" or "What's the average price of simple products?"
- **Category Insights**: Analyze category hierarchies, find categories with low product counts
- **Flexible Filtering**: Filter products by any field (status, type, price, dates, custom attributes)

### 📊 Sales Analytics
- **Order Analysis**: Get insights on average order value, sales by day of week, monthly trends
- **Product Performance**: Find top-selling products, analyze sales by time periods
- **Revenue Metrics**: Calculate revenue distributions, customer purchase patterns

### 👥 Customer Intelligence
- **Behavior Analysis**: Segment customers by value, frequency, recency
- **Fraud Detection**: Identify suspicious email patterns and potential fraud indicators
- **Target Marketing**: Find high-value customers, at-risk customers, or customers matching specific criteria

## Installation

1. **Clone and Install Dependencies**
```bash
cd /path/to/magento-mcp-server
npm install
```

2. **Configure Environment**
```bash
cp .env.example .env
```

Edit `.env` with your Magento credentials:
```env
MAGENTO_BASE_URL=https://your-magento-store.com
MAGENTO_ACCESS_TOKEN=your_admin_access_token_here
RATE_LIMIT=10
```

3. **Build the Project**
```bash
npm run build
```

## Getting Magento Access Token

1. **Log into Magento Admin Panel**
2. **Navigate to System > Extensions > Integrations**
3. **Create New Integration**:
   - Name: "MCP Server Integration"
   - Your Password: [your admin password]
   - Resources: Select "All" or specific resources you need
4. **Activate the Integration** and copy the **Access Token**

## Usage with ChatGPT

### 1. Add to ChatGPT Configuration

Add this to your ChatGPT MCP configuration file (usually `~/.config/chatgpt/mcp.json`):

```json
{
  "mcpServers": {
    "magento": {
      "command": "node",
      "args": ["/path/to/magento-mcp-server/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

### 2. Start Using Natural Language Queries

Once connected, you can ask ChatGPT questions like:

#### Catalog Questions
- "How many products are there without any images?"
- "What's the price range of all active products?"
- "Show me categories with less than 20 products"
- "How many simple products vs configurable products do I have?"

#### Sales Questions
- "What's my average order value this year?"
- "Which day of the week has the most orders?"
- "What are my top 10 selling products in July and August?"
- "Show me monthly revenue trends for 2024"

#### Customer Questions
- "How many customers have suspicious email patterns?"
- "Who are my most valuable customers?"
- "Which customers haven't ordered in over 6 months?"
- "Find customers with lifetime value over $1000"

## Available Tools

The server provides these dynamic tools that ChatGPT can use:

### Catalog Tools
- `get_all_products` - Retrieve products with filtering
- `get_all_categories` - Get category hierarchy
- `analyze_products` - Custom product analysis with grouping and metrics
- `analyze_categories` - Custom category analysis

### Sales Tools
- `get_all_orders` - Retrieve orders with filtering
- `analyze_orders` - Custom order analysis with time grouping
- `analyze_product_sales` - Product sales performance analysis

### Customer Tools
- `get_all_customers` - Retrieve customers with filtering
- `analyze_customers` - Custom customer analysis
- `analyze_customer_behavior` - Customer segmentation and behavior analysis
- `find_target_customers` - Find customers matching specific criteria

## Example Queries and How They Work

### "How many products don't have images?"
ChatGPT will use `analyze_products` with `metrics: ['without_images']` to get this information.

### "What's my average order value this month?"
ChatGPT will use `analyze_orders` with date filters and calculate the average from the results.

### "Which customers should I call to congratulate for being valuable?"
ChatGPT will use `find_target_customers` with `minLifetimeValue` and other criteria to identify VIP customers.

## Development

### Running in Development Mode
```bash
npm run dev
```

### Building
```bash
npm run build
```

### Project Structure
```
src/
├── index.ts              # Main MCP server entry point
├── config.ts             # Environment configuration
├── magento-client.ts     # Magento API client
└── tools/
    ├── catalog-tools.ts  # Product and category analysis
    ├── sales-tools.ts    # Order and sales analysis
    └── customer-tools.ts # Customer analysis
```

## Security Considerations

- **API Token Security**: Never commit your `.env` file. The access token has admin privileges.
- **Rate Limiting**: The server includes rate limiting to prevent API abuse.
- **Network Security**: Ensure your Magento instance is properly secured with HTTPS.

## Troubleshooting

### Common Issues

1. **"Configuration validation failed"**
   - Check your `.env` file has all required variables
   - Verify your Magento URL is correct and accessible

2. **"Failed to get products/orders/customers"**
   - Verify your access token has the required permissions
   - Check if your Magento API is accessible
   - Ensure rate limits aren't being exceeded

3. **"Connection refused"**
   - Verify your Magento base URL is correct
   - Check if your server can reach the Magento instance

### Debug Mode
Set `NODE_ENV=development` for more detailed error messages.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Review Magento API documentation
3. Create an issue in the repository

---

**Note**: This server provides read-only access to your Magento data. It does not modify any store data, only retrieves and analyzes it for insights.