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:

🔍 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:

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

Usage

Running the Server

STDIO Transport (for Claude Desktop, Cursor, etc.)

Testing with MCP Inspector

Integration with Claude Desktop

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

📋 Example Usage

Example 1: Complete Discovery Workflow

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

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

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

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

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:

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:

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:

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