pip install -e .

pip install mcp httpx beautifulsoup4 lxml pydantic python-dotenv

import asyncio
from search_plugin import WebSearchPlugin, SearchConfig, SearchBackend

async def main():
    config = SearchConfig(
        backend=SearchBackend.SEARXNG,
        max_results=10,
    )
    
    async with WebSearchPlugin(config) as plugin:
        # Get Markdown output (default)
        results = await plugin.search("Python async programming")
        print(results)
        
        # Get JSON output
        results_json = await plugin.search("Python async programming", output_format="json")
        print(results_json)
        
        # Get dict object
        results_dict = await plugin.search("Python async programming", output_format="dict")
        print(results_dict["results"])

asyncio.run(main())

# Basic search
python -m search_plugin "Python async programming"

# With options
python -m search_plugin "machine learning" --max-results 5 --backend duckduckgo --format json

# Run as MCP server
python -m search_plugin --mcp

- id: mcp-web-search
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    transport: stdio
    serverName: web_search
    command: python
    args: ["-m", "search_plugin"]
    cwd: /path/to/mcp-web-search
    env:
      PATH: /usr/local/bin:/usr/bin:/bin
    toolCallTimeoutMs: 60000
    startupTimeoutMs: 15000
    maxInstructionBytes: 32768
    failOnStartupError: false
    reconnect:
      enabled: true
      initialDelayMs: 500
      maxDelayMs: 30000
      maxAttempts: 10

# Override SearXNG instances (comma-separated)
export SEARXNG_INSTANCES="https://my-searxng.example.com,https://backup.example.com"

# Custom timeout
export SEARCH_TIMEOUT=60

# Default max results
export SEARCH_MAX_RESULTS=20

docker run -d -p 8080:8080 searxng/searxng

config = SearchConfig(searxng_instances=["http://localhost:8080"])

# Search Results for: `Python async`
**Backend:** searxng  |  **Results:** 3  |  **Time:** 245ms

1. **[asyncio — Python 3.12 documentation](https://docs.python.org/3/library/asyncio.html)**
   The asyncio module provides infrastructure for writing single-threaded concurrent code...
   *Source: google*

{
  "query": "Python async",
  "results": [
    {
      "url": "https://docs.python.org/3/library/asyncio.html",
      "title": "asyncio — Python 3.12 documentation",
      "snippet": "The asyncio module provides...",
      "source_engine": "google",
      "position": 1,
      "score": 0.95
    }
  ],
  "truncated": false,
  "total_results": 42,
  "search_time_ms": 245.3,
  "backend_used": "searxng"
}

response = await plugin.search("query")
if response.error:
    print(f"Search warning: {response.error}")

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=search_plugin --cov-report=html