A production-ready server with DDGS metasearch integration and MCP (Model Context Protocol) support. A production-ready server with DDGS metasearch integration and MCP (Model Context Protocol) support.

ddgs-server/
├── main.py                 # FastAPI app initialization and router registration
├── mcp_server.py          # MCP server with search tools for LLMs
├── mcp_server.py          # MCP server with search tools for LLMs
├── models/                 # Data models and schemas
│   ├── __init__.py
│   └── schemas.py         # Pydantic models and enums
├── controllers/           # Business logic layer
│   ├── __init__.py
│   ├── text_controller.py
│   ├── image_controller.py
│   ├── video_controller.py
│   ├── news_controller.py
│   ├── book_controller.py
│   └── unified_controller.py  # Searches all sources at once
├── routes/                # API route definitions
│   ├── __init__.py
│   ├── text_routes.py
│   ├── image_routes.py
│   ├── video_routes.py
│   ├── news_routes.py
│   ├── book_routes.py
│   └── unified_routes.py      # Unified search endpoint
└── public/

# Create project directory
mkdir ddgs-server
cd ddgs-server

# Install dependencies
pip install -r requirements.txt

# Save the main.py file from the generated code
# Then run:
uvicorn main:app --reload --host 0.0.0.0 --port 8000

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• API Root: http://localhost:8000
• MCP Server: http://localhost:8000/mcp

This server includes an integrated MCP (Model Context Protocol) server that provides LLM-friendly search tools. The MCP server is mounted at /mcp and exposes the following tools:

• search_web - Search the web for text content
• search_images - Search for images with size/color filters
• search_videos - Search for videos with resolution/duration filters
• search_news - Search for news articles with time limits
• search_books - Search for books
• search_everything - Search all sources at once (parallel)
• fetch_content - Extract content from a single URL
• fetch_multiple_contents - Extract content from multiple URLs (max 10)

The MCP server reuses all existing controller logic, making it efficient and maintainable. It's accessible at /mcp/mcp for LLM clients that support the MCP protocol.

This server includes an integrated MCP (Model Context Protocol) server that provides LLM-friendly search tools. The MCP server is mounted at /mcp and exposes the following tools:

• search_web - Search the web for text content
• search_images - Search for images with size/color filters
• search_videos - Search for videos with resolution/duration filters
• search_news - Search for news articles with time limits
• search_books - Search for books
• search_everything - Search all sources at once (parallel)

The MCP server reuses all existing controller logic, making it efficient and maintainable. It's accessible at /mcp for LLM clients that support the MCP protocol.

Endpoint: GET /api/search/text

Parameters:

• q (required): Search query
• region (optional): Region code (default: us-en)
• safesearch (optional): on/moderate/off (default: moderate)
• timelimit (optional): d/w/m/y
• max_results (optional): 1-100 (default: 10)
• page (optional): Page number (default: 1)
• backend (optional): Search backend (default: auto)

Example:

curl "http://localhost:8000/api/search/text?q=python%20programming&max_results=5"

Response:

{
  "success": true,
  "query": "python programming",
  "results_count": 5,
  "results": [
    {
      "title": "Python Programming Language",
      "href": "https://www.python.org/",
      "body": "Official Python website..."
    }
  ]
}

Endpoint: GET /api/search/images

Additional Parameters:

• size: Small/Medium/Large/Wallpaper
• color: color/Monochrome/Red/Orange/Yellow/Green/Blue/Purple/Pink
• type_image: photo/clipart/gif/transparent/line
• layout: Square/Tall/Wide

Example:

curl "http://localhost:8000/api/search/images?q=butterfly&size=Large&color=color"

Endpoint: GET /api/search/videos

Additional Parameters:

• resolution: high/standard
• duration: short/medium/long
• license_videos: creativeCommon/youtube

Example:

curl "http://localhost:8000/api/search/videos?q=tutorial&resolution=high&duration=medium"

Endpoint: GET /api/search/news

Parameters:

• Same as text search
• timelimit limited to: d/w/m

Example:

curl "http://localhost:8000/api/search/news?q=technology&timelimit=w&max_results=20"

Endpoint: GET /api/search/books

Parameters:

• q (required): Search query
• max_results (optional): 1-100 (default: 10)
• page (optional): Page number

Example:

curl "http://localhost:8000/api/search/books?q=machine%20learning&max_results=15"

Endpoint: GET /api/content/fetch

Parameters:

• url (required): URL to fetch content from
• timeout (optional): Request timeout 5-30 seconds (default: 10)

Example:

curl "http://localhost:8000/api/content/fetch?url=https://example.com/article"

Response:

{
  "url": "https://example.com/article",
  "title": "Article Title",
  "description": "Meta description",
  "content": "Main article text...",
  "content_length": 5420,
  "status_code": 200
}

Endpoint: POST /api/content/fetch-multiple

Body:

{
  "urls": ["https://example.com/page1", "https://example.com/page2"],
  "timeout": 10
}

Example:

curl -X POST "http://localhost:8000/api/content/fetch-multiple" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/article1", "https://example.com/article2"]}'

import requests

# Text search
response = requests.get(
    "http://localhost:8000/api/search/text",
    params={
        "q":  tutorial",
        "region": "us-en",
        "max_results": 10
    }
)

data = response.json()
print(f"Found {data['results_count']} results")

for result in data['results']:
    print(f"- {result['title']}: {result['href']}")

// Image search
fetch('http://localhost:8000/api/search/images?q=nature&size=Large&max_results=20')
  .then(response => response.json())
  .then(data => {
    console.log(`Found ${data.results_count} images`);
    data.results.forEach(img => {
      console.log(img.title, img.image);
    });
  });

curl -X GET "http://localhost:8000/api/search/text?q=python&max_results=5" \
  -H "accept: application/json"

curl -X GET "http://localhost:8000/api/search/images?q=sunset&size=Large&color=Orange" \
  -H "accept: application/json"

curl -X GET "http://localhost:8000/api/search/news?q=AI&timelimit=w&max_results=10" \
  -H "accept: application/json"

# Build image
docker build -t ddgs-api .

# Run container
docker run -p 8000:8000 ddgs-api

# Start service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop service
docker-compose down

Create a .env file:

HOST=0.0.0.0
PORT=8000
LOG_LEVEL=info
DDGS_TIMEOUT=10
DDGS_PROXY=  # Optional proxy

Modify the DDGS initialization in main.py:

ddgs = DDGS(
    proxy="socks5h://127.0.0.1:9150",  # Tor browser
    timeout=10
)

1. Input Validation: Pydantic models validate all inputs
2. Rate Limit Handling: Proper HTTP 429 responses
3. Error Handling: Comprehensive exception handling
4. Type Safety: Full type hints throughout
5. Logging: Request logging for monitoring

{
  "success": true,
  "query": "search term",
  "results_count": 10,
  "results": [...]
}

{
  "success": false,
  "error": "Error message",
  "details": "Additional error details"
}

Add CORS middleware for cross-origin requests:

from.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Install and add rate limiting:

pip install slowapi

from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter

@app.get("/api/search/text")
@limiter.limit("30/minute")
async def search_text(...):
    ...

1. Use multiple workers:

   uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000

2. Set up reverse proxy (Nginx example):

   location / {
       proxy_pass http://localhost:8000;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
   }

3. Enable HTTPS using Certbot/Let's Encrypt

4. Monitor with logging:

   • Use structured logging
   • Send logs to monitoring service

5. Use environment-based configuration

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY main.py .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

version: '3.8'

services:
  ddgs-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

# Health check
curl http://localhost:8000/health

# API root
curl http://localhost:8000/

# Text search
curl "http://localhost:8000/api/search/text?q=test&max_results=3"

✅ 5 Complete Search Endpoints

• Text/Web Search
• Image Search with filters
• Video Search with filters
• News Search
• Book Search

✅ Production Ready

• Auto-generated API documentation
• Input validation with Pydantic
• Comprehensive error handling
• Logging and monitoring
• Docker support

✅ Developer Friendly

• Type hints throughout
• Clear endpoint documentation
• Example client code
• Easy to extend

MIT License

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

For issues:

• Server*: Check the documentation at http://localhost:8000/docs
• DDGS Library: Visit https://pypi.org/project/ddgs/

Your DDGS server is now complete with:

• Full implementation in main.py
• Test client in test_client.py
• Docker configuration
• Comprehensive documentation
• Production-ready features

Start the server and visit http://localhost:8000/docs to explore the interactive API documentation!