# Digikala MCP Server

A Model Context Protocol (MCP) server for intelligent product discovery on Digikala, Iran's largest e-commerce platform.

## 🎯 Key Features

- **Intelligent Discovery Workflow**: Iterative search refinement with query optimization
- **Bilingual Search**: Automatic Persian (Farsi) and English query support
- **Simplified Results**: Returns only marketable products with clean, structured data
- **Smart Ratings**: Star ratings (0-5) only shown when statistically significant (10+ reviews)
- **Comprehensive Tools**: Search, details, recommendations, and AI-powered semantic search

## 💰 Currency Handling

**All price inputs and outputs use TOOMAN currency** (Iranian common currency).

- **User-facing:** All price parameters accept **Toomans**
- **API conversion:** Automatically converts to Rials (1 Tooman = 10 Rials) internally
- **Dual output:** Product prices returned in **both Tooman and Rial** for transparency

**Example:**
```python
# Input: Category ID and keyword (from get_optimized_keywords_and_categories), Price in Toomans
search_products(category_id=22, keyword="laptop", price_min_tooman=5000000, price_max_tooman=20000000)

# Output: Both currencies (simplified, parsed)
{
  "id": 12345,
  "title_fa": "لپ تاپ ایسوس",
  "selling_price_tooman": 1525000,  # 1.525M Toomans
  "selling_price_rial": 15250000,   # 15.25M Rials
  "rating_stars": 4.3,               # Out of 5 (only if 10+ reviews)
  "rating_count": 156
}
```

## 🔍 Discovery Workflow

This server implements an intelligent discovery workflow:

1. **Query Optimization**: Use `get_optimized_keywords_and_categories` with both Persian and English queries
2. **Iterative Search**: Execute `search_products` with category_id and keyword pairs from step 1
3. **Refine Results**: Adjust sorting, pagination, or filters based on results
4. **Deep Dive**: Use `get_product_details` for promising candidates
5. **Expand Search**: Use `get_product_recommendations` for similar products
6. **Visual Search**: Use `search_text_lenz` for clothing/accessories with descriptive queries

## 🛠️ Available Tools

### 1. get_optimized_keywords_and_categories
**Query optimization and category discovery**

- **Purpose**: Get optimized search keywords and relevant category IDs
- **When to use**: ALWAYS call this BEFORE search_products
- **Bilingual**: Call with BOTH Persian (Farsi) and English queries separately
- **Parameters**:
  - `query` (string): Single word query (e.g., 'laptop', 'phone', 'shoe')
- **Returns**: Optimized keywords, category IDs, and codes

**Example:**
```python
# Persian query (single word)
result_fa = get_optimized_keywords_and_categories("لپتاپ")
# English query (single word)
result_en = get_optimized_keywords_and_categories("laptop")

# Returns keyword-category pairs like:
# {"optimized_queries": ["laptop", "gaming laptop"], "categories": [{"id": 22, ...}]}

# Use these keyword-category pairs in search_products
```

---

### 2. search_products
**Core product search with filtering (Uses Search API V2)**

- **Purpose**: Search products within a specific category with advanced filters and sorting
- **Returns**: 20 simplified, marketable products per page
- **Critical**: Call `get_optimized_keywords_and_categories` FIRST to get category_id
- **Required**: Both `category_id` and `keyword` (from step 1 keyword-category pairs)
- **Parameters**:
  - `category_id` (int): **REQUIRED** - Category ID from get_optimized_keywords_and_categories
  - `keyword` (string): **REQUIRED** - Search keyword from get_optimized_keywords_and_categories
  - `page` (int): Page number (default: 1)
  - `sort` (int): Sort order (default: 1)
    - 1: Relevance (default)
    - 2: Price Low to High
    - 3: Price High to Low
    - 4: Newest
    - 5: Best Selling
    - 6: Most Viewed
    - 7: Highest Rated
  - `price_min_tooman` (int): Minimum price in Toomans
  - `price_max_tooman` (int): Maximum price in Toomans
  - `discount_min` (int): Minimum discount %
  - `discount_max` (int): Maximum discount %
  - `colors` (list[int]): Color filter IDs

**Returns**: Simplified product list with:
- `id`, `title_fa`, `title_en`, `url`
- `selling_price_tooman`, `selling_price_rial`
- `rating_stars` (0-5, only if 10+ reviews, otherwise None)
- `rating_count`, `brand`, `category`
- `discount_percent`, `is_incredible`, `is_digiplus_jet_eligible`

---

### 3. get_product_details
**Comprehensive product information**

- **Purpose**: Deep dive into specific products
- **When to use**: After finding promising candidates in search results
- **Parameters**:
  - `product_id` (int): Product ID from search results
- **Returns**: Parsed product details including:
  - Basic info (title, category, brand, URL)
  - Pricing (with Tooman/Rial)
  - Star ratings (0-5, if 10+ reviews)
  - Expert review description
  - Specifications (title, values)
  - Buy suggestion (count, percent)
  - Customer feedback (recommended %, advantages, disadvantages)
  - Available variants and price range

---

### 4. get_product_recommendations
**Similar products and alternatives**

- **Purpose**: Find similar/related products
- **When to use**: When a product is close but not exact match
- **Parameters**:
  - `product_id` (int): Reference product ID
  - `offset` (int, optional): Specific recommendation type
- **Returns**: Simplified product list with:
  - Available recommendation tabs (similar products, related categories)
  - Filtered marketable products only
  - Same fields as search_products

---

### 5. search_text_lenz
**AI-powered semantic search**

- **Purpose**: Visual/descriptive product search
- **Best for**: Clothing, accessories, wearables, shoes
- **Query format**: 2-3 word descriptions (e.g., "red summer dress", "black running shoes")
- **Parameters**:
  - `query` (string): Visual/descriptive query
  - `page` (int): Page number (default: 1)
- **Returns**: Simplified product list plus:
  - `is_text_lenz_eligible`: Whether Text-Lenz was used
  - `related_searches`: Alternative search suggestions
  - Pagination metadata

## Installation

```bash
# Install dependencies
uv sync

# Or add to existing project
uv add "mcp[cli]" httpx
```

## Usage

### Running the Server

#### STDIO Transport (for Claude Desktop, Cursor, etc.)
```bash
uv run python main.py
```

#### Testing with MCP Inspector
```bash
uv run mcp dev main.py
```

### Integration with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "digikala": {
      "command": "/path/to/local/uv",
      "args": [
          "run",
          "--directory",
          "/path/to/digikala-mcp-server",
          "python",
          "main.py"
        ]
    }
  }
}
```

## 📋 Example Usage

### Example 1: Complete Discovery Workflow
```
Find me the best gaming laptop under 50M Toomans
```

**AI Agent Workflow:**
1. Call `get_optimized_keywords_and_categories("لپتاپ")` (Farsi - single word)
2. Call `get_optimized_keywords_and_categories("laptop")` (English - single word)
3. Use keyword-category pairs from step 1 in `search_products`:
   - Example: `search_products(category_id=22, keyword="gaming laptop", price_max_tooman=50000000, sort=7)`
   - Try multiple keywords: "laptop", "gaming laptop", etc. with same category_id
   - Set `sort=7` (Highest Rated) or `sort=5` (Best Selling)
4. Review results, maybe try `sort=3` (Price High to Low) for premium options
5. Call `get_product_details(product_id)` for top 3 candidates
6. Compare specifications, ratings, and customer feedback

---

### Example 2: Iterative Search Refinement
```
I want noise-cancelling headphones for under 10M Toomans
```

**AI Agent Workflow:**
1. Optimize: `get_optimized_keywords_and_categories("هدفون")` (single word)
2. Optimize: `get_optimized_keywords_and_categories("headphone")` (single word)
3. Get keyword-category pairs and search:
   - `search_products(category_id=83, keyword="noise cancelling headphones", price_max_tooman=10000000)`
4. If too many results: Add `sort=7` (Highest Rated)
5. If too few results: Try different keywords or `sort=5` (Best Selling) or increase price
6. Review page 2-3 if needed with `page=2`
7. Get details for promising products

---

### Example 3: Visual/Descriptive Search
```
Find me a casual blue shirt for summer
```

**AI Agent Workflow:**
1. Use `search_text_lenz("blue casual shirt")` - exceptional for clothing
2. Review results and related searches
3. Try variations: `search_text_lenz("summer blue shirt")`
4. Get details for promising items
5. Use `get_product_recommendations` to explore similar styles

---

### Example 4: Finding Alternatives
```
I like this product but want to see similar options
```

**AI Agent Workflow:**
1. Get current product: `get_product_details(product_id)`
2. Get alternatives: `get_product_recommendations(product_id)`
3. Review available recommendation tabs
4. Try different offsets for category neighbors
5. Get details for interesting alternatives

## Development

### Project Structure
```
digikala-mcp-server/
├── main.py              # MCP server implementation
├── tests.py             # Comprehensive test suite
├── pyproject.toml       # Project configuration
├── uv.lock             # Dependency lock file
└── README.md           # This file
```

### Development Approach

This project follows a diffusion-inspired iterative development methodology:
- Phase 1: Simple working core (query optimization + basic search)
- Phase 2: Enhanced features (simplified outputs, bilingual support, integrated extraction)
- Phase 3: Smart filtering (marketable products, star ratings, intelligent defaults)
- Future: Error handling and production hardening

### Key Design Decisions

1. **Simplified Outputs**: All tools return parsed, clean data instead of raw API responses
2. **Marketable Products Only**: Non-available products are filtered out automatically
3. **Smart Ratings**: Star ratings (0-5) only shown when statistically significant (10+ reviews)
4. **Bilingual Support**: Emphasis on searching with both Persian and English queries
5. **Integrated Extraction**: Product extraction built into search tools, not separate
6. **Intelligent Defaults**: Always filters for available stock (has_selling_stock=1)

### Testing

#### Comprehensive Test Suite

Run the full test suite covering all refactored tools:

```bash
uv run python tests.py
```

The test suite validates:
- ✅ Query optimization (bilingual support)
- ✅ Simplified search results (marketable products only)
- ✅ Rating conversion (stars from 0-5)
- ✅ Pagination (20 items per page)
- ✅ Filtering and sorting
- ✅ Parsed product details
- ✅ Simplified recommendations
- ✅ Text-Lenz semantic search
- ✅ Currency conversion (Tooman/Rial)
- ✅ Edge cases and error handling

**Features:**
- Built-in timeout protection (30s per HTTP request)
- Proper error handling and cleanup
- Validates all tool outputs are simplified/parsed
- Exit codes for CI/CD integration

#### Direct Function Testing

Quick testing of individual functions:

```python
from main import get_optimized_keywords_and_categories, search_products, get_product_details

# Test query optimization (single word queries)
optimized = get_optimized_keywords_and_categories("لپتاپ")
print(f"Optimized keywords: {optimized['optimized_queries']}")
print(f"Categories: {optimized['categories']}")

# Extract keyword-category pair
category_id = optimized['categories'][0]['id']  # e.g., 22
keyword = optimized['categories'][0]['query']   # e.g., "laptop"

# Test search with filters (returns simplified products directly)
results = search_products(
    category_id=category_id,  # REQUIRED - from optimization step
    keyword=keyword,          # REQUIRED - from optimization step
    price_min_tooman=1000000,   # 10M Rials
    price_max_tooman=10000000,  # 100M Rials
    sort=2,  # Price Low to High
)

# Results are already simplified
for product in results['products'][:3]:
    rating = f"{product['rating_stars']}⭐" if product['rating_stars'] else "No rating"
    print(f"{product['title_fa']}: {product['selling_price_tooman']:,} Toomans - {rating}")

# Get detailed info
details = get_product_details(results['products'][0]['id'])
print(f"Specs: {len(details['specifications'])} attributes")
print(f"Customer feedback: {details.get('customer_feedback', {})}")
```

## API Documentation

This server integrates with:
- Digikala Autocomplete API v1: `https://api.digikala.com/v1/autocomplete/`
- Digikala Search API v2: `https://api.digikala.com/v2/category/{category_id}/`
- Digikala Product Details API v2: `https://api.digikala.com/v2/product/{id}/`
- Digikala Tabular Recommendations API v1: `https://api.digikala.com/v1/product/{id}/tabular-recommendation/`
- Digikala Text-Lenz Search API v1: `https://api.digikala.com/v1/search/text-lenz/`

## License

MIT

## 📊 Product Data Format

All tools return products in this simplified format:

```python
{
    "id": 12345,
    "title_fa": "عنوان فارسی محصول",
    "title_en": "Product English Title",
    "url": "/product/dkp-12345/...",
    "selling_price_rial": 15250000,
    "selling_price_tooman": 1525000,
    "rrp_price_rial": 18000000,
    "rrp_price_tooman": 1800000,
    "discount_percent": 15,
    "rating_stars": 4.3,        # 0-5 scale, None if <10 reviews
    "rating_count": 156,
    "brand": "Samsung",
    "category": "[Mobile,موبایل]",
    "is_incredible": False,
    "is_digiplus_jet_eligible": True
}
```

**Notes:**
- Only **marketable** products are returned (automatically filtered)
- `rating_stars` is `None` if `rating_count < 10` (not statistically significant)
- Both Tooman and Rial prices always included
- URL relative to digikala.com

---

## Version

0.2.0 - Refactored with simplified outputs and intelligent discovery workflow
- Integrated extraction into search tools
- Bilingual search support
- Smart rating conversion
- Parsed/simplified all outputs
- Intelligent filtering defaults