Shadowzzh

search.py

search.py
"""
Search MCP Server

This module provides MCP server functionality for performing web searches using various search engines.
It supports structured queries and returns LLM-friendly formatted search results.

Key features:
- Perform web searches using Google Custom Search API
- Filter and format search results for LLM consumption
- Validate and process search queries with metadata tracking

Main functions:
- mcp_search_google: Searches the web using Google Custom Search API
- mcp_get_search_capabilities: Returns information about search service capabilities
"""

import json
import os
import time
import traceback

import requests
from dotenv import load_dotenv
from pydantic import BaseModel, Field
from pydantic.fields import FieldInfo

from aworld.logs.util import Color
from examples.gaia.mcp_collections.base import ActionArguments, ActionCollection, ActionResponse


class SearchResult(BaseModel):
    """Individual search result with structured data."""

    id: str
    title: str
    url: str
    snippet: str
    source: str
    display_link: str | None = None
    formatted_url: str | None = None


class SearchMetadata(BaseModel):
    """Metadata for search operation results."""

    query: str
    search_engine: str
    total_results: int
    search_time: float | None = None
    language: str = "en"
    country: str = "us"
    safe_search: bool = True
    error_type: str | None = None
    api_quota_used: bool = False


class SearchCollection(ActionCollection):
    """MCP service for web search operations using various search engines.

    Provides comprehensive web search capabilities including:
    - Google Custom Search API integration
    - LLM-friendly result formatting
    - Search result filtering and validation
    - Metadata tracking for search operations
    - Error handling and quota management
    """

    def __init__(self, arguments: ActionArguments) -> None:
        super().__init__(arguments)

        # Load environment variables
        load_dotenv()

        # Validate required API credentials
        self.google_api_key = os.getenv("GOOGLE_API_KEY")
        self.google_cse_id = os.getenv("GOOGLE_CSE_ID")

        # Log initialization status
        self._color_log("Search service initialized", Color.green, "debug")

        if self.google_api_key and self.google_cse_id:
            self._color_log("Google Search API credentials found", Color.blue, "debug")
        else:
            self._color_log("Google Search API credentials missing - some features may be unavailable", Color.yellow)

    def _format_search_results_for_llm(self, results: list[SearchResult], query: str) -> str:
        """Format search results to be LLM-friendly.

        Args:
            results: List of search results
            query: Original search query

        Returns:
            Formatted string suitable for LLM consumption
        """
        if not results:
            return f"No search results found for query: '{query}'"

        formatted_parts = [f"# Search Results for: '{query}'", f"Found {len(results)} results:\n"]

        for i, result in enumerate(results, 1):
            result_section = [
                f"## Result {i}: {result.title}",
                f"**URL:** {result.url}",
                f"**Source:** {result.source}",
            ]

            if result.display_link:
                result_section.append(f"**Domain:** {result.display_link}")

            result_section.append(f"**Summary:** {result.snippet}")
            result_section.append("")  # Empty line for spacing

            formatted_parts.append("\n".join(result_section))

        return "\n".join(formatted_parts)

    def _validate_search_parameters(self, query: str, num_results: int) -> tuple[str, int]:
        """Validate and normalize search parameters.

        Args:
            query: Search query string
            num_results: Number of results requested

        Returns:
            Tuple of (validated_query, validated_num_results)

        Raises:
            ValueError: If parameters are invalid
        """
        if not query or not query.strip():
            raise ValueError("Search query cannot be empty")

        # Normalize query
        validated_query = query.strip()

        # Validate and clamp num_results
        validated_num_results = max(1, min(num_results, 10))  # Google CSE limit is 10

        return validated_query, validated_num_results

    def mcp_search_google(
        self,
        query: str = Field(description="The search query string to search for"),
        num_results: int = Field(default=5, description="Number of search results to return (1-10, default: 5)"),
        safe_search: bool = Field(default=True, description="Whether to enable safe search filtering"),
        language: str = Field(default="en", description="Language code for search results (e.g., 'en', 'es', 'fr')"),
        country: str = Field(default="us", description="Country code for search results (e.g., 'us', 'uk', 'ca')"),
        output_format: str = Field(default="json", description="Output format: 'markdown', 'json', or 'text'"),
    ) -> ActionResponse:
        """Search the web using Google Custom Search API.

        This tool provides comprehensive web search capabilities with:
        - Google Custom Search API integration
        - Configurable result count and filtering
        - Safe search and localization options
        - LLM-optimized result formatting
        - Detailed metadata tracking

        Args:
            query: The search query string
            num_results: Number of results to return (1-10)
            safe_search: Enable safe search filtering
            language: Language code for results
            country: Country code for results
            output_format: Format for the response

        Returns:
            ActionResponse with formatted search results and metadata
        """
        if isinstance(query, FieldInfo):
            query = query.default
        if isinstance(num_results, FieldInfo):
            num_results = num_results.default
        if isinstance(safe_search, FieldInfo):
            safe_search = safe_search.default
        if isinstance(language, FieldInfo):
            language = language.default
        if isinstance(country, FieldInfo):
            country = country.default
        if isinstance(output_format, FieldInfo):
            output_format = output_format.default

        try:
            # Validate API credentials
            if not self.google_api_key or not self.google_cse_id:
                return ActionResponse(
                    success=False,
                    message=(
                        "Google Search API credentials not configured. "
                        "Please set GOOGLE_API_KEY and GOOGLE_CSE_ID environment variables."
                    ),
                    metadata={"error_type": "missing_credentials"},
                )

            # Validate parameters
            validated_query, validated_num_results = self._validate_search_parameters(query, num_results)

            self._color_log(f"🔍 Searching Google for: '{validated_query}'", Color.cyan)

            # Prepare API request
            start_time = time.time()

            url = "https://www.googleapis.com/customsearch/v1"
            params = {
                "key": self.google_api_key,
                "cx": self.google_cse_id,
                "q": validated_query,
                "num": validated_num_results,
                "safe": "active" if safe_search else "off",
                "hl": language,
                "gl": country,
            }

            # Make API request
            response = requests.get(url, params=params, timeout=10)
            response.raise_for_status()

            search_time = time.time() - start_time
            data = response.json()

            # Parse search results
            search_results = []
            if "items" in data:
                for i, item in enumerate(data["items"]):
                    result = SearchResult(
                        id=f"google-{i}",
                        title=item.get("title", ""),
                        url=item.get("link", ""),
                        snippet=item.get("snippet", ""),
                        source="google",
                        display_link=item.get("displayLink", ""),
                        formatted_url=item.get("formattedUrl", ""),
                    )
                    search_results.append(result)

            # Format results based on requested format
            if "json" == "json":
                formatted_content = {
                    "query": validated_query,
                    "results": [result.model_dump() for result in search_results],
                    "count": len(search_results),
                }

                message_content = formatted_content
            elif output_format.lower() == "text":
                if search_results:
                    result_lines = []
                    for i, result in enumerate(search_results, 1):
                        result_lines.append(f"{i}. {result.title}")
                        result_lines.append(f"   URL: {result.url}")
                        result_lines.append(f"   Summary: {result.snippet}")
                        result_lines.append("")  # Empty line
                    message_content = "\n".join(result_lines)
                else:
                    message_content = f"No results found for: {validated_query}"
            else:  # markdown (default)
                message_content = self._format_search_results_for_llm(search_results, validated_query)

            # Prepare metadata
            metadata = SearchMetadata(
                query=validated_query,
                search_engine="google",
                total_results=len(search_results),
                search_time=search_time,
                language=language,
                country=country,
                safe_search=safe_search,
                api_quota_used=True,
            )

            self._color_log(f"✅ Found {len(search_results)} results in {search_time:.2f}s", Color.green)

            return ActionResponse(success=True, message=message_content, metadata=metadata.model_dump())

        except requests.exceptions.RequestException as e:
            error_msg = f"Google Search API request failed: {str(e)}"
            self.logger.error(f"Search API error: {traceback.format_exc()}")

            metadata = SearchMetadata(
                query=query, search_engine="google", total_results=0, error_type="api_request_failed"
            )

            self._color_log(f"❌ {error_msg}", Color.red)

            return ActionResponse(success=False, message=error_msg, metadata=metadata.model_dump())

        except ValueError as e:
            error_msg = f"Invalid search parameters: {str(e)}"

            metadata = SearchMetadata(
                query=query, search_engine="google", total_results=0, error_type="invalid_parameters"
            )

            self._color_log(f"❌ {error_msg}", Color.red)

            return ActionResponse(success=False, message=error_msg, metadata=metadata.model_dump())

        except Exception as e:
            error_msg = f"Search operation failed: {str(e)}"
            error_trace = traceback.format_exc()

            self.logger.error(f"Unexpected search error: {error_trace}")

            metadata = SearchMetadata(
                query=query, search_engine="google", total_results=0, error_type="unexpected_error"
            )

            self._color_log(f"❌ {error_msg}", Color.red)

            return ActionResponse(
                success=False, message=f"{error_msg}\n\nError details: {error_trace}", metadata=metadata.model_dump()
            )

    def mcp_get_search_capabilities(self) -> ActionResponse:
        """Get information about search service capabilities and configuration.

        Returns:
            ActionResponse with search service capabilities and current configuration
        """
        capabilities = {
            "search_engines": ["Google Custom Search API"],
            "supported_features": [
                "Web search with customizable result count",
                "Safe search filtering",
                "Language and country localization",
                "Multiple output formats (markdown, json, text)",
                "LLM-optimized result formatting",
                "Detailed metadata tracking",
            ],
            "supported_formats": ["markdown", "json", "text"],
            "configuration": {
                "google_api_configured": bool(self.google_api_key and self.google_cse_id),
                "max_results_per_query": 10,
                "default_language": "en",
                "default_country": "us",
                "safe_search_default": True,
            },
            "limitations": [
                "Google CSE has daily quota limits",
                "Maximum 10 results per query",
                "Requires valid API credentials",
            ],
        }

        formatted_info = f"""# Search Service Capabilities

        ## Available Search Engines
        {chr(10).join(f"- {engine}" for engine in capabilities["search_engines"])}

        ## Features
        {chr(10).join(f"- {feature}" for feature in capabilities["supported_features"])}

        ## Supported Output Formats
        {chr(10).join(f"- {fmt}" for fmt in capabilities["supported_formats"])}

        ## Current Configuration
        - **Google API Configured:** {capabilities["configuration"]["google_api_configured"]}
        - **Max Results Per Query:** {capabilities["configuration"]["max_results_per_query"]}
        - **Default Language:** {capabilities["configuration"]["default_language"]}
        - **Default Country:** {capabilities["configuration"]["default_country"]}
        - **Safe Search Default:** {capabilities["configuration"]["safe_search_default"]}

        ## Limitations
        {chr(10).join(f"- {limitation}" for limitation in capabilities["limitations"])}
        """

        return ActionResponse(success=True, message=formatted_info, metadata=capabilities)


# Example usage and entry point
if __name__ == "__main__":
    load_dotenv()

    # Default arguments for testing
    args = ActionArguments(
        name="search_service",
        transport="stdio",
        workspace=os.getenv("AWORLD_WORKSPACE", "~"),
    )

    # Initialize and run the search service
    try:
        service = SearchCollection(args)
        service.run()
    except Exception as e:
        print(f"An error occurred: {e}: {traceback.format_exc()}")