iflow-mcp_particular-audience-mcp-search-server 0.1.0__tar.gz

iflow_mcp_particular_audience_mcp_search_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Particular Audience.
+
+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.

iflow_mcp_particular_audience_mcp_search_server-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_particular-audience-mcp-search-server
+Version: 0.1.0
+Summary: MCP Search Server
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: fastapi>=0.95.0
+Requires-Dist: uvicorn>=0.21.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=1.10.7
+Requires-Dist: mcp>=0.5.0
+Requires-Dist: mcp-use>=1.2.0
+Requires-Dist: fastembed>=0.4.2
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: gql>=3.0.0
+Requires-Dist: requests-toolbelt>=1.0.0
+Dynamic: license-file

iflow_mcp_particular_audience_mcp_search_server-0.1.0/README.md

@@ -0,0 +1,252 @@
+# Adaptive Transformer Search MCP Server
+
+This MCP (Model Context Protocol) server provides access to [Particular Audience's Adaptive Transformer Search (ATS)](https://particularaudience.com/search/) - an AI-powered eCommerce search solution that harnesses the power of Large Language Models to understand customer search intent and eliminate zero search results.
+
+## What is Adaptive Transformer Search?
+
+Adaptive Transformer Search (ATS) represents a revolutionary leap beyond traditional keyword-based search and basic catalog browsing. Unlike conventional search that relies on exact token matching, ATS uses the same transformer technology behind OpenAI's GPT and Google's translation systems to understand the semantic meaning and intent behind customer queries. This enables the system to understand the difference between "chocolate milk" and "milk chocolate," handle natural language queries, and provide relevant results even when exact keyword matches don't exist.
+
+### Benefits Over Traditional Search
+
+ATS addresses the $300 billion search problem in eCommerce by eliminating the need for manual synonym rules, redirects, and ongoing search maintenance. Traditional keyword search requires extensive manual configuration and often fails when customers use natural language or misspellings. ATS automatically understands customer intent, reducing zero search results by up to 70% while increasing search revenue by 20% and eliminating 99% of manual search management work.
+
+### Merchandising Control for Retailers
+
+One of the key advantages of ATS is the ability for retailers to maintain merchandising control over how LLMs interpret and rank search results. Retailers can boost specific products, brands, or categories within search results based on promotional campaigns, inventory levels, or margin objectives. This ensures that while the AI provides intelligent, relevant results, retailers retain the ability to influence discovery in alignment with their business goals.
+
+### Enabling Retail Media in LLM Discovery
+
+ATS seamlessly integrates retail media capabilities into the search experience, allowing sponsored products to be intelligently woven into search results. This creates new revenue opportunities for retailers while maintaining relevance and user experience. The system can prioritize sponsored products when they genuinely match customer intent, creating a win-win scenario for retailers, advertisers, and customers.
+
+## Features
+
+This MCP server provides three main search tools that interface with the Particular Audience Search API, giving you access to all ATS capabilities:
+
+- **Search**: Adaptive Transformer Search with natural language understanding, optional filters, and pagination
+- **Filtered Search**: ATS search with required filters to narrow results while maintaining semantic understanding
+- **Sorted Search**: ATS search with custom sorting options (price, popularity, etc.) and merchandising control
+
+The server handles authentication automatically and provides comprehensive error handling and retry logic. All searches benefit from ATS's transformer technology, eliminating zero search results and providing intelligent, relevant product matches.
+
+## ATS Capabilities Available Through This MCP Server
+
+When you use this MCP server, you get access to all Adaptive Transformer Search capabilities:
+
+### Natural Language Understanding
+- Understands semantic meaning behind queries (e.g., "chocolate milk" vs "milk chocolate")
+- Handles natural language queries like "comfortable shoes for walking under $100"
+- Processes misspellings and variations automatically
+
+### Intelligent Search Results
+- Eliminates zero search results by up to 70%
+- Provides relevant results even when exact keyword matches don't exist
+- Understands product relationships and context
+
+### Merchandising Control
+- Boost specific products, brands, or categories in search results
+- Control ranking based on promotional campaigns, inventory, or margin objectives
+- Maintain business control while leveraging AI intelligence
+
+### Retail Media Integration
+- Seamlessly integrate sponsored products into search results
+- Maintain relevance while creating revenue opportunities
+- Intelligent placement of retail media content
+
+### Zero Manual Maintenance
+- No need for synonym rules, redirects, or manual search configuration
+- Automatically adapts to changes in user behavior and catalog data
+- Reduces manual search management work by 99%
+
+## Connecting to Onsite LLM/Chat Agents
+
+This MCP server enables seamless integration of ATS into your existing LLM-powered chat agents and discovery experiences. By connecting this server to your onsite AI assistant, customers can now search your product catalog using natural language through chat interfaces. The AI can understand complex queries like "show me comfortable shoes for walking that are under $100" and return relevant results, even if the customer doesn't use exact product names or categories. This creates a more intuitive, conversational shopping experience that feels natural to customers while driving higher conversion rates.
+
+## Prerequisites
+
+- Python 3.11 or higher
+- [UV](https://github.com/astral-sh/uv) package manager
+- Docker (optional, for containerized deployment)
+
+## Configuration
+
+Create a `.env` file with the following content (or set environment variables directly):
+
+```
+# Authentication settings
+AUTH_ENDPOINT=AUTHENTICATION_ENDPOINT
+SEARCH_API_ENDPOINT=SEARCH_ENDPOINT
+CLIENT_ID=your_client_id_here
+CLIENT_SHORTCODE=your_client_shortcode_here
+CLIENT_SECRET=your_client_secret_here
+
+# Server settings
+HOST=0.0.0.0
+PORT=3000
+MESSAGE_PATH=/mcp/messages/
+```
+
+## Deployment Options
+
+### Option 1: Direct UV Run
+
+Run directly with UV (assuming UV is pre-installed):
+
+```bash
+# Simple run
+uv run mcp_search_server.py
+
+# Or with inline environment variables
+AUTH_ENDPOINT=AUTHENTICATION_ENDPOINT \
+SEARCH_API_ENDPOINT=SEARCH_ENDPOINT \
+CLIENT_ID=your_id \
+CLIENT_SHORTCODE=your_code \
+CLIENT_SECRET=your_secret \
+uv run mcp_search_server.py
+```
+
+### Option 2: Docker Deployment
+
+Build and run using Docker:
+
+```bash
+# Build
+docker build -t mcp-search-server .
+
+# Run with env file
+docker run -p 3000:3000 --env-file .env mcp-search-server
+
+# Or run with inline environment variables
+docker run -p 3000:3000 \
+  -e AUTH_ENDPOINT=AUTHENTICATION_ENDPOINT \
+  -e SEARCH_API_ENDPOINT=SEARCH_ENDPOINT \
+  -e CLIENT_ID=your_id \
+  -e CLIENT_SHORTCODE=your_code \
+  -e CLIENT_SECRET=your_secret \
+  mcp-search-server
+```
+
+## MCP Client Configuration
+
+You can configure AI assistants like Claude Desktop or VS Code Copilot to use this MCP Search Server.
+
+### Integration with Claude Desktop
+
+To configure Claude Desktop:
+
+1. Specify your API credentials
+2. Retrieve your `uv` command full path (e.g. `which uv`)
+3. Edit the Claude Desktop configuration file (location varies by OS:
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - Linux: `~/.config/Claude/claude_desktop_config.json`)
+
+#### Local UV Configuration
+
+```json
+{
+  "mcpServers": {
+    "uv-search-server": {
+      "command": "/path/to/your/uv",
+      "args": [
+        "--directory",
+        "/path/to/your/project/directory",
+        "run",
+        "mcp_search_server.py"
+      ],
+      "env": {
+        "AUTH_ENDPOINT": "AUTHENTICATION_ENDPOINT",
+        "SEARCH_API_ENDPOINT": "SEARCH_ENDPOINT",
+        "CLIENT_ID": "your_client_id",
+        "CLIENT_SHORTCODE": "your_client_shortcode",
+        "CLIENT_SECRET": "your_client_secret",
+        "PYTHONUNBUFFERED": "1"
+      }
+    }
+  }
+}
+```
+
+#### Docker Configuration
+
+```json
+{
+  "mcpServers": {
+    "uv-search-server": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "--name",
+        "mcp-search-server",
+        "-p",
+        "3000:3000",
+        "-i",
+        "-e", "AUTH_ENDPOINT",
+        "-e", "SEARCH_API_ENDPOINT",
+        "-e", "CLIENT_ID",
+        "-e", "CLIENT_SHORTCODE",
+        "-e", "CLIENT_SECRET",
+        "-e", "PYTHONUNBUFFERED",
+        "mcp-search-server"
+      ],
+      "env": {
+        "AUTH_ENDPOINT": "AUTHENTICATION_ENDPOINT",
+        "SEARCH_API_ENDPOINT": "SEARCH_ENDPOINT",
+        "CLIENT_ID": "your_client_id",
+        "CLIENT_SHORTCODE": "your_client_shortcode",
+        "CLIENT_SECRET": "your_client_secret",
+        "PYTHONUNBUFFERED": "1"
+      }
+    }
+  }
+}
+```
+
+### Integration with VS Code
+
+For VS Code integration:
+
+1. Enable agent mode tools in your `settings.json`:
+   ```json
+   {
+     "chat.agent.enabled": true
+   }
+   ```
+
+2. Configure the Search Server in your `.vscode/mcp.json` or in VS Code's `settings.json`:
+   ```json
+   // Example .vscode/mcp.json
+   {
+     "servers": {
+       "uv-search-server": {
+         "type": "stdio",
+         "command": "/path/to/your/uv",
+         "args": [
+           "--directory",
+           "/path/to/your/project/directory",
+           "run",
+           "mcp_search_server.py"
+         ],
+         "env": {
+           "AUTH_ENDPOINT": "AUTHENTICATION_ENDPOINT",
+           "SEARCH_API_ENDPOINT": "SEARCH_ENDPOINT",
+           "CLIENT_ID": "your_client_id",
+           "CLIENT_SHORTCODE": "your_client_shortcode",
+           "CLIENT_SECRET": "your_client_secret",
+           "PYTHONUNBUFFERED": "1"
+         }
+       }
+     }
+   }
+   ```
+
+### Troubleshooting
+
+For Claude Desktop, you can check logs with:
+```bash
+tail -f ~/Library/Logs/Claude/mcp-server-uv-search-server.log
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. 

iflow_mcp_particular_audience_mcp_search_server-0.1.0/iflow_mcp_particular_audience_mcp_search_server.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_particular-audience-mcp-search-server
+Version: 0.1.0
+Summary: MCP Search Server
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: fastapi>=0.95.0
+Requires-Dist: uvicorn>=0.21.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=1.10.7
+Requires-Dist: mcp>=0.5.0
+Requires-Dist: mcp-use>=1.2.0
+Requires-Dist: fastembed>=0.4.2
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: gql>=3.0.0
+Requires-Dist: requests-toolbelt>=1.0.0
+Dynamic: license-file

iflow_mcp_particular_audience_mcp_search_server-0.1.0/iflow_mcp_particular_audience_mcp_search_server.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+mcp_search_server.py
+pyproject.toml
+iflow_mcp_particular_audience_mcp_search_server.egg-info/PKG-INFO
+iflow_mcp_particular_audience_mcp_search_server.egg-info/SOURCES.txt
+iflow_mcp_particular_audience_mcp_search_server.egg-info/dependency_links.txt
+iflow_mcp_particular_audience_mcp_search_server.egg-info/requires.txt
+iflow_mcp_particular_audience_mcp_search_server.egg-info/top_level.txt

iflow_mcp_particular_audience_mcp_search_server-0.1.0/iflow_mcp_particular_audience_mcp_search_server.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

iflow_mcp_particular_audience_mcp_search_server-0.1.0/iflow_mcp_particular_audience_mcp_search_server.egg-info/requires.txt

@@ -0,0 +1,10 @@
+fastapi>=0.95.0
+uvicorn>=0.21.0
+requests>=2.28.0
+pydantic>=1.10.7
+mcp>=0.5.0
+mcp-use>=1.2.0
+fastembed>=0.4.2
+python-dotenv>=1.0.0
+gql>=3.0.0
+requests-toolbelt>=1.0.0

iflow_mcp_particular_audience_mcp_search_server-0.1.0/iflow_mcp_particular_audience_mcp_search_server.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcp_search_server

iflow_mcp_particular_audience_mcp_search_server-0.1.0/mcp_search_server.py

@@ -0,0 +1,788 @@
+#!/usr/bin/env python3
+"""
+MCP Search Server
+
+This MCP server provides tools for searching products using the Particular Audience Search API.
+The server exposes three main tools:
+- search: Basic product search with optional filters
+- filtered_search: Search with required filters
+- sorted_search: Search with custom sorting options
+
+Usage:
+    python mcp_search_server.py
+
+Configuration:
+    Set the following environment variables in a .env file:
+    - AUTH_ENDPOINT: Authentication endpoint 
+    - SEARCH_API_ENDPOINT: Search API endpoint 
+    - CLIENT_ID: Client ID for authentication (required)
+    - CLIENT_SHORTCODE: Client shortcode (required)
+    - CLIENT_SECRET: Client secret for authentication (required)
+    - HOST: Server host (default: 0.0.0.0)
+    - PORT: Server port (default: 3000)
+    - MESSAGE_PATH: Path for MCP messages (default: /mcp/messages/)
+"""
+
+import os
+import time
+import logging
+import json
+from typing import Dict, Any, List, Optional
+import traceback
+from contextlib import asynccontextmanager
+
+import requests
+from fastapi import HTTPException
+from pydantic import BaseModel, Field
+from mcp.server.fastmcp import FastMCP, Context
+
+# Import dotenv for environment variable loading
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger("mcp_search_server")
+
+# Service configuration from environment variables
+AUTH_ENDPOINT = os.environ.get("AUTH_ENDPOINT")
+SEARCH_API_ENDPOINT = os.environ.get("SEARCH_API_ENDPOINT")
+CLIENT_ID = os.environ.get("CLIENT_ID")
+CLIENT_SHORTCODE = os.environ.get("CLIENT_SHORTCODE")
+CLIENT_SECRET = os.environ.get("CLIENT_SECRET")
+
+# Server configuration from environment variables
+HOST = os.environ.get("HOST", "0.0.0.0")
+PORT = int(os.environ.get("PORT", 3000))
+MESSAGE_PATH = os.environ.get("MESSAGE_PATH", "/mcp/messages/")
+
+# Token cache
+token_cache = {}
+
+# Validate required environment variables
+if not CLIENT_ID:
+    raise ValueError("CLIENT_ID environment variable is required")
+if not CLIENT_SHORTCODE:
+    raise ValueError("CLIENT_SHORTCODE environment variable is required")
+if not CLIENT_SECRET:
+    raise ValueError("CLIENT_SECRET environment variable is required")
+
+# Core models
+class FilterSpec(BaseModel):
+    field: str
+    value: Any
+    operator: str = "eq"
+
+class SortSpec(BaseModel):
+    field: str
+    order: str = "desc"
+    type: str = "number"
+
+# Search response models
+class PaginationInfo(BaseModel):
+    current_page: int
+    total_pages: int
+    total_results: int
+    page_size: int
+
+class SearchResponse(BaseModel):
+    results: List[Dict[str, Any]]
+    pagination: PaginationInfo
+    aggregations: Optional[Dict[str, Any]] = None
+    suggestions: Optional[List[str]] = None
+    redirect_url: Optional[Dict[str, Any]] = None
+    execution_time_ms: Optional[int] = None
+
+# Auth function
+async def get_auth_token(client_id: str = None) -> str:
+    """
+    Get authentication token from the auth service.
+    
+    Parameters:
+    - client_id: Optional client ID, defaults to CLIENT_ID from environment
+    
+    Returns:
+    - Access token string
+    
+    Raises:
+    - HTTPException: If authentication fails
+    """
+    client_id = client_id or CLIENT_ID
+    client_secret = CLIENT_SECRET
+    
+    if not client_id:
+        raise HTTPException(status_code=400, detail="Client ID is required")
+    
+    current_time = time.time()
+    
+    # Use cached token if valid
+    if client_id in token_cache and token_cache[client_id].get("expires_at", 0) > current_time:
+        return token_cache[client_id]["access_token"]
+    
+    # Fetch new token
+    logger.info(f"Fetching new auth token for client {client_id}")
+    try:
+        form_data = {
+            'client_id': client_id,
+            'grant_type': 'client_credentials'
+        }
+        
+        if client_secret:
+            form_data['client_secret'] = client_secret
+        
+        response = requests.post(
+            AUTH_ENDPOINT,
+            data=form_data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            timeout=10
+        )
+        response.raise_for_status()
+        
+        data = response.json()
+        access_token = data.get("access_token")
+        expires_in = data.get("expires_in", 3600)
+        token_type = data.get("token_type", "Bearer")
+        
+        # Cache token with 5-min safety margin
+        token_cache[client_id] = {
+            "access_token": access_token,
+            "token_type": token_type,
+            "expires_at": current_time + expires_in - 300
+        }
+        
+        return access_token
+        
+    except Exception as e:
+        logger.error(f"Auth token request failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to get auth token: {e}")
+
+# Search API function
+async def perform_search(
+    query: str,
+    start: int = 0,
+    size: int = 20,
+    filters: List[FilterSpec] = None,
+    sort_fields: List[SortSpec] = None
+) -> SearchResponse:
+    """
+    Perform product search using the Search API.
+    
+    Parameters:
+    - query: Search query string
+    - start: Starting position for pagination (0-based)
+    - size: Number of results to return per page
+    - filters: Optional list of FilterSpec objects for narrowing results
+    - sort_fields: Optional list of SortSpec objects for custom sorting
+    
+    Returns:
+    - SearchResponse object containing search results and metadata
+    
+    Raises:
+    - HTTPException: If search operation fails
+    """
+    logger.info(f"Searching for '{query}' on website {CLIENT_ID}")
+    
+    # Generate scope dictionary from filters
+    scope = {}
+    if filters:
+        for filter_spec in filters:
+            field = filter_spec.field
+            value = filter_spec.value
+            operator = filter_spec.operator
+            # Handle different operator types
+            if operator == "eq":
+                # Direct mapping for equality filters
+                scope[field] = value
+            elif operator == "range":
+                # For range filters, create or update min/max values
+                if field not in scope:
+                    scope[field] = {}                
+                # Handle range as dictionary with min/max keys
+                if isinstance(value, dict):
+                    if "min" in value:
+                        scope[field]["min"] = value["min"]
+                    if "max" in value:
+                        scope[field]["max"] = value["max"]
+                # Handle individual gte/lte operators
+                elif operator == "gte":
+                    scope[field]["min"] = value
+                elif operator == "lte":
+                    scope[field]["max"] = value
+        logger.debug(f"Generated scope from filters: {scope}")
+
+    if sort_fields:
+        sort_fields_list = [{sort_field.field: {"order": sort_field.order, "type": sort_field.type}} for sort_field in sort_fields]
+        logger.info(f"Sort fields: {sort_fields_list}")
+    else:
+        sort_fields_list = None
+    
+    # Build search request based on sample-body.json format
+    search_request = {
+        "q": query,
+        "website_id": str(CLIENT_ID).lower(),
+        "client": CLIENT_SHORTCODE,
+        "size": size,
+        "start": start,
+        "scope": scope
+    }
+    if sort_fields_list:
+        search_request["sort_fields"] = sort_fields_list
+    
+    # Call Search API
+    start_time = time.time()
+    max_retries = 3
+    for attempt in range(max_retries):
+        try:
+            token = await get_auth_token(client_id=CLIENT_ID)
+            logger.info(f"Sending search request (attempt {attempt+1}): {json.dumps(search_request)[:500]}...")
+            response = requests.post(
+                SEARCH_API_ENDPOINT,
+                json=search_request,
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "Content-Type": "application/json"
+                },
+                timeout=15
+            )
+            if response.status_code == 401:
+                logger.warning(f"Received 401 Unauthorized from search API (attempt {attempt+1}). Invalidating token cache and retrying...")
+                # Invalidate token cache for this client
+                if CLIENT_ID in token_cache:
+                    del token_cache[CLIENT_ID]
+                if attempt < max_retries - 1:
+                    continue  # Try again with a new token
+                else:
+                    response.raise_for_status()  # Will raise HTTPError
+            response.raise_for_status()
+            data = response.json()
+            payload = data.get("payload")
+            logger.info(f"Search API response: {payload}")
+            execution_time_ms = int((time.time() - start_time) * 1000)
+            total_results = payload.get("total_results", 0)
+            page_size = size
+            total_pages = max(1, (total_results + page_size - 1) // page_size)
+            current_page = start // page_size + 1
+            pagination = PaginationInfo(
+                current_page=current_page,
+                total_pages=total_pages,
+                total_results=total_results,
+                page_size=page_size
+            )
+            return SearchResponse(
+                results=payload.get("results", []),
+                pagination=pagination,
+                aggregations=payload.get("aggregations"),
+                suggestions=payload.get("suggestions", {}).get("fuzzy_suggestions", []),
+                redirect_url=payload.get("redirect_url"),
+                execution_time_ms=execution_time_ms
+            )
+        except requests.HTTPError as e:
+            if hasattr(e.response, 'status_code') and e.response.status_code == 401:
+                logger.warning(f"HTTPError 401 on attempt {attempt+1}: {e}")
+                if CLIENT_ID in token_cache:
+                    del token_cache[CLIENT_ID]
+                if attempt < max_retries - 1:
+                    continue
+            logger.error(f"Search failed with HTTPError: {e}")
+            raise HTTPException(status_code=500, detail=f"Search operation failed: {e}")
+        except Exception as e:
+            logger.error(f"Search failed: {e}")
+            raise HTTPException(status_code=500, detail=f"Search operation failed: {e}")
+    # If we exit the loop, all retries failed
+    raise HTTPException(status_code=500, detail="Search operation failed after multiple retries due to authentication errors.")
+
+# Create FastMCP server with SSE settings
+mcp_server = FastMCP(
+    name="MCP Search Server",
+    host=HOST,
+    port=PORT,
+    message_path=MESSAGE_PATH,
+    debug=True,
+    log_level="INFO"
+)
+
+# Register MCP tools
+@mcp_server.tool("search")
+async def search(
+    query: str, 
+    start: int = 0, 
+    size: int = 20,
+    filters: List[FilterSpec] = None,
+    ctx: Context = None
+) -> SearchResponse:
+    """
+    Execute a product search with optional filters.
+    
+    Parameters:
+    - query: The search query text (e.g., "blue shirts", "tires", "dress")
+    - start: Starting position for pagination (0-based index)
+    - size: Number of results to return per page
+    - filters: Optional list of filters to narrow search results
+      Format: [{"field": "color", "value": "blue", "operator": "eq"}]
+      Supported operators: 
+        - "eq" (equals): {"field": "color", "value": "blue", "operator": "eq"}
+        - "range" (for min/max values): {"field": "price", "value": {"min": 20, "max": 100}, "operator": "range"}
+    
+    Returns:
+    - SearchResponse object containing results, pagination info, and optional metadata
+      
+    Authentication is handled automatically using environment variables.
+    """
+    # Log the search request
+    if ctx:
+        await ctx.info(f"Searching for '{query}' on website: {CLIENT_ID}")
+    
+    return await perform_search(
+        query=query,
+        start=start,
+        size=size,
+        filters=filters
+    )
+
+# Add specialized search tool
+@mcp_server.tool("filtered_search")
+async def filtered_search(
+    query: str,
+    filters: List[FilterSpec],
+    start: int = 0,
+    size: int = 20,
+    ctx: Context = None
+) -> SearchResponse:
+    """
+    Search products with specific filters.
+    
+    Parameters:
+    - query: The search query text (can be empty if using filters only)
+    - filters: List of filters to narrow search results
+      Format: [{"field": "field_name", "value": value, "operator": "eq"}]
+      Examples:
+        - Category filter: {"field": "product_category", "value": "Clothing > Shirts", "operator": "eq"}
+        - Color filter: {"field": "color", "value": "blue", "operator": "eq"}
+        - Price range: {"field": "price", "value": {"min": 20, "max": 100}, "operator": "range"}
+    - start: Starting position for pagination (0-based index)
+    - size: Number of results to return per page
+    
+    Returns:
+    - SearchResponse object containing results, pagination info, and optional metadata
+    """
+    if ctx:
+        await ctx.info(f"Filtered search for '{query}' with filters: {filters}")
+    
+    return await perform_search(
+        query=query,
+        start=start,
+        size=size,
+        filters=filters
+    )
+
+# Add sorted search tool
+@mcp_server.tool("sorted_search")
+async def sorted_search(
+    query: str,
+    sort: List[SortSpec],
+    start: int = 0,
+    size: int = 20,
+    filters: List[FilterSpec] = None,
+    ctx: Context = None
+) -> SearchResponse:
+    """
+    Search products with custom sorting options.
+    
+    Parameters:
+    - query: The search query text (can be empty if using filters only)
+    - sort: List of sort specifications to order results
+      Format: [{"field": "field_name", "order": "asc|desc", "type": "number|text|date"}]
+      Examples:
+        - Price (lowest first): {"field": "price", "order": "asc", "type": "number"}
+        - Popularity (highest first): {"field": "popularity", "order": "desc", "type": "number"}
+        - Name (alphabetical): {"field": "title", "order": "asc", "type": "text"}
+    - start: Starting position for pagination (0-based index)
+    - size: Number of results to return per page
+    - filters: Optional list of filters to narrow search results
+      Same format as the 'filters' parameter in the search and filtered_search tools
+    
+    Returns:
+    - SearchResponse object containing results, pagination info, and optional metadata
+    """
+    if ctx:
+        await ctx.info(f"Sorted search for '{query}' with sort: {sort}")
+    
+    return await perform_search(
+        query=query,
+        start=start,
+        size=size,
+        filters=filters or [],
+        sort_fields=sort
+    )
+
+
+# Register resources
+@mcp_server.resource(
+    uri="resource://search/docs",
+    name="Search Documentation",
+    description="Documentation for the product search API",
+    mime_type="application/json",
+)
+async def search_docs_resource() -> str:
+    """
+    Provides comprehensive documentation about the search tools with parameter descriptions and examples.
+    This resource includes details on all available search tools, parameter formats, and usage examples.
+    
+    Returns:
+    - JSON string containing search API documentation
+    """
+    
+    docs = {
+        "name": "search",
+        "description": "Execute a product search against the Search API with optional filters",
+        "parameters": {
+            "query": {
+                "type": "string",
+                "description": "The search query string (e.g., 'blue shirts', 'tires')"
+            },
+            "start": {
+                "type": "integer",
+                "description": "Starting position for results (0-based)",
+                "default": 0
+            },
+            "size": {
+                "type": "integer",
+                "description": "Number of results per page",
+                "default": 20
+            },
+            "filters": {
+                "type": "array",
+                "description": "Optional filters to narrow search results",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "field": {
+                            "type": "string", 
+                            "description": "Field name to filter on (e.g., 'color', 'price', 'product_category')"
+                        },
+                        "value": {
+                            "type": ["string", "number", "object"],
+                            "description": "Filter value - can be string/number for equality or object with min/max for ranges" 
+                        },
+                        "operator": {
+                            "type": "string",
+                            "enum": ["eq", "range", "gte", "lte"],
+                            "description": "Filter operator - 'eq' for equality, 'range' for min/max values",
+                            "default": "eq"
+                        }
+                    },
+                    "required": ["field", "value"]
+                }
+            }
+        },
+        "tools": {
+            "search": {
+                "description": "Basic search with optional filters",
+                "parameters": ["query", "start", "size", "filters"]
+            },
+            "filtered_search": {
+                "description": "Search with mandatory filters",
+                "parameters": ["query", "filters", "start", "size"]
+            },
+            "sorted_search": {
+                "description": "Search with custom sorting options",
+                "parameters": ["query", "sort", "start", "size", "filters"]
+            }
+        },
+        "sorting": {
+            "description": "Sorting specifications for sorted_search tool",
+            "sort_spec": {
+                "field": {
+                    "type": "string",
+                    "description": "Field name to sort by (e.g., 'price', 'popularity')"
+                },
+                "order": {
+                    "type": "string",
+                    "enum": ["asc", "desc"],
+                    "description": "Sort order - 'asc' for ascending, 'desc' for descending",
+                    "default": "desc"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": ["number", "text", "date"],
+                    "description": "Type of the field being sorted",
+                    "default": "number"
+                }
+            },
+            "sort_examples": [
+                {
+                    "description": "Sort by price (lowest first)",
+                    "sort": {"field": "price", "order": "asc", "type": "number"}
+                },
+                {
+                    "description": "Sort by popularity (highest first)",
+                    "sort": {"field": "popularity", "order": "desc", "type": "number"}
+                },
+                {
+                    "description": "Sort by name (alphabetical)",
+                    "sort": {"field": "title", "order": "asc", "type": "text"}
+                }
+            ]
+        },
+        "internal_configuration": {
+            "website_id": CLIENT_ID,
+            "client_shortcode": CLIENT_SHORTCODE
+        },
+        "filter_examples": [
+            {
+                "description": "Filter by color (equality)",
+                "filter": {"field": "color", "value": "blue", "operator": "eq"}
+            },
+            {
+                "description": "Filter by category (equality)",
+                "filter": {"field": "product_category", "value": "Clothing > Shirts", "operator": "eq"}
+            },
+            {
+                "description": "Filter by price range",
+                "filter": {"field": "price", "value": {"min": 20, "max": 100}, "operator": "range"}
+            }
+        ],
+        "search_examples": [
+            {
+                "description": "Basic search",
+                "params": {
+                    "query": "dress",
+                    "start": 0,
+                    "size": 20
+                }
+            },
+            {
+                "description": "Search for tyres with pagination",
+                "params": {
+                    "query": "tyres tires wheels",
+                    "start": 10,
+                    "size": 15
+                }
+            },
+            {
+                "description": "Search with color filter",
+                "params": {
+                    "query": "shirts",
+                    "filters": [
+                        {"field": "color", "value": "blue", "operator": "eq"}
+                    ]
+                }
+            },
+            {
+                "description": "Category search with price range",
+                "params": {
+                    "query": "",
+                    "filters": [
+                        {"field": "product_category", "value": "Clothing > Shirts", "operator": "eq"},
+                        {"field": "price", "value": {"min": 20, "max": 100}, "operator": "range"}
+                    ]
+                }
+            }
+        ]
+    }
+    return json.dumps(docs, indent=2)
+
+@mcp_server.resource(
+    uri="resource://search/response-schema",
+    name="Search Response Schema",
+    description="Schema describing the format of search response",
+    mime_type="application/json",
+)
+async def search_response_schema_resource() -> str:
+    """
+    Provides the JSON schema for search response objects.
+    This resource documents the structure of responses returned by all search tools.
+    
+    Returns:
+    - JSON string containing the search response schema
+    """
+    
+    schema = {
+        "type": "object",
+        "properties": {
+            "results": {
+                "type": "array",
+                "description": "List of product results",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "description": "Product properties vary based on search results with no enforced schema"
+                    }
+                }
+            },
+            "pagination": {
+                "type": "object",
+                "properties": {
+                    "current_page": {"type": "integer", "description": "Current page number"},
+                    "total_pages": {"type": "integer", "description": "Total number of pages"},
+                    "total_results": {"type": "integer", "description": "Total number of results"},
+                    "page_size": {"type": "integer", "description": "Number of results per page"}
+                }
+            },
+            "aggregations": {
+                "type": "object",
+                "description": "Aggregation information for filtering"
+            },
+            "suggestions": {
+                "type": "array",
+                "description": "Search suggestions if query has few results",
+                "items": {
+                    "type": "string"
+                }
+            },
+            "redirect_url": {
+                "type": "object",
+                "description": "URL information for redirects on specific queries"
+            },
+            "execution_time_ms": {
+                "type": "integer",
+                "description": "Time taken to execute the search in milliseconds"
+            }
+        }
+    }
+    
+    return json.dumps(schema, indent=2)
+
+@mcp_server.resource(
+    uri="resource://search/examples",
+    name="Search Examples",
+    description="Examples of different search patterns",
+    mime_type="application/json",
+)
+async def search_examples_resource() -> str:
+    """
+    Provides ready-to-use example search requests for common use cases.
+    This resource includes complete examples for all search tools with various parameter combinations.
+    
+    Returns:
+    - JSON string containing practical search examples
+    """
+    examples = {
+        "basic_search": {
+            "description": "Basic product search",
+            "tool": "search",
+            "parameters": {
+                "query": "blue shirt",
+                "start": 0,
+                "size": 20
+            }
+        },
+        "filtered_category_search": {
+            "description": "Search for products in a specific category",
+            "tool": "filtered_search",
+            "parameters": {
+                "query": "",
+                "filters": [
+                    {"field": "product_category", "value": "Clothing > Shirts", "operator": "eq"}
+                ],
+                "start": 0,
+                "size": 20
+            }
+        },
+        "price_range_search": {
+            "description": "Search for products within a price range",
+            "tool": "filtered_search",
+            "parameters": {
+                "query": "dress",
+                "filters": [
+                    {"field": "price", "value": {"min": 29.99, "max": 99.99}, "operator": "range"}
+                ],
+                "start": 0,
+                "size": 20
+            }
+        },
+        "tyres_search": {
+            "description": "Search for tyres/tires with multiple filters",
+            "tool": "filtered_search",
+            "parameters": {
+                "query": "tyres tires wheels",
+                "filters": [
+                    {"field": "product_category", "value": "Automotive > Tires", "operator": "eq"},
+                    {"field": "size", "value": "205/55R16", "operator": "eq"}
+                ],
+                "start": 0,
+                "size": 15
+            }
+        },
+        "sorted_price_search": {
+            "description": "Search for products sorted by price (lowest first)",
+            "tool": "sorted_search",
+            "parameters": {
+                "query": "laptop",
+                "sort": [
+                    {"field": "price", "order": "asc", "type": "number"}
+                ],
+                "start": 0,
+                "size": 20
+            }
+        },
+        "sorted_filtered_search": {
+            "description": "Search with both filters and custom sorting",
+            "tool": "sorted_search",
+            "parameters": {
+                "query": "sneakers",
+                "sort": [
+                    {"field": "popularity", "order": "desc", "type": "number"}
+                ],
+                "filters": [
+                    {"field": "brand", "value": "Nike", "operator": "eq"},
+                    {"field": "price", "value": {"min": 50, "max": 150}, "operator": "range"}
+                ],
+                "start": 0,
+                "size": 20
+            }
+        },
+        "multiple_sort_fields": {
+            "description": "Search with multiple sort fields (primary and secondary ordering)",
+            "tool": "sorted_search",
+            "parameters": {
+                "query": "shoes",
+                "sort": [
+                    {"field": "price", "order": "asc", "type": "number"},
+                    {"field": "rating", "order": "desc", "type": "number"}
+                ],
+                "start": 0,
+                "size": 20
+            }
+        }
+    }
+    return json.dumps(examples, indent=2)
+
+# Add a simple lifespan function to handle server startup
+@asynccontextmanager
+async def server_lifespan(app: FastMCP):
+    """
+    Lifespan handler for the FastMCP server to manage startup and shutdown operations.
+    
+    On startup:
+    - Verifies the authentication service is working
+    - Pre-fetches a token for faster initial requests
+    
+    Parameters:
+    - app: The FastMCP server instance
+    """
+    logger.info("Server starting up")
+    
+    # Pre-fetch a token to verify auth service is working
+    try:
+        await get_auth_token()
+        logger.info("Auth service verified successfully")
+    except Exception as e:
+        logger.error(f"Auth service check failed: {e}")
+    
+    yield  # Server runs
+    
+    logger.info("Server shutting down")
+
+# Assign lifespan
+mcp_server.settings.lifespan = server_lifespan
+
+# Main entry point: run via SSE
+if __name__ == "__main__":
+    logger.info(f"Starting MCP Search Server on http://{HOST}:{PORT}")
+    mcp_server.run() 

iflow_mcp_particular_audience_mcp_search_server-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "iflow-mcp_particular-audience-mcp-search-server"
+version = "0.1.0"
+description = "MCP Search Server"
+requires-python = ">=3.11"
+
+dependencies = [
+    "fastapi>=0.95.0",
+    "uvicorn>=0.21.0",
+    "requests>=2.28.0",
+    "pydantic>=1.10.7",
+    "mcp>=0.5.0",
+    "mcp-use>=1.2.0",
+    "fastembed>=0.4.2",
+    "python-dotenv>=1.0.0",
+    "gql>=3.0.0",
+    "requests-toolbelt>=1.0.0"
+]
+
+[scripts]
+server = "mcp_search_server:main"
+
+[tool.setuptools]
+py-modules = ["mcp_search_server"]
+
+[tool.setuptools.packages.find]
+include = ["mcp_search_server"]
+exclude = ["sample_usage.py"]

iflow_mcp_particular_audience_mcp_search_server-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+