# Saleor MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for Saleor. This server enables an MCP client to interact with Saleor e-commerce data including products, orders, customers, and more.

[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-Compatible-blue)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
[![Poetry](https://img.shields.io/badge/Poetry-Dependency%20Management-blue)](https://python-poetry.org)

## 🚀 Features

-**Product Management**: Query and browse Saleor products with rich formatting
## 📋 Prerequisites

### Required Software

1. **Python 3.10 or higher**
   ```bash
   python --version  # Should be 3.10+
   ```

2. **Poetry** (recommended) or pip
   ```bash
   # Install Poetry
   curl -sSL https://install.python-poetry.org | python3 -
   
   # Or via pip
   pip install poetry
   ```

3. **Claude Desktop**
   - Download from [claude.ai/desktop](https://claude.ai/desktop)

### Required Services

4. **Running Saleor Instance**
   - Local development server

## 🏪 Setting Up Saleor

You need a running Saleor instance to connect to. Choose one of these options:

### Option 1: Local Development (Recommended for Testing)

Follow the official Saleor documentation to set up a local instance:

📚 **[Saleor Developer Documentation](https://docs.saleor.io/docs/3.x/developer)**

**Quick Start with Docker:**
```bash
# Clone Saleor
git clone https://github.com/saleor/saleor-platform.git
cd saleor-platform

# Start with Docker Compose
docker-compose up -d

# Access at http://localhost:8000/graphql/
```

**Detailed Setup Guides:**
- 🐳 [Docker Setup](https://docs.saleor.io/docs/3.x/developer/installation/docker-compose)
- 🐍 [Local Python Setup](https://docs.saleor.io/docs/3.x/developer/installation)
- ☁️ [Saleor Cloud](https://cloud.saleor.io/)
## ⚡ Quick Start

### 1. Clone and Install

```bash
# Clone the repository
git clone https://github.com/yourusername/saleor-mcp-server.git
cd saleor-mcp-server

# Install dependencies
poetry install

# Or with pip
pip install -r requirements.txt
pip install -e .
```

### 2. Configure Environment

```bash
# Copy environment template
cp .env.example .env

# Edit configuration
nano .env  # or your preferred editor
```

**Required Configuration (.env):**
```env
# Saleor API Configuration
SALEOR_API_URL=http://localhost:8000/graphql/
SALEOR_EMAIL=your-email@example.com
SALEOR_PASSWORD=your-password

# Optional: Advanced Settings
LOG_LEVEL=INFO
TOKEN_REFRESH_THRESHOLD=300
SERVER_NAME=saleor
DEFAULT_PRODUCT_LIMIT=20
MAX_PRODUCT_LIMIT=100
```

### 3. Test the Connection

```bash
# Test your configuration
poetry run python scripts/test-tools.py

# Or test the server directly
TEST_MODE=true poetry run bm-mcp
```

**Expected output:**
```
🧪 Testing Saleor connection...
✅ Connection successful!
📦 Testing product query...
✅ Found 3 products
   • Product Name (ID: ...)
🎉 All tests passed!
```

### 4. Test with MCP Inspector

```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test your server
npx @modelcontextprotocol/inspector poetry run bm-mcp
```

This opens a web interface at `http://localhost:5173` where you can:
- Test the connection
- Call the `get_products` tool
- See formatted responses

## 🖥️ Claude Desktop Setup

### 1. Find your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude.desktopconfig`
- **Windows**: `%APPDATA%\Claude\claude.desktopconfig`
- **Linux**: `~/.config/Claude/claude.desktopconfig`

### 2. Add the server configuration:

**Option A: Using Poetry (Recommended)**
```json
{
  "mcpServers": {
    "saleor": {
      "command": "poetry",
      "args": ["run", "bm-mcp"],
      "cwd": "/full/path/to/saleor-mcp-server",
      "env": {
        "SALEOR_API_URL": "http://localhost:8000/graphql/",
        "SALEOR_EMAIL": "your-email@example.com",
        "SALEOR_PASSWORD": "your-password"
      }
    }
  }
}
```

**Option B: Direct Script**
```json
{
  "mcpServers": {
    "saleor": {
      "command": "/full/path/to/saleor-mcp-server/.venv/bin/bm-mcp",
      "args": []
    }
  }
}
```

### 3. Restart Claude Desktop

After updating the configuration, restart Claude Desktop completely.

## 🧪 Testing

### Command Line Testing

```bash
# Test imports and configuration
poetry run python -c "from bm_mcp.main import main; print('✅ Import successful')"

# Test with environment flag
TEST_MODE=true poetry run bm-mcp

# Test specific tools
poetry run python scripts/test-tools.py
```

### Interactive Testing

```bash
# Start MCP Inspector
npx @modelcontextprotocol/inspector poetry run bm-mcp

# Test in Claude Desktop
# Ask: "Show me products from my store"
# Ask: "Get the latest products from my Saleor instance"
```

## Usage Examples

Once configured, you can ask Claude questions like:

- **"Show me the latest products in my store"**
- **"What products do I have available?"**

### Available Tools

- **`get_products`**: Retrieve products with optional filtering
  - Parameters: `limit`, `channel`, `category_id`
  - Returns: Formatted product list with names, prices, availability

## 🛠️ Development

### Project Structure

```
saleor-mcp-server/
├── bm_mcp/
│   ├── client/         # Saleor API client
│   ├── config/         # Configuration management
│   ├── formatters/     # Data formatting
│   ├── tools/          # MCP tool implementations
│   ├── utils/          # Utilities and helpers
│   └── main.py         # Entry point
├── scripts/            # Testing and utility scripts
├── tests/              # Unit tests
├── .env.example        # Environment template
└── README.md
```

### Adding New Tools

1. Create tool class in `bm_mcp/tools/`
2. Inherit from appropriate base class
3. Register in `main.py`
4. Add tests in `tests/`

### Running Tests

```bash
# Run unit tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=bm_mcp

# Test specific functionality
poetry run python scripts/test-tools.py
```

## 🔧 Troubleshooting

### Common Issues

**Connection Errors**
```bash
# Verify Saleor is running
curl http://localhost:8000/graphql/

# Test credentials
poetry run python scripts/test-connection.py
```

**Import Errors**
```bash
# Reinstall dependencies
poetry install --sync

# Check Python version
python --version  # Should be 3.10+
```

**Claude Desktop Issues**
```bash
# Check logs
tail -f ~/Library/Logs/Claude/mcp-server-saleor.log

# Verify config syntax
cat ~/Library/Application\ Support/Claude/claude.desktopconfig | python -m json.tool
```

### Debug Mode

```bash
# Enable debug logging
LOG_LEVEL=DEBUG poetry run bm-mcp

# Test mode with verbose output
TEST_MODE=true LOG_LEVEL=DEBUG poetry run bm-mcp
```

### Getting Help

- [Saleor Documentation](https://docs.saleor.io/)
- [MCP Documentation](https://modelcontextprotocol.io/docs)
- [Report Issues](https://github.com/yourusername/saleor-mcp-server/issues)
- [Discussions](https://github.com/yourusername/saleor-mcp-server/discussions)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Anthropic](https://www.anthropic.com/) for the Model Context Protocol
- [Saleor](https://saleor.io/) for the excellent e-commerce platform
- The open-source community for inspiration and tools

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (`poetry run pytest`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

---