klydo-mcp 0.1.3__py3-none-any.whl

klydo/__init__.py

@@ -0,0 +1,8 @@
+"""
+Klydo MCP Server - Fashion discovery for Indian Gen Z.
+
+A Model Context Protocol server that enables AI assistants
+to search and discover fashion products from Indian e-commerce sites.
+"""
+
+__version__ = "0.1.0"

klydo/config.py

@@ -0,0 +1,47 @@
+"""
+Application configuration using Pydantic Settings.
+
+All settings can be overridden via environment variables
+with the KLYDO_ prefix.
+"""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """
+    Application settings.
+
+    Loaded from environment variables or .env file.
+    All env vars should be prefixed with KLYDO_.
+
+    Example:
+        KLYDO_DEBUG=true
+        KLYDO_DEFAULT_SCRAPER=myntra
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="KLYDO_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # Scraper settings
+    default_scraper: str = "myntra"
+    request_timeout: int = 30
+    cache_ttl: int = 3600  # 1 hour
+
+    # Rate limiting (be nice to servers)
+    requests_per_minute: int = 30
+
+    # Klydo brand API auth
+    klydo_api_token: str | None = None
+    klydo_session_id: str | None = None
+
+    # Debug mode
+    debug: bool = False
+
+
+# Singleton instance
+settings = Settings()

klydo/logging.py

@@ -0,0 +1,141 @@
+"""
+Logging configuration using Loguru.
+
+Provides structured, human-readable logging for the Klydo MCP server.
+Logs are essential for tracking requests, debugging issues, and monitoring
+the server in production.
+
+Usage:
+    from klydo.logging import logger
+
+    logger.info("Search request", query="black dress", limit=10)
+    logger.debug("Cache hit", key="search:dress")
+    logger.error("API error", exc_info=True)
+"""
+
+import sys
+from typing import Any
+
+from loguru import logger
+
+from klydo.config import settings
+
+# Remove default handler
+logger.remove()
+
+# Configure log format based on debug mode
+if settings.debug:
+    # Detailed format for development
+    log_format = (
+        "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+        "<level>{level: <8}</level> | "
+        "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | "
+        "<level>{message}</level>"
+    )
+    log_level = "DEBUG"
+else:
+    # Cleaner format for production
+    log_format = (
+        "{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function} | {message}"
+    )
+    log_level = "INFO"
+
+# Add stdout handler
+logger.add(
+    sys.stderr,
+    format=log_format,
+    level=log_level,
+    colorize=True,
+    backtrace=settings.debug,
+    diagnose=settings.debug,
+)
+
+
+def log_request(
+    action: str,
+    **kwargs: Any,
+) -> None:
+    """
+    Log an incoming MCP tool request.
+
+    Args:
+        action: The action being performed (e.g., "search", "get_product")
+        **kwargs: Additional context to log
+    """
+    logger.info(f"Request: {action}", **kwargs)
+
+
+def log_response(
+    action: str,
+    duration_ms: float,
+    result_count: int | None = None,
+    **kwargs: Any,
+) -> None:
+    """
+    Log a completed MCP tool response.
+
+    Args:
+        action: The action that was performed
+        duration_ms: Time taken in milliseconds
+        result_count: Number of results returned (if applicable)
+        **kwargs: Additional context to log
+    """
+    msg = f"Response: {action} completed in {duration_ms:.0f}ms"
+    if result_count is not None:
+        msg += f" ({result_count} results)"
+    logger.info(msg, **kwargs)
+
+
+def log_cache_hit(key: str) -> None:
+    """Log a cache hit."""
+    logger.debug(f"Cache HIT: {key}")
+
+
+def log_cache_miss(key: str) -> None:
+    """Log a cache miss."""
+    logger.debug(f"Cache MISS: {key}")
+
+
+def log_api_call(
+    source: str,
+    endpoint: str,
+    method: str = "GET",
+) -> None:
+    """Log an outgoing API call."""
+    logger.debug(f"API call: {method} {source} {endpoint}")
+
+
+def log_api_error(
+    source: str,
+    endpoint: str,
+    error: str,
+    status_code: int | None = None,
+) -> None:
+    """Log an API error."""
+    msg = f"API error: {source} {endpoint}"
+    if status_code:
+        msg += f" (HTTP {status_code})"
+    msg += f" - {error}"
+    logger.warning(msg)
+
+
+def log_scraper_error(
+    scraper: str,
+    operation: str,
+    error: Exception,
+) -> None:
+    """Log a scraper error with exception details."""
+    logger.error(f"Scraper error: {scraper}.{operation} - {error}")
+
+
+# Export logger and helper functions
+__all__ = [
+    "logger",
+    "log_request",
+    "log_response",
+    "log_cache_hit",
+    "log_cache_miss",
+    "log_api_call",
+    "log_api_error",
+    "log_scraper_error",
+]

klydo/models/__init__.py

@@ -0,0 +1,19 @@
+"""
+Domain models for Klydo MCP Server.
+
+All Pydantic models representing fashion products and related entities.
+"""
+
+from klydo.models.product import (
+    Price,
+    Product,
+    ProductImage,
+    ProductSummary,
+)
+
+__all__ = [
+    "Price",
+    "Product",
+    "ProductImage",
+    "ProductSummary",
+]

klydo/models/product.py

@@ -0,0 +1,107 @@
+"""
+Product models for fashion e-commerce.
+
+These models define the structure of product data returned
+by scrapers and exposed through MCP tools.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+from pydantic import BaseModel, Field, HttpUrl
+
+
+class ProductImage(BaseModel):
+    """
+    Product image with URL and alt text.
+
+    Attributes:
+        url: Direct URL to the image
+        alt: Alt text for accessibility
+    """
+
+    url: HttpUrl
+    alt: str = ""
+
+
+class Price(BaseModel):
+    """
+    Price with optional discount information.
+
+    Attributes:
+        current: Current selling price
+        original: Original price before discount (if applicable)
+        currency: Currency code (default INR)
+        discount_percent: Discount percentage (if applicable)
+    """
+
+    current: Decimal
+    original: Decimal | None = None
+    currency: str = "INR"
+    discount_percent: int | None = None
+
+    @property
+    def has_discount(self) -> bool:
+        """Check if product is discounted."""
+        return self.original is not None and self.original > self.current
+
+
+class ProductSummary(BaseModel):
+    """
+    Lightweight product for search results.
+
+    Contains enough info to display in a list without
+    fetching full product details.
+
+    Attributes:
+        id: Unique product identifier (from source site)
+        name: Product name/title
+        brand: Brand name
+        price: Price information
+        image_url: Primary product image URL
+        category: Product category
+        source: Scraper source name (e.g., 'myntra')
+        url: Direct link to product page for purchase
+    """
+
+    id: str = Field(..., description="Unique product identifier")
+    name: str = Field(..., description="Product name/title")
+    brand: str = Field(..., description="Brand name")
+    price: Price = Field(..., description="Price information")
+    image_url: HttpUrl = Field(..., description="Primary product image URL")
+    category: str = Field(..., description="Product category")
+    source: str = Field(..., description="Scraper source (e.g., 'myntra')")
+    url: HttpUrl = Field(..., description="Direct link to product page")
+
+
+class Product(ProductSummary):
+    """
+    Full product details.
+
+    Extends ProductSummary with complete information including
+    all images, sizes, colors, ratings, and specifications.
+
+    Attributes:
+        description: Full product description
+        images: All product images
+        sizes: Available sizes
+        colors: Available colors
+        rating: Average rating (0-5)
+        review_count: Number of reviews
+        in_stock: Whether product is in stock
+        specifications: Additional product specifications
+    """
+
+    description: str = Field(..., description="Full product description")
+    images: list[ProductImage] = Field(
+        default_factory=list, description="All product images"
+    )
+    sizes: list[str] = Field(default_factory=list, description="Available sizes")
+    colors: list[str] = Field(default_factory=list, description="Available colors")
+    rating: float | None = Field(None, ge=0, le=5, description="Average rating (0-5)")
+    review_count: int = Field(default=0, ge=0, description="Number of reviews")
+    in_stock: bool = Field(default=True, description="Whether product is in stock")
+    specifications: dict[str, str] = Field(
+        default_factory=dict, description="Additional product specifications"
+    )

klydo/scrapers/__init__.py

@@ -0,0 +1,73 @@
+"""
+Scraper layer for fashion e-commerce sites.
+
+This module provides a unified interface for scraping
+fashion products from various Indian e-commerce sites.
+
+Usage:
+    from klydo.scrapers import get_scraper
+
+    scraper = get_scraper("myntra")
+    products = await scraper.search("black dress")
+"""
+
+from klydo.scrapers.base import ScraperProtocol
+
+# Registry of available scrapers
+# Import here to avoid circular imports
+_SCRAPERS: dict[str, type[ScraperProtocol]] = {}
+
+
+def _register_scrapers() -> None:
+    """Lazy registration of scrapers to avoid circular imports."""
+    global _SCRAPERS
+    if not _SCRAPERS:
+        from klydo.scrapers.myntra import MyntraScraper
+        from klydo.scrapers.klydo_store import KlydoStoreScraper
+
+        _SCRAPERS["myntra"] = MyntraScraper
+        _SCRAPERS["klydo"] = KlydoStoreScraper
+
+
+def get_scraper(name: str = "myntra") -> ScraperProtocol:
+    """
+    Factory function to get a scraper instance by name.
+
+    Args:
+        name: Scraper name (e.g., 'myntra', 'ajio')
+
+    Returns:
+        Scraper instance implementing ScraperProtocol
+
+    Raises:
+        ValueError: If scraper name is not registered
+
+    Example:
+        scraper = get_scraper("myntra")
+        products = await scraper.search("dress")
+    """
+    _register_scrapers()
+
+    if name not in _SCRAPERS:
+        available = list(_SCRAPERS.keys())
+        raise ValueError(f"Unknown scraper: '{name}'. Available scrapers: {available}")
+
+    return _SCRAPERS[name]()
+
+
+def list_scrapers() -> list[str]:
+    """
+    List all available scraper names.
+
+    Returns:
+        List of registered scraper names
+    """
+    _register_scrapers()
+    return list(_SCRAPERS.keys())
+
+
+__all__ = [
+    "ScraperProtocol",
+    "get_scraper",
+    "list_scrapers",
+]

klydo/scrapers/base.py

@@ -0,0 +1,107 @@
+"""
+Abstract scraper interface using Python Protocol.
+
+This defines the contract that all scrapers must implement.
+Using Protocol (structural subtyping) instead of ABC for:
+- Duck typing with type safety
+- No inheritance required
+- Easy to mock in tests
+- Clear interface for AI agents to understand
+"""
+
+from typing import Protocol, runtime_checkable
+
+from klydo.models.product import Product, ProductSummary
+
+
+@runtime_checkable
+class ScraperProtocol(Protocol):
+    """
+    Abstract scraper interface.
+
+    Implement this protocol for any fashion e-commerce site.
+    All methods are async to support non-blocking I/O.
+
+    Example implementation:
+        class MyScraper:
+            @property
+            def source_name(self) -> str:
+                return "mysite"
+
+            async def search(self, query: str, **kwargs) -> list[ProductSummary]:
+                # Implementation here
+                ...
+    """
+
+    @property
+    def source_name(self) -> str:
+        """
+        Human-readable source name.
+
+        Returns:
+            Source name (e.g., 'Myntra', 'Ajio')
+        """
+        ...
+
+    async def search(
+        self,
+        query: str,
+        *,
+        category: str | None = None,
+        gender: str | None = None,
+        min_price: int | None = None,
+        max_price: int | None = None,
+        limit: int = 20,
+    ) -> list[ProductSummary]:
+        """
+        Search for products matching criteria.
+
+        Args:
+            query: Search terms (e.g., "black dress", "nike shoes")
+            category: Filter by category (e.g., "dresses", "shoes")
+            gender: Filter by gender ("men", "women", "unisex")
+            min_price: Minimum price in INR
+            max_price: Maximum price in INR
+            limit: Maximum number of results to return
+
+        Returns:
+            List of matching products (lightweight summaries)
+        """
+        ...
+
+    async def get_product(self, product_id: str) -> Product | None:
+        """
+        Get full product details by ID.
+
+        Args:
+            product_id: Unique product identifier from search results
+
+        Returns:
+            Full product details, or None if not found
+        """
+        ...
+
+    async def get_trending(
+        self,
+        category: str | None = None,
+        limit: int = 20,
+    ) -> list[ProductSummary]:
+        """
+        Get trending/popular products.
+
+        Args:
+            category: Optional category filter
+            limit: Maximum number of results
+
+        Returns:
+            List of trending products
+        """
+        ...
+
+    async def close(self) -> None:
+        """
+        Clean up resources (HTTP clients, etc.).
+
+        Should be called when done with the scraper.
+        """
+        ...

klydo/scrapers/cache.py

@@ -0,0 +1,198 @@
+"""
+Simple file-based cache with TTL support.
+
+This provides caching for scraper responses to:
+- Reduce load on target sites
+- Improve response times
+- Work offline with cached data
+
+Can be swapped for Redis or other backends later.
+"""
+
+import hashlib
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class CacheEntry(BaseModel):
+    """
+    Cache entry with data and expiration.
+
+    Attributes:
+        data: Cached data (dict or list)
+        expires_at: When this entry expires (UTC)
+    """
+
+    data: dict[str, Any] | list[Any]
+    expires_at: datetime
+
+
+class Cache:
+    """
+    File-based cache with TTL support.
+
+    Each cache entry is stored as a JSON file with expiration metadata.
+    Expired entries are cleaned up on read.
+
+    Usage:
+        cache = Cache(namespace="myntra")
+
+        # Try cache first
+        if cached := await cache.get("search:dress"):
+            return cached
+
+        # Fetch and cache
+        result = await fetch_data()
+        await cache.set("search:dress", result, ttl=3600)
+
+    Attributes:
+        namespace: Cache namespace (used in key hashing)
+        cache_dir: Directory for cache files
+        default_ttl: Default TTL in seconds
+    """
+
+    def __init__(
+        self,
+        namespace: str,
+        cache_dir: Path | None = None,
+        default_ttl: int = 3600,
+    ):
+        """
+        Initialize cache.
+
+        Args:
+            namespace: Cache namespace (e.g., 'myntra')
+            cache_dir: Directory for cache files (default: ~/.cache/klydo)
+            default_ttl: Default TTL in seconds (default: 1 hour)
+        """
+        self.namespace = namespace
+        self.cache_dir = cache_dir or Path.home() / ".cache" / "klydo"
+        self.default_ttl = default_ttl
+
+        # Ensure cache directory exists
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _key_to_path(self, key: str) -> Path:
+        """
+        Convert cache key to file path.
+
+        Uses MD5 hash to create safe filenames.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Path to cache file
+        """
+        full_key = f"{self.namespace}:{key}"
+        hashed = hashlib.md5(full_key.encode()).hexdigest()
+        return self.cache_dir / f"{hashed}.json"
+
+    async def get(self, key: str) -> dict[str, Any] | list[Any] | None:
+        """
+        Get cached value if exists and not expired.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached data, or None if not found/expired
+        """
+        path = self._key_to_path(key)
+
+        if not path.exists():
+            return None
+
+        try:
+            raw = path.read_text(encoding="utf-8")
+            entry = CacheEntry.model_validate_json(raw)
+
+            # Check expiration
+            now = datetime.now(timezone.utc)
+            if entry.expires_at < now:
+                # Expired, clean up
+                path.unlink(missing_ok=True)
+                return None
+
+            return entry.data
+
+        except (json.JSONDecodeError, ValueError):
+            # Corrupted cache file, remove it
+            path.unlink(missing_ok=True)
+            return None
+
+    async def set(
+        self,
+        key: str,
+        value: dict[str, Any] | list[Any],
+        ttl: int | None = None,
+    ) -> None:
+        """
+        Cache a value with TTL.
+
+        Args:
+            key: Cache key
+            value: Data to cache (must be JSON-serializable)
+            ttl: TTL in seconds (default: use default_ttl)
+        """
+        ttl = ttl or self.default_ttl
+        expires_at = datetime.now(timezone.utc) + timedelta(seconds=ttl)
+
+        entry = CacheEntry(data=value, expires_at=expires_at)
+
+        path = self._key_to_path(key)
+        path.write_text(entry.model_dump_json(), encoding="utf-8")
+
+    async def invalidate(self, key: str) -> bool:
+        """
+        Remove a cached value.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            True if entry was removed, False if not found
+        """
+        path = self._key_to_path(key)
+
+        if path.exists():
+            path.unlink()
+            return True
+
+        return False
+
+    async def clear(self) -> int:
+        """
+        Clear all cached entries for this namespace.
+
+        Note: This clears ALL entries in the cache directory,
+        not just this namespace. Use with caution.
+
+        Returns:
+            Number of entries cleared
+        """
+        count = 0
+        for path in self.cache_dir.glob("*.json"):
+            path.unlink()
+            count += 1
+        return count
+
+    def cache_key(self, *parts: str) -> str:
+        """
+        Build a cache key from parts.
+
+        Args:
+            *parts: Key parts to join
+
+        Returns:
+            Cache key string
+
+        Example:
+            key = cache.cache_key("search", "dress", "women")
+            # Returns: "search:dress:women"
+        """
+        return ":".join(str(p) for p in parts if p)