offers-check-marketplaces-mcp-2025


Nameoffers-check-marketplaces-mcp-2025 JSON
Version 0.1.2 PyPI version JSON
download
home_pageNone
SummaryMCP server for automated product search and price comparison across multiple marketplaces with integrated license management
upload_time2025-08-01 09:49:30
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseMIT
keywords automation e-commerce marketplace mcp price-comparison
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Offers Check Marketplaces MCP Server

[![PyPI version](https://badge.fury.io/py/offers-check-marketplaces.svg)](https://badge.fury.io/py/offers-check-marketplaces)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful MCP (Model Context Protocol) server for automated product search and price comparison across multiple marketplaces with integrated license management.

## Features

- 🔍 **Multi-marketplace Search**: Search products across multiple e-commerce platforms
- 💰 **Price Comparison**: Automated price comparison and analysis
- 📊 **Statistics & Analytics**: Comprehensive reporting and data analysis
- 🗄️ **Database Management**: SQLite-based data storage with async operations
- 🔐 **License Management**: Integrated license verification system
- 🌐 **Web Scraping**: Playwright-based web scraping capabilities
- 📈 **Excel Integration**: Import/export data from Excel files
- 🚀 **High Performance**: Async/await architecture for optimal performance

## Supported Marketplaces

- **Komus** (komus.ru) - Office supplies and stationery
- **VseInstrumenti** (vseinstrumenti.ru) - Tools and equipment
- **Ozon** (ozon.ru) - Universal marketplace
- **Wildberries** (wildberries.ru) - Consumer goods
- **OfficeMag** (officemag.ru) - Office supplies

## Installation

### From PyPI

```bash
pip install offers-check-marketplaces
```

### From Source

```bash
git clone https://github.com/yourusername/offers-check-marketplaces-mcp.git
cd offers-check-marketplaces-mcp
pip install -e .
```

## Quick Start

### 1. Basic Usage

```bash
# Run in STDIO mode (for MCP clients)
offers-check-marketplaces

# Run in SSE mode (web server)
offers-check-marketplaces --sse --host 0.0.0.0 --port 8000
```

### 2. MCP Configuration

Add to your MCP client configuration (e.g., `.cursor/mcp.json` or `.kiro/settings/mcp.json`):

```json
{
  "mcpServers": {
    "offers_check_marketplaces": {
      "command": "offers-check-marketplaces",
      "env": {
        "LICENSE_KEY": "your-license-key-here"
      }
    }
  }
}
```

### 3. Environment Variables

```bash
# Set license key
export LICENSE_KEY="your-license-key-here"

# Optional: Set custom API endpoint
export API_BASE_URL="https://your-api-endpoint.com"
```

## MCP Tools

The server provides the following MCP tools:

### Core Tools

- **`search_products`** - Search for products across marketplaces
- **`get_product_details`** - Get detailed product information and prices
- **`get_product_list`** - List all products from database
- **`get_statistics`** - Generate comprehensive statistics

### Data Management Tools

- **`save_product_prices`** - Save found prices to database
- **`update_all_prices`** - Batch update prices for multiple products

### License Management Tools

- **`check_license_status`** - Check current license status
- **`set_license_key`** - Set new license key

### Excel Tools

- **`parse_excel_file`** - Parse Excel file and return structured data
- **`get_excel_info`** - Get information about Excel file structure without reading all data
- **`export_to_excel`** - Export data to Excel file with formatting
- **`filter_excel_data`** - Filter Excel data by specified criteria
- **`transform_excel_data`** - Transform Excel data according to specified rules

## Usage Examples

### Search Products

```python
# Using MCP client
result = await mcp_client.call_tool("search_products", {
    "model_name": "Полотно техническое БЯЗЬ ОТБЕЛЕННАЯ ГОСТ"
})
```

### Get Product Details

```python
# Get detailed information about a product
result = await mcp_client.call_tool("get_product_details", {
    "product_code": 195385.0
})
```

### Generate Statistics

```python
# Get comprehensive statistics
result = await mcp_client.call_tool("get_statistics", {})
```

### Parse Excel File

```python
# Parse Excel file with specific parameters
result = await mcp_client.call_tool("parse_excel_file", {
    "file_path": "data/input.xlsx",
    "sheet_name": "Данные",
    "header_row": 0,
    "max_rows": 100
})
```

### Export Data to Excel

```python
# Export processed data to Excel with formatting
result = await mcp_client.call_tool("export_to_excel", {
    "data": processed_data,
    "file_path": "data/output.xlsx",
    "sheet_name": "Результаты",
    "apply_formatting": True,
    "auto_adjust_columns": True
})
```

### Filter Excel Data

```python
# Filter data by multiple criteria
result = await mcp_client.call_tool("filter_excel_data", {
    "data": excel_data,
    "filters": {
        "Категория": "Хозтовары и посуда",
        "Цена позиции\nМП c НДС": {
            "greater_than": 1000,
            "less_than": 5000
        }
    }
})
```

## Configuration

### License Configuration

The system requires a valid license key. You can provide it through:

1. **Environment variable**: `LICENSE_KEY=your-key`
2. **MCP configuration**: Set in the `env` section of your MCP config
3. **Configuration file**: `data/.license_config.json`

### Data Directory

The system automatically creates user data directories following OS standards:

- **Windows**: `%APPDATA%\offers-check-marketplaces\`
- **macOS**: `~/Library/Application Support/offers-check-marketplaces/`
- **Linux**: `~/.local/share/offers-check-marketplaces/` (XDG compliant)

Contains:

- SQLite database (`database/products.db`)
- License cache (`cache/.license_cache.json`)
- Excel files for import/export
- Application logs (`logs/`)

You can override the location using the `OFFERS_CHECK_DATA_DIR` environment variable.

## Development

### Setup Development Environment

```bash
git clone https://github.com/yourusername/offers-check-marketplaces-mcp.git
cd offers-check-marketplaces-mcp

# Install with development dependencies
pip install -e ".[dev]"
```

### Running Tests

```bash
# Run all tests
pytest

# Run specific test files
python test_license_integration.py
python test_mcp_license_tools.py
python test_final_integration.py
```

### Building Package

```bash
# Install build tools
pip install build twine

# Build package
python -m build

# Upload to PyPI (requires credentials)
twine upload dist/*
```

## Architecture

### Components

- **Server** (`server.py`) - Main MCP server with tool implementations
- **License Manager** (`license_manager.py`) - License verification and management
- **Database Manager** (`database_manager.py`) - SQLite database operations
- **Search Engine** (`search_engine.py`) - Multi-marketplace search coordination
- **Data Processor** (`data_processor.py`) - Excel file processing
- **Statistics Generator** (`statistics.py`) - Analytics and reporting
- **Error Handling** (`error_handling.py`) - Comprehensive error management

### Data Flow

1. **Input**: Excel files with product specifications
2. **Processing**: Search products across marketplaces
3. **Storage**: Save results to SQLite database
4. **Analysis**: Generate statistics and comparisons
5. **Output**: Updated Excel files with prices and analysis

## API Reference

### Search Products

```python
search_products(model_name: str) -> dict
```

Search for products across multiple marketplaces.

**Parameters:**

- `model_name` (str): Product model name to search for

**Returns:**

- Dictionary with search results from different marketplaces

### Get Product Details

```python
get_product_details(product_code: float) -> dict
```

Get detailed information about a specific product.

**Parameters:**

- `product_code` (float): Unique product code from database

**Returns:**

- Dictionary with product details and price analysis

## Error Handling

The system includes comprehensive error handling:

- **License Errors**: Invalid or missing license keys
- **Network Errors**: Marketplace connectivity issues
- **Database Errors**: SQLite operation failures
- **Validation Errors**: Invalid input parameters

All errors are logged and return user-friendly messages.

## Contributing

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

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- **Documentation**: [GitHub Repository](https://github.com/yourusername/offers-check-marketplaces-mcp)
- **Issues**: [Bug Tracker](https://github.com/yourusername/offers-check-marketplaces-mcp/issues)
- **License**: Contact support for license-related questions

## Changelog

### v0.1.0

- Initial release
- Multi-marketplace product search
- Price comparison and analysis
- Integrated license management
- MCP server implementation
- Excel data processing
- SQLite database storage
- Comprehensive error handling

---

Made with ❤️ for automated marketplace analysis

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "offers-check-marketplaces-mcp-2025",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": "Your Name <your.email@example.com>",
    "keywords": "automation, e-commerce, marketplace, mcp, price-comparison",
    "author": null,
    "author_email": "Your Name <your.email@example.com>",
    "download_url": "https://files.pythonhosted.org/packages/b9/50/e315f68dc926e5c41ab1f4effb014612816568a29737939517271286c736/offers_check_marketplaces_mcp_2025-0.1.2.tar.gz",
    "platform": null,
    "description": "# Offers Check Marketplaces MCP Server\n\n[![PyPI version](https://badge.fury.io/py/offers-check-marketplaces.svg)](https://badge.fury.io/py/offers-check-marketplaces)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA powerful MCP (Model Context Protocol) server for automated product search and price comparison across multiple marketplaces with integrated license management.\n\n## Features\n\n- \ud83d\udd0d **Multi-marketplace Search**: Search products across multiple e-commerce platforms\n- \ud83d\udcb0 **Price Comparison**: Automated price comparison and analysis\n- \ud83d\udcca **Statistics & Analytics**: Comprehensive reporting and data analysis\n- \ud83d\uddc4\ufe0f **Database Management**: SQLite-based data storage with async operations\n- \ud83d\udd10 **License Management**: Integrated license verification system\n- \ud83c\udf10 **Web Scraping**: Playwright-based web scraping capabilities\n- \ud83d\udcc8 **Excel Integration**: Import/export data from Excel files\n- \ud83d\ude80 **High Performance**: Async/await architecture for optimal performance\n\n## Supported Marketplaces\n\n- **Komus** (komus.ru) - Office supplies and stationery\n- **VseInstrumenti** (vseinstrumenti.ru) - Tools and equipment\n- **Ozon** (ozon.ru) - Universal marketplace\n- **Wildberries** (wildberries.ru) - Consumer goods\n- **OfficeMag** (officemag.ru) - Office supplies\n\n## Installation\n\n### From PyPI\n\n```bash\npip install offers-check-marketplaces\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/yourusername/offers-check-marketplaces-mcp.git\ncd offers-check-marketplaces-mcp\npip install -e .\n```\n\n## Quick Start\n\n### 1. Basic Usage\n\n```bash\n# Run in STDIO mode (for MCP clients)\noffers-check-marketplaces\n\n# Run in SSE mode (web server)\noffers-check-marketplaces --sse --host 0.0.0.0 --port 8000\n```\n\n### 2. MCP Configuration\n\nAdd to your MCP client configuration (e.g., `.cursor/mcp.json` or `.kiro/settings/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"offers_check_marketplaces\": {\n      \"command\": \"offers-check-marketplaces\",\n      \"env\": {\n        \"LICENSE_KEY\": \"your-license-key-here\"\n      }\n    }\n  }\n}\n```\n\n### 3. Environment Variables\n\n```bash\n# Set license key\nexport LICENSE_KEY=\"your-license-key-here\"\n\n# Optional: Set custom API endpoint\nexport API_BASE_URL=\"https://your-api-endpoint.com\"\n```\n\n## MCP Tools\n\nThe server provides the following MCP tools:\n\n### Core Tools\n\n- **`search_products`** - Search for products across marketplaces\n- **`get_product_details`** - Get detailed product information and prices\n- **`get_product_list`** - List all products from database\n- **`get_statistics`** - Generate comprehensive statistics\n\n### Data Management Tools\n\n- **`save_product_prices`** - Save found prices to database\n- **`update_all_prices`** - Batch update prices for multiple products\n\n### License Management Tools\n\n- **`check_license_status`** - Check current license status\n- **`set_license_key`** - Set new license key\n\n### Excel Tools\n\n- **`parse_excel_file`** - Parse Excel file and return structured data\n- **`get_excel_info`** - Get information about Excel file structure without reading all data\n- **`export_to_excel`** - Export data to Excel file with formatting\n- **`filter_excel_data`** - Filter Excel data by specified criteria\n- **`transform_excel_data`** - Transform Excel data according to specified rules\n\n## Usage Examples\n\n### Search Products\n\n```python\n# Using MCP client\nresult = await mcp_client.call_tool(\"search_products\", {\n    \"model_name\": \"\u041f\u043e\u043b\u043e\u0442\u043d\u043e \u0442\u0435\u0445\u043d\u0438\u0447\u0435\u0441\u043a\u043e\u0435 \u0411\u042f\u0417\u042c \u041e\u0422\u0411\u0415\u041b\u0415\u041d\u041d\u0410\u042f \u0413\u041e\u0421\u0422\"\n})\n```\n\n### Get Product Details\n\n```python\n# Get detailed information about a product\nresult = await mcp_client.call_tool(\"get_product_details\", {\n    \"product_code\": 195385.0\n})\n```\n\n### Generate Statistics\n\n```python\n# Get comprehensive statistics\nresult = await mcp_client.call_tool(\"get_statistics\", {})\n```\n\n### Parse Excel File\n\n```python\n# Parse Excel file with specific parameters\nresult = await mcp_client.call_tool(\"parse_excel_file\", {\n    \"file_path\": \"data/input.xlsx\",\n    \"sheet_name\": \"\u0414\u0430\u043d\u043d\u044b\u0435\",\n    \"header_row\": 0,\n    \"max_rows\": 100\n})\n```\n\n### Export Data to Excel\n\n```python\n# Export processed data to Excel with formatting\nresult = await mcp_client.call_tool(\"export_to_excel\", {\n    \"data\": processed_data,\n    \"file_path\": \"data/output.xlsx\",\n    \"sheet_name\": \"\u0420\u0435\u0437\u0443\u043b\u044c\u0442\u0430\u0442\u044b\",\n    \"apply_formatting\": True,\n    \"auto_adjust_columns\": True\n})\n```\n\n### Filter Excel Data\n\n```python\n# Filter data by multiple criteria\nresult = await mcp_client.call_tool(\"filter_excel_data\", {\n    \"data\": excel_data,\n    \"filters\": {\n        \"\u041a\u0430\u0442\u0435\u0433\u043e\u0440\u0438\u044f\": \"\u0425\u043e\u0437\u0442\u043e\u0432\u0430\u0440\u044b \u0438 \u043f\u043e\u0441\u0443\u0434\u0430\",\n        \"\u0426\u0435\u043d\u0430 \u043f\u043e\u0437\u0438\u0446\u0438\u0438\\n\u041c\u041f c \u041d\u0414\u0421\": {\n            \"greater_than\": 1000,\n            \"less_than\": 5000\n        }\n    }\n})\n```\n\n## Configuration\n\n### License Configuration\n\nThe system requires a valid license key. You can provide it through:\n\n1. **Environment variable**: `LICENSE_KEY=your-key`\n2. **MCP configuration**: Set in the `env` section of your MCP config\n3. **Configuration file**: `data/.license_config.json`\n\n### Data Directory\n\nThe system automatically creates user data directories following OS standards:\n\n- **Windows**: `%APPDATA%\\offers-check-marketplaces\\`\n- **macOS**: `~/Library/Application Support/offers-check-marketplaces/`\n- **Linux**: `~/.local/share/offers-check-marketplaces/` (XDG compliant)\n\nContains:\n\n- SQLite database (`database/products.db`)\n- License cache (`cache/.license_cache.json`)\n- Excel files for import/export\n- Application logs (`logs/`)\n\nYou can override the location using the `OFFERS_CHECK_DATA_DIR` environment variable.\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/yourusername/offers-check-marketplaces-mcp.git\ncd offers-check-marketplaces-mcp\n\n# Install with development dependencies\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run specific test files\npython test_license_integration.py\npython test_mcp_license_tools.py\npython test_final_integration.py\n```\n\n### Building Package\n\n```bash\n# Install build tools\npip install build twine\n\n# Build package\npython -m build\n\n# Upload to PyPI (requires credentials)\ntwine upload dist/*\n```\n\n## Architecture\n\n### Components\n\n- **Server** (`server.py`) - Main MCP server with tool implementations\n- **License Manager** (`license_manager.py`) - License verification and management\n- **Database Manager** (`database_manager.py`) - SQLite database operations\n- **Search Engine** (`search_engine.py`) - Multi-marketplace search coordination\n- **Data Processor** (`data_processor.py`) - Excel file processing\n- **Statistics Generator** (`statistics.py`) - Analytics and reporting\n- **Error Handling** (`error_handling.py`) - Comprehensive error management\n\n### Data Flow\n\n1. **Input**: Excel files with product specifications\n2. **Processing**: Search products across marketplaces\n3. **Storage**: Save results to SQLite database\n4. **Analysis**: Generate statistics and comparisons\n5. **Output**: Updated Excel files with prices and analysis\n\n## API Reference\n\n### Search Products\n\n```python\nsearch_products(model_name: str) -> dict\n```\n\nSearch for products across multiple marketplaces.\n\n**Parameters:**\n\n- `model_name` (str): Product model name to search for\n\n**Returns:**\n\n- Dictionary with search results from different marketplaces\n\n### Get Product Details\n\n```python\nget_product_details(product_code: float) -> dict\n```\n\nGet detailed information about a specific product.\n\n**Parameters:**\n\n- `product_code` (float): Unique product code from database\n\n**Returns:**\n\n- Dictionary with product details and price analysis\n\n## Error Handling\n\nThe system includes comprehensive error handling:\n\n- **License Errors**: Invalid or missing license keys\n- **Network Errors**: Marketplace connectivity issues\n- **Database Errors**: SQLite operation failures\n- **Validation Errors**: Invalid input parameters\n\nAll errors are logged and return user-friendly messages.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [GitHub Repository](https://github.com/yourusername/offers-check-marketplaces-mcp)\n- **Issues**: [Bug Tracker](https://github.com/yourusername/offers-check-marketplaces-mcp/issues)\n- **License**: Contact support for license-related questions\n\n## Changelog\n\n### v0.1.0\n\n- Initial release\n- Multi-marketplace product search\n- Price comparison and analysis\n- Integrated license management\n- MCP server implementation\n- Excel data processing\n- SQLite database storage\n- Comprehensive error handling\n\n---\n\nMade with \u2764\ufe0f for automated marketplace analysis\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "MCP server for automated product search and price comparison across multiple marketplaces with integrated license management",
    "version": "0.1.2",
    "project_urls": {
        "Bug Tracker": "https://github.com/yourusername/offers-check-marketplaces-mcp/issues",
        "Documentation": "https://github.com/yourusername/offers-check-marketplaces-mcp#readme",
        "Homepage": "https://github.com/yourusername/offers-check-marketplaces-mcp",
        "Repository": "https://github.com/yourusername/offers-check-marketplaces-mcp"
    },
    "split_keywords": [
        "automation",
        " e-commerce",
        " marketplace",
        " mcp",
        " price-comparison"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "fa85cbc79d4f98bc0dc819a2133dbc7386b4421c50ddebbf6de37b1d84facf04",
                "md5": "e26c07203a8ff4ddb19c2d3990f55ab2",
                "sha256": "ed6e04fee9f92efb286293d9a2b3fa6041f6dfd3aab3ed0d0f18af373df90933"
            },
            "downloads": -1,
            "filename": "offers_check_marketplaces_mcp_2025-0.1.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e26c07203a8ff4ddb19c2d3990f55ab2",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 101097,
            "upload_time": "2025-08-01T09:49:13",
            "upload_time_iso_8601": "2025-08-01T09:49:13.699836Z",
            "url": "https://files.pythonhosted.org/packages/fa/85/cbc79d4f98bc0dc819a2133dbc7386b4421c50ddebbf6de37b1d84facf04/offers_check_marketplaces_mcp_2025-0.1.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "b950e315f68dc926e5c41ab1f4effb014612816568a29737939517271286c736",
                "md5": "b0ee134490d2cef2391ada32e1b18f0c",
                "sha256": "a2d1210634bbe13545ad0ea71e077f189b30d0ce578071c6bd48ae9b8ee12eaf"
            },
            "downloads": -1,
            "filename": "offers_check_marketplaces_mcp_2025-0.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "b0ee134490d2cef2391ada32e1b18f0c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 514694,
            "upload_time": "2025-08-01T09:49:30",
            "upload_time_iso_8601": "2025-08-01T09:49:30.907821Z",
            "url": "https://files.pythonhosted.org/packages/b9/50/e315f68dc926e5c41ab1f4effb014612816568a29737939517271286c736/offers_check_marketplaces_mcp_2025-0.1.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-01 09:49:30",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "yourusername",
    "github_project": "offers-check-marketplaces-mcp",
    "github_not_found": true,
    "lcname": "offers-check-marketplaces-mcp-2025"
}
        
Elapsed time: 0.59863s