klydo-mcp 0.1.3__py3-none-any.whl

klydo/server.py

@@ -0,0 +1,219 @@
+"""
+Klydo MCP Server entry point.
+
+This module defines the MCP server and tools for fashion discovery.
+Run with: python -m klydo.server or use the `klydo` command.
+
+Usage with Claude Desktop:
+    Add to your claude_desktop_config.json:
+    {
+        "mcpServers": {
+            "klydo": {
+                "command": "uv",
+                "args": ["--directory", "/path/to/klydo-mcp-server", "run", "klydo"]
+            }
+        }
+    }
+"""
+
+import time
+
+from fastmcp import FastMCP
+
+from klydo.config import settings
+from klydo.logging import logger, log_request, log_response
+from klydo.models.product import Product, ProductSummary
+from klydo.scrapers import get_scraper
+
+# Initialize MCP server
+mcp = FastMCP(
+    name="Klydo Fashion",
+    instructions="""
+Fashion discovery assistant for Indian Gen Z (18-32 age group).
+
+You can help users:
+- Search for fashion products (clothes, shoes, accessories)
+- Get detailed product information with images
+- Find trending/popular fashion items
+
+All products include:
+- Multiple images (CDN-hosted, directly viewable)
+- Price with discounts
+- Available sizes and colors
+- Product page links (may not always be accessible)
+
+IMPORTANT - When presenting products to users:
+- ALWAYS show image URLs (image_url field) as the primary way to view products
+- Image URLs are direct CDN links that are always accessible and viewable
+- The 'url' field may contain product page links that aren't always accessible
+- For product details, display ALL images from the 'images' array so users can see products from multiple angles
+- Format image URLs as clickable/viewable links for easy access
+
+Tips for best results:
+- Use specific search terms like "black cotton dress" or "nike running shoes"
+- Filter by gender (men/women) for better results
+- Use price filters to stay within budget
+""",
+)
+
+# Get scraper instance
+_scraper = get_scraper(settings.default_scraper)
+
+# Log server startup
+logger.info(
+    f"Klydo MCP Server initialized | scraper={settings.default_scraper} | debug={settings.debug}"
+)
+
+
+@mcp.tool
+async def search_products(
+    query: str,
+    category: str | None = None,
+    gender: str | None = None,
+    min_price: int | None = None,
+    max_price: int | None = None,
+    limit: int = 10,
+) -> list[ProductSummary]:
+    """
+    Search for fashion products.
+
+    Args:
+        query: Search terms (e.g., "black dress", "nike shoes", "cotton kurta")
+        category: Filter by category (e.g., "dresses", "shoes", "tshirts", "kurtas")
+        gender: Filter by gender ("men" or "women")
+        min_price: Minimum price in INR (e.g., 500)
+        max_price: Maximum price in INR (e.g., 2000)
+        limit: Maximum number of results (default 10, max 50)
+
+    Returns:
+        List of matching products with:
+        - image_url: Direct CDN link to product image (ALWAYS show this to users to view products)
+        - price: Current price with discount information
+        - brand: Product brand name
+        - name: Product name and description
+        - url: Product page link (may not always be accessible; prefer showing image_url)
+
+        IMPORTANT: When presenting results to users, display the image_url as the primary
+        way to view products. These are direct CDN links that are always accessible.
+
+    Example:
+        Search for "floral dress" with max price 1500 for women
+    """
+    start_time = time.time()
+    log_request(
+        "search_products",
+        query=query,
+        category=category,
+        gender=gender,
+        min_price=min_price,
+        max_price=max_price,
+        limit=limit,
+    )
+
+    result = await _scraper.search(
+        query=query,
+        category=category,
+        gender=gender,
+        min_price=min_price,
+        max_price=max_price,
+        limit=min(limit, 50),
+    )
+
+    duration_ms = (time.time() - start_time) * 1000
+    log_response("search_products", duration_ms, result_count=len(result))
+
+    return result
+
+
+@mcp.tool
+async def get_product_details(product_id: str) -> Product | None:
+    """
+    Get complete product information including all images, sizes, and specifications.
+
+    Args:
+        product_id: The product ID from search results
+
+    Returns:
+        Full product details including:
+        - images: Array of ALL product images from multiple angles (CRITICAL: Display ALL these image URLs to users)
+        - image_url: Primary product image (also accessible)
+        - Available sizes and colors
+        - Rating and reviews
+        - Full description
+        - url: Product page link (may not be accessible; images are the primary viewing method)
+
+        Returns None if product not found.
+
+        CRITICAL FOR PRESENTATION:
+        When showing product details to users, display ALL image URLs from the 'images' array.
+        These are direct CDN links that are always accessible and allow users to view the
+        product from multiple angles. The image URLs should be formatted as clickable/viewable
+        links. Do NOT rely on the 'url' field for viewing products.
+
+    Example:
+        Get details for product ID "STL_HBIVEZLO78F27UG9AFRL"
+    """
+    start_time = time.time()
+    log_request("get_product_details", product_id=product_id)
+
+    result = await _scraper.get_product(product_id)
+
+    duration_ms = (time.time() - start_time) * 1000
+    log_response(
+        "get_product_details",
+        duration_ms,
+        found=result is not None,
+        product_id=product_id,
+    )
+
+    return result
+
+
+@mcp.tool
+async def get_trending(
+    category: str | None = None,
+    limit: int = 10,
+) -> list[ProductSummary]:
+    """
+    Get currently trending/popular fashion products.
+
+    Args:
+        category: Optional category filter (e.g., "dresses", "shoes", "tshirts")
+        limit: Maximum number of results (default 10, max 50)
+
+    Returns:
+        List of trending products sorted by popularity, each with:
+        - image_url: Direct CDN link to product image (ALWAYS show this to users to view products)
+        - price: Current price with discount information
+        - brand: Product brand name
+        - name: Product name and description
+        - url: Product page link (may not always be accessible; prefer showing image_url)
+
+        IMPORTANT: When presenting trending products to users, display the image_url as the
+        primary way to view products. These are direct CDN links that are always accessible.
+
+    Example:
+        Get trending shoes, or just "get trending" for all categories
+    """
+    start_time = time.time()
+    log_request("get_trending", category=category, limit=limit)
+
+    result = await _scraper.get_trending(
+        category=category,
+        limit=min(limit, 50),
+    )
+
+    duration_ms = (time.time() - start_time) * 1000
+    log_response("get_trending", duration_ms, result_count=len(result))
+
+    return result
+
+
+def main() -> None:
+    """Run the MCP server."""
+    logger.info("Starting Klydo MCP Server...")
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

klydo_mcp-0.1.3.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: klydo-mcp
+Version: 0.1.3
+Summary: Fashion discovery MCP server for Indian Gen Z
+Project-URL: Homepage, https://github.com/myselfshravan/klydo-mcp
+Project-URL: Repository, https://github.com/myselfshravan/klydo-mcp
+Project-URL: Issues, https://github.com/myselfshravan/klydo-mcp/issues
+Author-email: Shravan <shravan@klydo.in>
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,e-commerce,fashion,india,klydo,mcp,myntra,shopping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: selectolax>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Klydo MCP Server
+
+[![CI](https://github.com/myselfshravan/klydo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/myselfshravan/klydo-mcp/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/klydo-mcp.svg)](https://badge.fury.io/py/klydo-mcp)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
+
+**Fashion discovery MCP server for Indian Gen Z (18-32 age group).** 
+
+Enables AI assistants like Claude to search and discover fashion products from Indian e-commerce sites. Built by [Klydo](https://klydo.in) — a Bangalore-based startup for Gen-Z quick tech fashion commerce.
+
+## ✨ Features
+
+- 🔍 **Search Products** — Search fashion items with filters (category, gender, price range)
+- 📦 **Product Details** — Get complete product info including images, sizes, colors, ratings
+- 🔥 **Trending Products** — Discover what's popular right now
+- 🛒 **Sources** — Built-in scrapers for Myntra and the Klydo brand (klydo.in)
+- 📝 **Structured Logging** — Debug-friendly logs with Loguru
+- ⚡ **Fast & Cached** — In-memory caching for quick responses
+
+## 🚀 Quick Start
+
+### Installation
+
+#### Option 1: Install from PyPI (Recommended)
+
+```bash
+# Using pip
+pip install klydo-mcp
+
+# Or using pipx (isolated environment)
+pipx install klydo-mcp
+
+# Or using uvx (no installation needed)
+uvx klydo-mcp
+```
+
+#### Option 2: Install from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/myselfshravan/klydo-mcp.git
+cd klydo-mcp
+
+# Install dependencies with uv
+uv sync
+```
+
+### Usage with Claude Desktop
+
+#### If installed via PyPI (pip/pipx)
+
+Add to your Claude Desktop configuration:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "klydo": {
+      "command": "klydo"
+    }
+  }
+}
+```
+
+#### If using uvx (recommended for easy updates)
+
+```json
+{
+  "mcpServers": {
+    "klydo": {
+      "command": "uvx",
+      "args": ["klydo-mcp"]
+    }
+  }
+}
+```
+
+#### If installed from source
+
+```json
+{
+  "mcpServers": {
+    "klydo": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/klydo-mcp", "run", "klydo"]
+    }
+  }
+}
+```
+
+Then restart Claude Desktop.
+
+### Run Standalone
+
+```bash
+uv run klydo
+```
+
+## 🛠️ MCP Tools
+
+### `search_products`
+
+Search for fashion products.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | ✅ | Search terms (e.g., "black dress", "nike shoes") |
+| `category` | string | ❌ | Filter by category (e.g., "dresses", "shoes") |
+| `gender` | string | ❌ | Filter by gender ("men" or "women") |
+| `min_price` | int | ❌ | Minimum price in INR |
+| `max_price` | int | ❌ | Maximum price in INR |
+| `limit` | int | ❌ | Max results (default 10, max 50) |
+
+### `get_product_details`
+
+Get complete product information.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `product_id` | string | ✅ | Product ID from search results |
+
+**Returns:** Full product details including all images, sizes, colors, ratings, and purchase link.
+
+### `get_trending`
+
+Get currently trending/popular fashion products.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `category` | string | ❌ | Category filter |
+| `limit` | int | ❌ | Max results (default 10, max 50) |
+
+## ⚙️ Configuration
+
+Copy `.env.example` to `.env` and customize:
+
+```bash
+# Default scraper: "klydo" or "myntra"
+KLYDO_DEFAULT_SCRAPER=klydo
+
+# Request settings
+KLYDO_REQUEST_TIMEOUT=30
+KLYDO_CACHE_TTL=3600
+
+# Debug mode (set to false in production)
+KLYDO_DEBUG=false
+
+# API token for klydo.in scraper (required for Klydo scraper)
+KLYDO_KLYDO_API_TOKEN=your-token
+```
+
+## 📁 Project Structure
+
+```text
+klydo-mcp/
+├── src/klydo/
+│   ├── __init__.py
+│   ├── server.py          # MCP server entry point
+│   ├── config.py          # Configuration (Pydantic Settings)
+│   ├── logging.py         # Loguru configuration
+│   ├── models/
+│   │   └── product.py     # Product, Price models
+│   └── scrapers/
+│       ├── base.py        # Scraper protocol (interface)
+│       ├── cache.py       # In-memory cache with TTL
+│       ├── klydo_store.py # Klydo.in scraper
+│       └── myntra.py      # Myntra scraper
+├── tests/                 # Test suite
+├── .github/workflows/     # CI/CD pipelines
+├── pyproject.toml
+└── README.md
+```
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with verbose output
+uv run pytest -v
+
+# Run specific test file
+uv run pytest tests/test_models.py
+```
+
+## 🔧 Development
+
+```bash
+# Install dev dependencies
+uv sync --dev
+
+# Run linting
+uv run ruff check src/
+
+# Format code
+uv run ruff format src/
+
+# Run the server locally
+uv run klydo
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 🔐 Security
+
+For security issues, please see our [Security Policy](SECURITY.md).
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+## 🏢 About Klydo
+
+[Klydo](https://klydo.in) is a Bangalore-based startup building quick tech fashion commerce for Gen-Z. This MCP server is part of our mission to make fashion discovery seamless across AI interfaces.
+
+---
+
+**Made with ❤️ in Bangalore, India**

klydo_mcp-0.1.3.dist-info/RECORD

@@ -0,0 +1,16 @@
+klydo/__init__.py,sha256=3OQmIe621dZH9ib_w4dag9FAmQ2eQzHcwUDFWD7ZDdo,216
+klydo/config.py,sha256=t0x9dq2zlZ9PVtzR4qURwNMQmU_wofOZtUJdqm8NMRw,1012
+klydo/logging.py,sha256=ZLJT_be3KDn_AvZXbf3T1VUL9a0f_N7fHpX_gvrPoIk,3270
+klydo/server.py,sha256=Y80V0iu0tED1NhF--5JAGJ1U9o1MQtqsrAp-MDRaOUc,6969
+klydo/models/__init__.py,sha256=q-Nz-bVADv_6xsZlug3bnhRGQ3GPH4PH_ozDhEUo92g,302
+klydo/models/product.py,sha256=MsnctocltK5w4H8qQNs7aTkaQ11U82dg8r9QFcbssl0,3438
+klydo/scrapers/__init__.py,sha256=73ZpqVQpA1RJdafGP2fqi81IdLm3X2gb_HTABdwGXTw,1765
+klydo/scrapers/base.py,sha256=xuECczHL_Euu028YShv4hPzV_9Nf9B3d_0RLrH75MUw,2753
+klydo/scrapers/cache.py,sha256=QbZQ3w9VnK4XmU4rk7KN-Y2-ed8Ci8iC4qF2wLjdtmY,5037
+klydo/scrapers/klydo_store.py,sha256=a1nGgt7pDf-pkRKCiSS5BwA-CgnGIp0PMDNfpgYD-FI,16656
+klydo/scrapers/myntra.py,sha256=D_sUjaWccLrqpnPMVNYYQ8tbrUWsk6ZeejVLeIOM1pk,24576
+klydo_mcp-0.1.3.dist-info/METADATA,sha256=quKbsRWnyHT7OO__jDiV9JO0hALM-sfFK8W37oI1zh8,7302
+klydo_mcp-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+klydo_mcp-0.1.3.dist-info/entry_points.txt,sha256=gD6x0O0Lcmmpqn60HoCDKXBrLz-NTY883ve_LEOU2RI,44
+klydo_mcp-0.1.3.dist-info/licenses/LICENSE,sha256=CJasrlXAk_f3YoFAqXpD1W6pnRw-SeKvXR-bqySdz1I,1086
+klydo_mcp-0.1.3.dist-info/RECORD,,

klydo_mcp-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

klydo_mcp-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+klydo = klydo.server:main

klydo_mcp-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Klydo MCP Server Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.