duckduckgo-tool/
├── duckduckgo_server.py             # Main MCP server entry point
├── pyproject.toml
├── Dockerfile
├── README.md
├── pytest.ini
├── tests/
│   ├── __init__.py
│   └── test_search_tools.py
└── src/
    └── duckduckgo_browser/
        ├── __init__.py
        ├── __main__.py              # python -m duckduckgo_browser
        ├── duckduckgo_server.py     # stub (canonical server is at root)
        ├── services/
        │   ├── __init__.py
        │   ├── search_engine.py     # RealSearchEngine — DuckDuckGo Lite
        │   └── web_scraper.py       # DuckDuckGoScraper with retry & cache
        └── tools/
            ├── __init__.py
            ├── toolhandler.py       # Abstract base class
            └── search_tools.py     # get_internet_result tool handler

Answer: Machine learning is a branch of artificial intelligence that enables systems to learn
        and improve from experience without being explicitly programmed.
Source 1: https://www.ibm.com/topics/machine-learning
Source 2: https://www.google.com/search?q=what+is+machine+learning

# Create and activate virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

# Install dependencies
pip install -e .

duckduckgo-mcp --mode stdio

duckduckgo-mcp --mode sse --host 0.0.0.0 --port 8000

duckduckgo-mcp --mode streamable-http --host 0.0.0.0 --port 8000

# Build
docker build -t duckduckgo-mcp .

# Run streamable-http (default)
docker run -p 8000:8000 duckduckgo-mcp

# Run SSE mode
docker run -e TRANSPORT_TYPE=sse -e APP_PORT=8000 -p 8000:8000 duckduckgo-mcp

# Run with custom port
docker run -e TRANSPORT_TYPE=streamable-http -e APP_PORT=9000 -p 9000:9000 duckduckgo-mcp

# Run stdio mode (pipe-based)
docker run -i -e TRANSPORT_TYPE=stdio duckduckgo-mcp

{
  "mcpServers": {
    "duckduckgo": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

{
  "mcpServers": {
    "duckduckgo": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

{
  "mcpServers": {
    "duckduckgo": {
      "command": "duckduckgo-mcp",
      "args": ["--mode", "stdio"]
    }
  }
}

User Query
    ↓
get_internet_result (async tool handler)
    ↓
RealSearchEngine.search()
    ↓
DuckDuckGoScraper.search_with_retry()
    ├─ Check in-memory cache (5-min TTL)
    ├─ Cache hit  → return cached results
    └─ Cache miss → fetch from DuckDuckGo Lite
        ├─ Attempt 1 (10s timeout)
        ├─ Fail → wait 2s → Attempt 2
        ├─ Fail → wait 4s → Attempt 3
        └─ All fail → return stale cache or empty result
    ↓
Auto-detect category from result content
    ↓
Format: Answer + Source 1 + Source 2

# Streamable HTTP deployment
env:
  - name: TRANSPORT_TYPE
    value: "streamable-http"
  - name: APP_PORT
    value: "8000"
  - name: APP_HOST
    value: "0.0.0.0"

# SSE deployment
env:
  - name: TRANSPORT_TYPE
    value: "sse"
  - name: APP_PORT
    value: "8000"
  - name: APP_HOST
    value: "0.0.0.0"

pip install pytest pytest-asyncio
pytest

duckduckgo-mcp --mode streamable-http --port 8001

pip install -e . --force-reinstall

DuckDuckGoScraper(
    timeout=10.0,           # Request timeout per attempt (seconds)
    max_retries=3,          # Number of retry attempts
    retry_backoff_base=2.0, # Exponential backoff base (2s, 4s, ...)
    cache_ttl=300,          # Cache TTL in seconds (5 minutes)
)