# Currency Handling in Digikala MCP Server
## Overview
The Digikala MCP Server implements automatic currency conversion between **Tooman** (user-facing) and **Rial** (API internal) currencies.
## Why Tooman?
In Iran, while the official currency is Rial, people commonly use **Tooman** for daily transactions:
- **1 Tooman = 10 Rials**
- Tooman is more intuitive and commonly used
- Simplifies price representation (fewer zeros)
## Implementation
### Conversion Functions
```python
def tooman_to_rial(tooman: int) -> int:
"""Convert Tooman to Rial (multiply by 10)"""
return tooman * 10
def rial_to_tooman(rial: int) -> int:
"""Convert Rial to Tooman (divide by 10)"""
return rial // 10
```
### Input Parameters
All price-related parameters accept **Toomans**:
| Tool | Parameters |
|------|-----------|
| `search_products` | `price_min_tooman`, `price_max_tooman` |
| `get_products_paginated` | `price_min_tooman`, `price_max_tooman` |
**Example:**
```python
# User provides prices in Toomans
search_products(
query="laptop",
price_min_tooman=500000, # 500K Toomans
price_max_tooman=2000000 # 2M Toomans
)
# Internally converted to Rials for API:
# price[min] = 5,000,000 Rials
# price[max] = 20,000,000 Rials
```
### Output Format
Product prices are returned in **both currencies** for complete transparency:
```python
ProductSummary = {
"id": 12345,
"title_fa": "لپ تاپ ایسوس",
"selling_price_rial": 15250000, # 15.25M Rials
"selling_price_tooman": 1525000, # 1.525M Toomans
"rrp_price_rial": 18000000, # 18M Rials
"rrp_price_tooman": 1800000, # 1.8M Toomans
"discount_percent": 15,
# ... other fields
}
```
## Affected Tools
### 1. search_products
- **Input:** `price_min_tooman`, `price_max_tooman`
- **Conversion:** Automatically converts to Rials before API call
- **Output:** Raw API response (Rials)
### 2. extract_products_from_search
- **Input:** Search result from `search_products`
- **Conversion:** Converts all Rial prices to Toomans
- **Output:** Products with both `_rial` and `_tooman` fields
### 3. get_products_paginated
- **Input:** `price_min_tooman`, `price_max_tooman`
- **Conversion:** Uses `search_products` internally (inherits conversion)
- **Output:** Products with dual currency format
## Testing
### Currency Conversion Tests
```python
# Test Tooman to Rial
assert tooman_to_rial(1000) == 10000
assert tooman_to_rial(5000) == 50000
# Test Rial to Tooman
assert rial_to_tooman(10000) == 1000
assert rial_to_tooman(50000) == 5000
# Test round-trip conversion
assert rial_to_tooman(tooman_to_rial(12345)) == 12345
```
### Integration Tests
- ✅ Price filter tests with Tooman inputs
- ✅ Product extraction with dual currency output
- ✅ Pagination with Tooman filters
- ✅ Combined filters with Tooman prices
- ✅ Currency conversion validation in all outputs
## Usage Examples
### Example 1: Search with Price Range
```python
# Find laptops between 500K-2M Toomans
results = search_products(
query="laptop",
price_min_tooman=500000,
price_max_tooman=2000000,
has_selling_stock=1
)
# Extract with dual currency
products = extract_products_from_search(results)
for product in products:
print(f"{product['title_fa']}")
print(f" Price: {product['selling_price_tooman']:,} Toomans")
print(f" ({product['selling_price_rial']:,} Rials)")
```
### Example 2: Budget Shopping
```python
# Find all products under 50K Toomans
budget_items = search_products(
query="کتاب",
price_max_tooman=50000, # 500K Rials
sort=2 # Sort by price (low to high)
)
products = extract_products_from_search(budget_items)
```
### Example 3: Price Comparison
```python
products = get_products_paginated(
query="headphones",
price_min_tooman=100000,
price_max_tooman=500000,
page=1
)
for product in products['products']:
original = product['rrp_price_tooman']
current = product['selling_price_tooman']
savings = original - current
print(f"{product['title_fa']}")
print(f" Original: {original:,} T")
print(f" Current: {current:,} T")
print(f" You save: {savings:,} T ({product['discount_percent']}%)")
```
## Benefits
1. **User-Friendly:** Prices in commonly-used Tooman currency
2. **Transparent:** Both Rial and Tooman provided in outputs
3. **Automatic:** No manual conversion needed by users
4. **Consistent:** All price parameters use same currency
5. **Tested:** Comprehensive test coverage ensures accuracy
## Migration from Old API
If you were using the old parameter names:
```python
# Old (Rial-based)
search_products(
query="laptop",
price_min=5000000, # Rials
price_max=15000000 # Rials
)
# New (Tooman-based)
search_products(
query="laptop",
price_min_tooman=500000, # Toomans
price_max_tooman=1500000 # Toomans
)
```
## API Compatibility
The server maintains full compatibility with Digikala's API:
- **Input conversion:** Tooman → Rial before API call
- **Output enrichment:** Rial → Tooman added to results
- **No API changes:** Works with existing Digikala API endpoints
## Performance
- **Minimal overhead:** Simple integer arithmetic (multiply/divide by 10)
- **No precision loss:** Integer division ensures accurate conversion
- **Zero latency impact:** Conversion happens in-memory
## Conclusion
The currency handling system provides a seamless experience for users while maintaining full compatibility with Digikala's Rial-based API. Users work with intuitive Tooman values, and the server handles all conversion automatically.
