klydo-mcp 0.1.3__tar.gz

klydo_mcp-0.1.3/.env.example

@@ -0,0 +1,22 @@
+# Klydo MCP Server Configuration
+# Copy this file to .env and customize as needed
+
+# Default scraper to use
+KLYDO_DEFAULT_SCRAPER=klydo
+
+# Request timeout in seconds
+KLYDO_REQUEST_TIMEOUT=30
+
+# Cache TTL in seconds (how long to cache scraped data)
+KLYDO_CACHE_TTL=3600
+
+# Rate limiting (requests per minute to be nice to servers)
+KLYDO_REQUESTS_PER_MINUTE=30
+
+# Klydo brand API auth (used by the klydo.in scraper)
+# Leave blank to fall back to the baked-in public token, or override with your own.
+# KLYDO_KLYDO_API_TOKEN=
+# KLYDO_KLYDO_SESSION_ID=
+
+# Debug mode (set to true for verbose logging)
+KLYDO_DEBUG=false

klydo_mcp-0.1.3/.env.production.example

@@ -0,0 +1,69 @@
+# Klydo MCP Server - Production Configuration
+# ============================================
+# Copy this file to .env and configure for your production environment.
+# 
+# SECURITY WARNING: Never commit .env files with real credentials to version control!
+
+# =============================================================================
+# SCRAPER SETTINGS
+# =============================================================================
+
+# Default scraper to use: "klydo" (Klydo Store) or "myntra"
+KLYDO_DEFAULT_SCRAPER=klydo
+
+# Request timeout in seconds
+KLYDO_REQUEST_TIMEOUT=30
+
+# Cache TTL in seconds (how long to cache scraped data)
+# Recommended: 3600 (1 hour) for production to reduce API load
+KLYDO_CACHE_TTL=3600
+
+# Rate limiting (requests per minute to be nice to servers)
+KLYDO_REQUESTS_PER_MINUTE=30
+
+# =============================================================================
+# KLYDO API AUTHENTICATION
+# =============================================================================
+# 
+# IMPORTANT: The Klydo store scraper requires an API token to function.
+# This token must be obtained from the Klydo API team.
+#
+# For production deployments:
+# 1. Request an API token from the Klydo team
+# 2. Set it below (never commit the actual token!)
+# 3. Consider using a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)
+
+# API token for klydo.in scraper (REQUIRED for Klydo scraper)
+KLYDO_KLYDO_API_TOKEN=
+
+# Optional: Custom session ID (auto-generated if not set)
+# KLYDO_KLYDO_SESSION_ID=
+
+# =============================================================================
+# DEBUG & LOGGING
+# =============================================================================
+
+# Debug mode - set to false in production!
+# When true: Enables verbose logging, full stack traces
+# When false: Only INFO level logs, cleaner output
+KLYDO_DEBUG=false
+
+# =============================================================================
+# DEPLOYMENT NOTES
+# =============================================================================
+#
+# For containerized deployments (Docker/Kubernetes):
+# - Pass environment variables directly rather than using .env files
+# - Use secrets management for sensitive values like KLYDO_KLYDO_API_TOKEN
+#
+# Example Docker run:
+#   docker run -e KLYDO_KLYDO_API_TOKEN=your-token klydo-mcp-server
+#
+# Example Kubernetes secret:
+#   kubectl create secret generic klydo-secrets \
+#     --from-literal=KLYDO_KLYDO_API_TOKEN=your-token
+#
+# For Claude Desktop (local usage):
+# - Copy this file to .env in the project root
+# - Fill in your API token
+# - The MCP server will automatically load the .env file

klydo_mcp-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install test dependencies
+        run: uv pip install pytest pytest-asyncio
+
+      - name: Run tests
+        run: uv run pytest -v --tb=short
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install Ruff
+        run: uv pip install ruff
+
+      - name: Run Ruff linter
+        run: uv run ruff check src/
+
+      - name: Run Ruff formatter check
+        run: uv run ruff format --check src/
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install build
+        run: uv pip install build
+
+      - name: Build package
+        run: uv run python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

klydo_mcp-0.1.3/.github/workflows/publish.yaml

@@ -0,0 +1,95 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Target PyPI (testpypi or pypi)"
+        required: true
+        default: "testpypi"
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+jobs:
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install build
+        run: uv pip install build
+
+      - name: Build package
+        run: uv run python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
+    
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/klydo-mcp
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
+    
+    environment:
+      name: pypi
+      url: https://pypi.org/p/klydo-mcp
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

klydo_mcp-0.1.3/.gitignore

@@ -0,0 +1,37 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+*.egg
+
+# Virtual environments
+.venv
+venv/
+env/
+
+# Environment variables
+.env
+
+# PyPI publishing
+.pypirc
+*.tar.gz
+*.whl
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test coverage
+.coverage
+htmlcov/
+.pytest_cache/

klydo_mcp-0.1.3/.pre-commit-config.yaml

@@ -0,0 +1,65 @@
+# Pre-commit hooks for Klydo MCP Server
+# Install with: pre-commit install
+# Run manually: pre-commit run --all-files
+
+repos:
+  # Ruff - Fast Python linter and formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      # Run the linter
+      - id: ruff
+        args: [--fix]
+      # Run the formatter
+      - id: ruff-format
+
+  # General file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Trim trailing whitespace
+      - id: trailing-whitespace
+      # Ensure files end with a newline
+      - id: end-of-file-fixer
+      # Check YAML syntax
+      - id: check-yaml
+      # Check TOML syntax
+      - id: check-toml
+      # Check JSON syntax
+      - id: check-json
+      # Check for merge conflict markers
+      - id: check-merge-conflict
+      # Check for debug statements
+      - id: debug-statements
+      # Prevent large files from being committed
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      # Check for private keys
+      - id: detect-private-key
+
+  # Security checks
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+        exclude: package.lock.json
+
+  # Type checking (optional - can be slow)
+  # - repo: https://github.com/pre-commit/mirrors-mypy
+  #   rev: v1.13.0
+  #   hooks:
+  #     - id: mypy
+  #       additional_dependencies: [pydantic, httpx]
+  #       args: [--ignore-missing-imports]
+
+# CI configuration
+ci:
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit hooks
+  autofix_prs: true
+  autoupdate_branch: 'main'
+  autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
+  autoupdate_schedule: weekly
+  skip: [detect-secrets]
+  submodules: false

klydo_mcp-0.1.3/.pypirc.example

@@ -0,0 +1,29 @@
+# PyPI Configuration Template
+# Copy this file to ~/.pypirc and update with your tokens
+#
+# SECURITY WARNING: Never commit your actual ~/.pypirc file to git!
+# This is just a template showing the structure.
+
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-YOUR_PYPI_API_TOKEN_HERE
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-YOUR_TESTPYPI_API_TOKEN_HERE
+
+# How to use:
+# 1. Copy this file to ~/.pypirc
+# 2. Replace YOUR_PYPI_API_TOKEN_HERE with your actual PyPI token
+# 3. Replace YOUR_TESTPYPI_API_TOKEN_HERE with your TestPyPI token (optional)
+# 4. Set proper permissions: chmod 600 ~/.pypirc
+#
+# Get tokens from:
+# - PyPI: https://pypi.org/manage/account/token/
+# - TestPyPI: https://test.pypi.org/manage/account/token/

klydo_mcp-0.1.3/.python-version

@@ -0,0 +1 @@
+3.13

klydo_mcp-0.1.3/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Structured logging with Loguru for better debugging and monitoring
+- Production-ready environment configuration (`.env.production.example`)
+- Comprehensive test suite with pytest
+- GitHub Actions CI/CD pipeline for testing and publishing
+- CHANGELOG.md for tracking changes
+- CONTRIBUTING.md with contribution guidelines
+- SECURITY.md with security policy
+
+### Changed
+- Removed hardcoded DEFAULT_AUTH_TOKEN for better security
+- Updated project URLs to point to official GitHub repository
+- Updated author information in pyproject.toml
+
+### Security
+- API tokens must now be provided via environment variables only
+- No hardcoded secrets in codebase
+
+## [0.1.0] - 2026-06-02
+
+### Added
+- Initial release of Klydo MCP Server
+- MCP server implementation using FastMCP
+- Klydo.in catalog API integration
+- Product search with filters (category, gender, price range)
+- Product details retrieval with images and specifications
+- Trending products discovery
+- In-memory caching for API responses
+- Pydantic models for type-safe data handling
+- Configuration via environment variables
+- Claude Desktop integration support
+
+### Features
+- `search_products` - Search for fashion products with various filters
+- `get_product_details` - Get complete product information
+- `get_trending` - Get trending/popular products
+
+### Technical
+- Python 3.11+ support
+- Async HTTP client with httpx
+- pydantic-settings for configuration management
+- Installable via pip/uv from PyPI
+
+[Unreleased]: https://github.com/myselfshravan/klydo-mcp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/myselfshravan/klydo-mcp/releases/tag/v0.1.0

klydo_mcp-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,204 @@
+# Contributing to Klydo MCP Server
+
+First off, thank you for considering contributing to Klydo MCP Server! 🎉
+
+This project is part of [Klydo](https://klydo.in), a Gen-Z quick tech fashion commerce startup based in Bangalore. We welcome contributions from the community to make this project even better.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+- [Testing](#testing)
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment. We expect all contributors to:
+
+- Be respectful and considerate in all interactions
+- Welcome newcomers and help them learn
+- Focus on what is best for the community
+- Show empathy towards other community members
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/klydo-mcp.git
+   cd klydo-mcp
+   ```
+3. **Add the upstream remote**:
+   ```bash
+   git remote add upstream https://github.com/myselfshravan/klydo-mcp.git
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.11 or higher
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Setup with uv (Recommended)
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run the server locally
+uv run klydo
+
+# Run tests
+uv run pytest
+```
+
+### Setup with pip
+
+```bash
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```
+
+### Environment Configuration
+
+1. Copy the example environment file:
+   ```bash
+   cp .env.example .env
+   ```
+2. Edit `.env` and configure as needed (API tokens, etc.)
+
+## How to Contribute
+
+### Reporting Bugs
+
+- Check if the bug has already been reported in [Issues](https://github.com/myselfshravan/klydo-mcp/issues)
+- If not, create a new issue with:
+  - Clear, descriptive title
+  - Steps to reproduce
+  - Expected vs actual behavior
+  - Python version and OS
+  - Relevant logs/error messages
+
+### Suggesting Features
+
+- Open an issue with the `enhancement` label
+- Describe the feature and its use case
+- Explain why it would benefit users
+
+### Contributing Code
+
+1. **Find an issue** to work on or create one first
+2. **Comment on the issue** to let others know you're working on it
+3. **Create a branch** from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+4. **Make your changes** following our coding standards
+5. **Write/update tests** for your changes
+6. **Run the test suite** to ensure everything passes
+7. **Commit your changes** with clear messages
+8. **Push to your fork** and create a Pull Request
+
+## Pull Request Process
+
+1. **Update documentation** if you've changed APIs or added features
+2. **Add tests** for new functionality
+3. **Ensure CI passes** - all tests and linting must pass
+4. **Request review** from maintainers
+5. **Address feedback** promptly and constructively
+
+### PR Title Format
+
+Use clear, descriptive titles:
+- `feat: Add new search filter for colors`
+- `fix: Handle empty API response gracefully`
+- `docs: Update installation instructions`
+- `test: Add tests for scraper cache`
+- `refactor: Simplify product parsing logic`
+
+## Coding Standards
+
+### Python Style
+
+- Follow [PEP 8](https://pep8.org/) style guide
+- Use type hints for all public functions
+- Maximum line length: 100 characters
+- Use descriptive variable and function names
+
+### Code Quality Tools
+
+```bash
+# Format code with Ruff
+uv run ruff format src/
+
+# Lint code with Ruff
+uv run ruff check src/
+
+# Type checking (optional)
+uv run mypy src/klydo
+```
+
+### Commit Messages
+
+- Use the present tense ("Add feature" not "Added feature")
+- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+- Keep the first line under 72 characters
+- Reference issues when relevant: "Fix #123"
+
+### Documentation
+
+- Add docstrings to all public modules, classes, and functions
+- Use Google-style docstrings
+- Update README if adding new features
+- Update CHANGELOG for notable changes
+
+## Testing
+
+### Running Tests
+
+```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
+
+# Run with coverage
+uv run pytest --cov=klydo
+```
+
+### Writing Tests
+
+- Place tests in the `tests/` directory
+- Name test files `test_*.py`
+- Use descriptive test function names
+- Use fixtures for common test data
+- Mock external API calls
+
+### Test Categories
+
+- **Unit tests**: Test individual functions/methods
+- **Integration tests**: Test component interactions
+- **Scraper tests**: Test with mocked HTTP responses
+
+## Need Help?
+
+- Create an issue with your question
+- Check existing issues and discussions
+- Review the documentation
+
+Thank you for contributing! 🚀

klydo_mcp-0.1.3/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.