# Catalog Services MCP Server

An MCP (Model Context Protocol) server for Adobe Commerce Catalog Services, providing tools to interact with product, category, and environment services via gRPC and REST APIs.

Proto Schemas from https://git.corp.adobe.com/magento/proto-schemas

## Features

This MCP server provides the following tools:

- **Product Variants**: Get product variant information (configurable product options)
- **Product Overrides**: Query product price overrides by customer group and website
- **Category Permissions**: Retrieve category permission information
- **Environment Details**: Get environment, website, and store view information

## Prerequisites

- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv) - Fast Python package installer and resolver
- Cursor IDE (or any MCP-compatible client)

## Installation

### 1. Install uv

If you don't have `uv` installed, install it first:

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv
```

### 2. Clone and Setup the Project

```bash
# Clone the repository
git clone <repository-url>
cd catalog-services-mcp

# Install dependencies using uv
uv sync
```

### 3. Configure Environment Variables

Set the required environment variables for authentication:

```bash
# Adobe Commerce Catalog Service credentials
export CATALOG_SERVICE_API_KEY="your_api_key"
export CATALOG_SERVICE_PRIVATE_KEY="your_private_key"

# New Relic credentials (if using New Relic tools)
export NEW_RELIC_API_KEY="your_new_relic_api_key"
```

### 4. Configure MCP in Cursor

Add the following configuration to your Cursor MCP settings file (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "Catalog Services": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/path/to/catalog-services-mcp",
        "run",
        "main.py"
      ]
    }
  }
}
```

**Important**: Replace `/Users/YOUR_USERNAME/path/to/catalog-services-mcp` with the actual path to your cloned repository.

### 5. Restart Cursor

After adding the configuration, restart Cursor IDE to load the MCP server.

## Usage

Once configured, you can use the Catalog Services tools in Cursor by invoking them through the MCP protocol. Available tools include:

- `get_product_variants` - Retrieve product variant information
- `get_product_overrides_by_website` - Get product price overrides for all customer groups
- `get_category_permissions` - Query category permissions
- `get_environment_details` - Get environment information
- `get_environment_store_views` - List all store views for an environment
- `find_store_view_codes` - Find store views by website/store code

## Development

### Project Structure

```
catalog-services-mcp/
├── catalog_service/          # Main service module
│   ├── generated/           # Generated protobuf files
│   ├── proto-schemas/       # Proto schema definitions
│   ├── product_service_tool.py
│   ├── product_override_service_tool.py
│   ├── variant_service_tool.py
│   ├── category_permission_service_tool.py
│   └── environment_service_tool.py
├── main.py                  # MCP server entry point
├── pyproject.toml          # Project dependencies
└── README.md
```

### Regenerating Protobuf Files

If you need to regenerate the protobuf files from the proto schemas:

```bash
cd catalog_service
./generate_protos.sh
```

## Troubleshooting

### MCP Server Not Starting

1. Check that `uv` is installed and in your PATH:
   ```bash
   which uv
   ```

2. Verify the path in `mcp.json` is correct and absolute

3. Check Cursor logs for error messages

### Authentication Errors

Ensure your environment variables are set correctly:

```bash
echo $CATALOG_SERVICE_API_KEY
echo $CATALOG_SERVICE_PRIVATE_KEY
```

### Connection Issues

- Verify network connectivity to Adobe Commerce services
- Check that you're connected to the corporate VPN if required
- Ensure firewall rules allow outbound connections

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

Internal Adobe Commerce project