web-search-searxng-mcp 0.1.0__py3-none-any.whl

web_search_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""
+Web Search MCP Package.
+"""

web_search_mcp/config/logging.py

@@ -0,0 +1,15 @@
+import sys
+from loguru import logger
+from web_search_mcp.config.settings import settings
+
+def configure_logging():
+    """
+    Configure application logging using loguru.
+    """
+    logger.remove()  # Remove default handler
+    
+    logger.add(
+        sys.stderr,
+        level=settings.LOG_LEVEL,
+        format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>"
+    )

web_search_mcp/config/settings.py

@@ -0,0 +1,19 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    """
+    Application settings.
+    """
+    app_version: str = Field(default="0.1.0", description="Application version")
+    SEARXNG_BASE_URL: str = "http://localhost:8080"
+    SEARXNG_TIMEOUT: int = 10
+    LOG_LEVEL: str = "INFO"
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=True
+    )
+
+settings = Settings()

web_search_mcp/domains/search/exceptions.py

@@ -0,0 +1,7 @@
+class SearchError(Exception):
+    """Base exception for search domain."""
+    pass
+
+class SearchProviderError(SearchError):
+    """Raised when the search provider fails."""
+    pass

web_search_mcp/domains/search/models.py

@@ -0,0 +1,19 @@
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+class SearchResult(BaseModel):
+    """
+    Represents a single search result from a search engine.
+    """
+    title: str = Field(..., description="Title of the search result")
+    url: str = Field(..., description="URL of the search result")
+    content: Optional[str] = Field(None, description="Snippet or content of the result")
+    engine: Optional[str] = Field(None, description="Source engine (e.g. google, bing)")
+
+class SearchResponse(BaseModel):
+    """
+    Represents a response containing a list of search results.
+    """
+    query: str = Field(..., description="The original search query")
+    results: List[SearchResult] = Field(default_factory=list, description="List of search results")
+    number_of_results: int = Field(0, description="Total number of results returned")

web_search_mcp/domains/search/services.py

@@ -0,0 +1,36 @@
+from typing import List, Protocol
+from loguru import logger
+from web_search_mcp.domains.search.models import SearchResponse, SearchResult
+
+class SearchClient(Protocol):
+    """Protocol for search clients."""
+    def search(self, query: str, limit: int) -> List[SearchResult]:
+        ...
+
+class SearchService:
+    """
+    Service for performing web searches.
+    """
+    def __init__(self, search_client: SearchClient):
+        self._search_client = search_client
+
+    def perform_search(self, query: str, limit: int = 10) -> SearchResponse:
+        """
+        Execute a search query and return formatted results.
+        """
+        logger.info(f"Performing search for query: '{query}' with limit: {limit}")
+        
+        try:
+            results = self._search_client.search(query, limit)
+            logger.debug(f"Search returned {len(results)} results")
+            
+            response = SearchResponse(
+                query=query,
+                results=results,
+                number_of_results=len(results)
+            )
+            return response
+            
+        except Exception as e:
+            logger.error(f"Search failed: {e}")
+            raise

web_search_mcp/entry_points/main.py

@@ -0,0 +1,10 @@
+from web_search_mcp.entry_points.mcp_server import mcp
+
+def main():
+    """
+    Main entry point for the Web Search MCP server.
+    """
+    mcp.run()
+
+if __name__ == "__main__":
+    main()

web_search_mcp/entry_points/mcp_server.py

@@ -0,0 +1,31 @@
+from fastmcp import FastMCP
+from web_search_mcp.infrastructure.clients.searxng import SearxNGClient
+from web_search_mcp.domains.search.services import SearchService
+from web_search_mcp.config.logging import configure_logging
+
+# Configure logging at module level or startup
+configure_logging()
+
+# Initialize MCP Server
+mcp = FastMCP("Web Search MCP")
+
+def get_search_service() -> SearchService:
+    """Dependency wiring for SearchService."""
+    client = SearxNGClient()
+    return SearchService(client)
+
+@mcp.tool()
+def web_search(query: str, limit: int = 10) -> str:
+    """
+    Perform a web search using the configured search engine (SearxNG).
+    
+    Args:
+        query: The search query string.
+        limit: Maximum number of results to return (default: 10).
+        
+    Returns:
+        A JSON string containing the search results.
+    """
+    service = get_search_service()
+    response = service.perform_search(query, limit)
+    return response.model_dump_json(indent=2)

web_search_mcp/infrastructure/clients/searxng.py

@@ -0,0 +1,77 @@
+import httpx
+from typing import List, Any, Dict
+from loguru import logger
+from web_search_mcp.config.settings import settings
+from web_search_mcp.domains.search.models import SearchResult
+from web_search_mcp.domains.search.exceptions import SearchProviderError
+
+class SearxNGClient:
+    """
+    Client for interacting with a SearxNG instance.
+    """
+    def __init__(self, base_url: str = settings.SEARXNG_BASE_URL, timeout: int = settings.SEARXNG_TIMEOUT):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def search(self, query: str, limit: int = 10) -> List[SearchResult]:
+        """
+        Perform a search query against SearxNG.
+        """
+        url = f"{self.base_url}/search"
+        params: Dict[str, Any] = {
+            "q": query,
+            "format": "json",
+            "categories": "general",
+            "language": "en-US",
+            "pageno": 1,
+        }
+        
+        # SearxNG doesn't strictly support 'limit' in params usually, it returns results per page.
+        # We can implement client-side slicing or try using 'time_range' etc if needed.
+        # But 'limit' isn't a standard param in all searxng instances, usually controlled by preferences.
+        # We will slice the result.
+
+        try:
+            logger.debug(f"Requesting {url} with params {params}")
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.get(url, params=params)
+                response.raise_for_status()
+                data = response.json()
+        except httpx.HTTPError as e:
+            logger.error(f"HTTP error communicating with SearxNG: {e}")
+            raise SearchProviderError(f"SearxNG communication error: {e}")
+        except Exception as e:
+            logger.error(f"Unexpected error communicating with SearxNG: {e}")
+            raise SearchProviderError(f"SearxNG unexpected error: {e}")
+
+        return self._parse_results(data, limit)
+
+    def _parse_results(self, data: Dict[str, Any], limit: int) -> List[SearchResult]:
+        """
+        Parse the raw JSON response from SearxNG into domain models.
+        """
+        raw_results = data.get("results", [])
+        parsed_results: List[SearchResult] = []
+
+        for result in raw_results:
+            if len(parsed_results) >= limit:
+                break
+                
+            # SearxNG result field mapping
+            title = result.get("title", "")
+            url = result.get("url", "")
+            content = result.get("content", "")
+            engine = result.get("engine", "")
+
+            # Basic validation
+            if not title or not url:
+                continue
+
+            parsed_results.append(SearchResult(
+                title=title,
+                url=url,
+                content=content,
+                engine=engine
+            ))
+
+        return parsed_results

web_search_searxng_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: web-search-searxng-mcp
+Version: 0.1.0
+Summary: Add your description here
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: fastmcp>=2.14.5
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.12.5
+Description-Content-Type: text/markdown
+
+# Step-by-Step Setup Guide for Web Search MCP
+
+This guide lists the specific steps to set up the Web Search MCP server and integrate it into your development environment or MCP clients (like Claude Desktop).
+
+## Prerequisites
+
+Before starting, ensure you have the following installed:
+
+1.  **Docker & Docker Compose**: For running the local SearxNG instance.
+2.  **uv**: An extremely fast Python package installer and resolver.
+    - Install instructions: [astral.sh/uv](https://github.com/astral-sh/uv)
+
+## Step 1: Installation & Setup
+
+1.  **Clone the Repository**
+    Clone this repository to a permanent location on your machine.
+    ```bash
+    git clone https://github.com/ViktoriaKutseva/web-search-mcp.git
+    cd web-search-mcp
+    ```
+
+2.  **Initialize Environment**
+    Use `uv` to sync dependencies (this creates the virtual environment).
+    ```bash
+    uv sync
+    ```
+
+## Step 2: Start the Search Engine
+
+The MCP server relies on a local instance of SearxNG.
+
+1.  **Configure SearxNG**
+    Copy the example settings file to create the actual configuration.
+    ```bash
+    cp searxng/settings.yml.example searxng/settings.yml
+    ```
+    *Note: The `settings.yml` file is git-ignored. You should generate a new `secret_key` inside it.*
+
+2.  **Start Services**
+    From the repository root run:
+    ```bash
+    docker compose up -d
+    ```
+
+3.  **Verify SearxNG**
+    Open your browser and navigate to `http://localhost:8080`. You should see the SearxNG search interface.
+
+## Step 3: Configure MCP Client
+
+To use this tool in other specific projects or global editors, you need to register it with your MCP Client (e.g., Claude Desktop, VS Code extension).
+
+### Option A: Integration with Claude Desktop
+
+1.  **Get Absolute Path**
+    Run `pwd` (Linux/macOS) or `cd` (Windows) in the repository root to get the full path.
+    *Example:* `/home/user/code/web-search-mcp`
+
+2.  **Locate Config File**
+    Find or create the `claude_desktop_config.json` file:
+    *   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+    *   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+3.  **Edit Configuration**
+    Add the `web-search` entry to the `mcpServers` object. Replace `/ABSOLUTE/PATH/TO/` with your actual path.
+
+    ```json
+    {
+      "mcpServers": {
+        "web-search": {
+          "command": "uv",
+          "args": [
+            "--directory",
+            "/ABSOLUTE/PATH/TO/web-search-mcp",
+            "run",
+            "web-search-mcp"
+          ],
+          "env": {
+            "SEARXNG_BASE_URL": "http://localhost:8080"
+          }
+        }
+      }
+    }
+    ```
+
+4.  **Restart Claude Desktop**
+    Completely quit and restart the application for changes to take effect.
+
+## Step 4: Verification
+
+1.  Open your MCP Client (e.g., Claude Desktop).
+2.  Look for the 🔌 icon or installed tools list to verify `web-search` is connected.
+3.  Ask a question that requires searching the web:
+    > "Search for the latest release of Python and tell me the date."
+
+## Troubleshooting
+
+-   **SearxNG not reachable**: Ensure Docker container is running (`docker ps`) and port 8080 is free.
+-   **MCP Error**: Check the logs in your client or run `uv run web-search-mcp` manually in the terminal to see if it starts without crashing (it will wait for stdio input).
+
+## Configuration
+
+Settings are managed via environment variables (or \`.env\` file):
+
+- \`SEARXNG_BASE_URL\`: URL of the SearxNG instance (default: \`http://localhost:8080\`)
+- \`SEARXNG_TIMEOUT\`: Request timeout in seconds (default: \`10\`)
+- \`LOG_LEVEL\`: Logging level (default: \`INFO\`)
+
+## Development
+
+- **Architecture**: Follows simplified DDD guidelines.
+  - \`domains/\`: Business logic
+  - \`infrastructure/\`: External implementations (SearxNG client)
+  - \`entry_points/\`: MCP server and Main execution
+  - \`config/\`: Settings

web_search_searxng_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+web_search_mcp/__init__.py,sha256=A4JxZsp9WlRXtH-kQui7vtBcHNwgnc0dYIFqGlDiXVI,32
+web_search_mcp/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+web_search_mcp/config/logging.py,sha256=YMWDWlvMgY7wBFm1D9Q8lWNjZrJemHIwsN6e3ZUqDwk,487
+web_search_mcp/config/settings.py,sha256=Nwr7ki7lWTpFTI224jaa_-_eIOLS_uqvtez41X-2SY0,511
+web_search_mcp/domains/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+web_search_mcp/domains/search/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+web_search_mcp/domains/search/exceptions.py,sha256=LEfFL6bw7GFpuneAAgkQ2_Ow_9vyUORG1aUyrkVmtQw,182
+web_search_mcp/domains/search/models.py,sha256=mKAwbYOaOOhg-ePmpDY_hPp4NrK6EcmFCd6zXH4sQjk,862
+web_search_mcp/domains/search/services.py,sha256=pyvIMUL1Dcm6NiIPCw5FRGUIPl2ZWhxAbwk8HP15Lfc,1176
+web_search_mcp/entry_points/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+web_search_mcp/entry_points/main.py,sha256=ZwXfjwCw8ZypZ69yMXtHkNBhDsdEHOcHVKLGhKqZP3s,189
+web_search_mcp/entry_points/mcp_server.py,sha256=VYG2vyUyX6VmPoISqu--miigF3YvHbA-hgO4qU8Q-So,984
+web_search_mcp/infrastructure/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+web_search_mcp/infrastructure/clients/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+web_search_mcp/infrastructure/clients/searxng.py,sha256=e5vSKtg-ghS4lKZk-az1TdjkzfduGmVjIzLGKc0bgLI,2873
+web_search_searxng_mcp-0.1.0.dist-info/METADATA,sha256=KyluNfSIbXz1pYtLzliakNEtrgPuljrWdxjme4Flg_w,4214
+web_search_searxng_mcp-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+web_search_searxng_mcp-0.1.0.dist-info/entry_points.txt,sha256=7Rd9zuUoxSVIoyImHlc71A2u45ee7IZnMGzQy0Q7piA,73
+web_search_searxng_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=Ndp2kFd74g3NmWTsArvM_oA5E4u8Qn_NH9QVEs5J8YM,1072
+web_search_searxng_mcp-0.1.0.dist-info/RECORD,,

web_search_searxng_mcp-0.1.0.dist-info/WHEEL

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

web_search_searxng_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+web-search-mcp = web_search_mcp.entry_points.main:main

web_search_searxng_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ViktoriaKutseva
+
+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.