# Turbify Store MCP Server

A Model Context Protocol (MCP) server for managing Turbify Store catalogs. This server provides tools to create, update, delete, and search catalog items through the Turbify Store Catalog API.

## Features

- **Item Management**: Create, update, and delete catalog items
- **Search**: Search through your catalog using keywords
- **Configuration**: View and manage store settings
- **Error Handling**: Comprehensive error handling and reporting
- **Documentation**: Built-in API documentation via MCP resources

## Installation

1. Clone this repository:

```bash
git clone <your-repo-url>
cd turbify-mcp
```

2. Initialize with uv (recommended):

```bash
uv init .
uv add fastmcp pydantic requests urllib3
```

Or install with pip:

```bash
pip install -e .
```

## Configuration

Set the following environment variables:

```bash
export TURBIFY_STORE_ID="your_store_id"
export TURBIFY_CONTRACT_TOKEN="your_contract_token"
```

Or create a `.env` file:

```env
TURBIFY_STORE_ID=your_store_id
TURBIFY_CONTRACT_TOKEN=your_contract_token
```

## Usage

### Running the Server

```bash
python src/turbify_mcp/server.py
```

Or if installed:

```bash
turbify-mcp
```

Using MCP Inspector

```bash
mcp-inspector "python run_server.py"
```

### Available Tools

#### create_catalog_item

Create a new item in your catalog:

```python
create_catalog_item(
    item_id="ITEM123",
    name="Sample Product",
    table_id="TABLE1",
    price=29.99,
    sale_price=24.99,
    orderable="yes",
    taxable="yes"
)
```

#### update_catalog_item

Update an existing item:

```python
update_catalog_item(
    item_id="ITEM123",
    name="Updated Product Name",
    price=34.99
)
```

#### delete_catalog_item

Delete an item:

```python
delete_catalog_item(item_id="ITEM123")
```

#### search_catalog_items

Search for items:

```python
search_catalog_items(
    keyword="shirt",
    start_index=1,
    end_index=50
)
```

#### get_store_config

Get current configuration:

```python
get_store_config()
```

## MCP Integration

This server can be used with any MCP-compatible client, such as:

- Claude Desktop
- Custom MCP clients
- Development tools that support MCP

### Claude Desktop Configuration

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "turbify-store": {
      "command": "python",
      "args": ["path/to/turbify-store-mcp/src/turbify_store_mcp/server.py"],
      "env": {
        "TURBIFY_STORE_ID": "your_store_id",
        "TURBIFY_CONTRACT_TOKEN": "your_contract_token"
      }
    }
  }
}
```

## API Response Format

All tools return JSON responses with the following structure:

### Success Response

```json
{
  "status": "success",
  "messages": [
    {
      "code": "SUCCESS",
      "message": "Operation completed successfully"
    }
  ],
  "items": [...],  // For search operations
  "item_ids": [...] // For some operations
}
```

### Error Response

```json
{
  "status": "error",
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Error description"
    }
  ]
}
```

## Development

### Setting up for development:

```bash
# Install with development dependencies
uv add --dev pytest pytest-asyncio black mypy

# Run tests
uv run pytest

# Format code
uv run black .

# Type checking
uv run mypy src/
```

### Project Structure

```
turbify-mcp/
├── src/
│   └── turbify_mcp/
│       ├── __init__.py
│       └── server.py
├── tests/
├── pyproject.toml
├── README.md
└── .env
```

## Requirements

- Python 3.8+
- Turbify Store API credentials
- FastMCP
- Pydantic v2
- Requests

## Limitations

- Maximum 1000 items per search query (Turbify API limit)
- Rate limiting as per Turbify Store API terms
- XML-based API (handled internally)

## 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

[Add your license information here]

## Support

For issues related to:

- This MCP server: Create an issue in this repository
- Turbify Store API: Consult Turbify Store API documentation
- MCP protocol: Check the Model Context Protocol specification