# MCP сервер для поиска информации через DuckDuckGo Search

Этот MCP сервер предоставляет инструменты для поиска информации в интернете с использованием библиотеки DDGS (DuckDuckGo Search).

## Установка

### Требования

- Python 3.8+
- `uv` (https://github.com/astral-sh/uv) - рекомендуется для управления зависимостями
- Или стандартный `pip` и `venv`

### Шаги установки

1.  **Клонируйте репозиторий или создайте папку проекта:**
    ```bash
    mkdir duck_duck_MCP
    cd duck_duck_MCP
    ```

2.  **(Рекомендуется) Создайте виртуальное окружение:**
    ```bash
    # С uv
    uv venv
    # Активируйте (Windows)
    venv\Scripts\activate
    # Активируйте (Linux/macOS)
    source .venv/bin/activate
    ```
    *Примечание: Если вы используете `uv`, он автоматически создаст и активирует `.venv` при первом запуске `uv pip install`.*

3.  **Установите зависимости:**
    ```bash
    # С uv (рекомендуется)
    uv pip install -r requirements.txt
    # Или с pip
    pip install -r requirements.txt
    ```
    *Примечание: `ddgs` - это библиотека для работы с DuckDuckGo Search.*

## Поддерживаемые методы MCP

Сервер реализует следующие методы протокола MCP:

- `initialize` - Инициализация сервера
- `tools/list` - Получение списка доступных инструментов
- `tools/call` - Вызов инструмента

## Доступные инструменты

### `get_search_operators`
Получить документацию по операторам поиска DDG

**Параметры:** нет

### `search_text`
Текстовый поиск через DDGS

**Параметры:**
- `query` (обязательный): Поисковый запрос
- `region`: Регион (us-en, uk-en, ru-ru, и т.д.) - по умолчанию "us-en"
- `safesearch`: Уровень фильтрации (on, moderate, off) - по умолчанию "moderate"
- `timelimit`: Ограничение по времени (d, w, m, y)
- `max_results`: Максимальное количество результатов - по умолчанию 10
- `page`: Номер страницы результатов - по умолчанию 1
- `backend`: Поисковые движки (auto, google, bing, и т.д.) - по умолчанию "auto"

### `search_images`
Поиск изображений через DDGS

**Параметры:**
- `query` (обязательный): Поисковый запрос
- `region`: Регион - по умолчанию "us-en"
- `safesearch`: Уровень фильтрации (on, moderate, off) - по умолчанию "moderate"
- `timelimit`: Ограничение по времени (d, w, m, y)
- `max_results`: Максимальное количество результатов - по умолчанию 10
- `page`: Номер страницы результатов - по умолчанию 1
- `backend`: Поисковые движки - по умолчанию "auto"
- `size`: Размер изображения (Small, Medium, Large, Wallpaper)
- `color`: Цвет изображения (color, Monochrome, Red, и т.д.)
- `type_image`: Тип изображения (photo, clipart, gif, и т.д.)
- `layout`: Макет изображения (Square, Tall, Wide)
- `license_image`: Лицензия изображения (any, Public, Share, и т.д.)

### `search_videos`
Поиск видео через DDGS

**Параметры:**
- `query` (обязательный): Поисковый запрос
- `region`: Регион - по умолчанию "us-en"
- `safesearch`: Уровень фильтрации (on, moderate, off) - по умолчанию "moderate"
- `timelimit`: Ограничение по времени (d, w, m)
- `max_results`: Максимальное количество результатов - по умолчанию 10
- `page`: Номер страницы результатов - по умолчанию 1
- `backend`: Поисковые движки - по умолчанию "auto"
- `resolution`: Разрешение видео (high, standard)
- `duration`: Длительность видео (short, medium, long)
- `license_videos`: Лицензия видео (creativeCommon, youtube)

### `search_news`
Поиск новостей через DDGS

**Параметры:**
- `query` (обязательный): Поисковый запрос
- `region`: Регион - по умолчанию "us-en"
- `safesearch`: Уровень фильтрации (on, moderate, off) - по умолчанию "moderate"
- `timelimit`: Ограничение по времени (d, w, m)
- `max_results`: Максимальное количество результатов - по умолчанию 10
- `page`: Номер страницы результатов - по умолчанию 1
- `backend`: Поисковые движки - по умолчанию "auto"

### `search_books`
Поиск книг через DDGS

**Параметры:**
- `query` (обязательный): Поисковый запрос
- `max_results`: Максимальное количество результатов - по умолчанию 10
- `page`: Номер страницы результатов - по умолчанию 1
- `backend`: Поисковые движки - по умолчанию "auto"

## Примеры использования

### Текстовый поиск
```json
{
  "method": "search_text",
  "params": {
    "query": "python programming",
    "max_results": 5,
    "region": "us-en"
  }
}
```

### Поиск изображений
```json
{
  "method": "search_images",
  "params": {
    "query": "cats",
    "max_results": 10,
    "color": "Monochrome"
  }
}
```

### Получение операторов поиска
```json
{
  "method": "get_search_operators",
  "params": {}
}
```

## Операторы поиска DDG

- `cats dogs` - Результаты о cats или dogs
- `"cats and dogs"` - Результаты точного совпадения "cats and dogs"
- `cats -dogs` - Меньше упоминаний dogs в результатах
- `cats +dogs` - Больше упоминаний dogs в результатах
- `cats filetype:pdf` - PDF файлы о cats
- `dogs site:example.com` - Страницы о dogs с сайта example.com
- `cats -site:example.com` - Страницы о cats, исключая example.com
- `intitle:dogs` - Заголовок страницы содержит слово "dogs"
- `inurl:cats` - URL страницы содержит слово "cats"  

## Примеры конфигов
### Конфигурация для запуска напрямую 
```
{
  "mcpServers": {
    "ddg-stdio": {
      "disabled": true,
      "timeout": 60,
      "type": "stdio",
      "command": "python",
      "args": [
        "Path_To\\ddg_mcp_server.py"
      ],
      "env": {}
    }
  }
}
```
### Adding to Github Copilot in VS Code
1. Create a .vscode folder and create a file in it: mcp.json
2. Add the config:  
```
{
  "servers": {
    "ddg-stdio": {
      "type": "stdio",
      "command": "Path_TO\\duck_duck_MCP\\venv\\Scripts\\python.exe",
      "args": [
        "Path_TO\\duck_duck_MCP\\ddg_mcp_server.py"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

## Running in Opencode
Add the server according to the instructions with this config (this is the global version in the opencode.json file):  
```
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ddg-stdio": {
      "type": "local",
      "command": [
        "PATH_TO\\duck_duck_MCP\\venv\\Scripts\\python.exe",
        "PATH_TO\duck_duck_MCP\\ddg_mcp_server.py"
      ],
      "environment": {
        "PYTHONIOENCODING": "utf-8"
      },
      "enabled": true
    }
  }
}

```

### Конфигурация с использованием Python из venv (рекомендуется)

**Для Windows:**
```json
{
  "mcpServers": {
    "ddg-stdio": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "C:\\Users\\Igor\\Desktop\\duck_duck_MCP\\venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\Igor\\Desktop\\duck_duck_MCP\\ddg_mcp_server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

**Важно:**
- Замените `C:\\Users\\Igor\\Desktop\\duck_duck_MCP` на ваш реальный путь к проекту
- Используйте двойные обратные слashes (`\\`) в путях для Windows
- Убедитесь, что в venv установлены все зависимости: `pip install -r requirements.txt`
- Переменная окружения `PYTHONIOENCODING=utf-8` обязательна для правильной работы с кириллицей

**Для Linux/macOS:**
```json
{
  "mcpServers": {
    "ddg-stdio": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "/path/to/duck_duck_MCP/venv/bin/python",
      "args": ["/path/to/duck_duck_MCP/ddg_mcp_server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```
{
  "mcpServers": {
    "ddg-stdio": {
      "command": "Полный_путь_к_папке_duck_duck_MCP\\venv\\Scripts\\python.exe",
      "timeout": 120,
       "type": "stdio",
      "args": [
        "Полный_путь_к_папке_duck_duck_MCP\\ddg_mcp_server.py"
      ],
      "env": {},
      "active": true
    }
  }
}
```
*Замените `Полный_путь_к_папке_duck_duck_MCP` на реальный путь к вашему проекту. Например: `E:\\Users\\Igory\\Desktop\\duck_duck_MCP\\venv\\Scripts\\python.exe`*

## Обработка ошибок

Сервер может возвращать следующие ошибки:
- Превышение лимита запросов
- Таймаут запроса
- Общие ошибки поиска

## Поддержка прокси
Для использования прокси можно установить переменную окружения `DDGS_PROXY`:
```bash
export DDGS_PROXY="socks5h://user:password@1.2.3.4:8080"
```

---

# MCP Server for Information Search via DuckDuckGo Search

This MCP server provides tools for searching information on the internet using the DDGS (DuckDuckGo Search) library.

## Installation

### Requirements

- Python 3.8+
- `uv` (https://github.com/astral-sh/uv) - recommended for dependency management
- Or standard `pip` and `venv`

### Installation Steps

1.  **Clone the repository or create a project folder:**
    ```bash
    mkdir duck_duck_MCP
    cd duck_duck_MCP
    ```

2.  **(Recommended) Create a virtual environment:**
    ```bash
    # With uv
    uv venv
    # Activate (Windows)
    venv\Scripts\activate
    # Activate (Linux/macOS)
    source .venv/bin/activate
    ```
    *Note: If you use `uv`, it will automatically create and activate `.venv` when you first run `uv pip install`.*

3.  **Install dependencies:**
    ```bash
    # With uv (recommended)
    uv pip install -r requirements.txt
    # Or with pip
    pip install -r requirements.txt
    ```
    *Note: `ddgs` is a library for working with DuckDuckGo Search.*

## Supported MCP Methods

The server implements the following MCP protocol methods:

- `initialize` - Server initialization
- `tools/list` - Get list of available tools
- `tools/call` - Call tool

## Available Tools

### `get_search_operators`
Get documentation on DDG search operators

**Parameters:** none

### `search_text`
Text search via DDGS

**Parameters:**
- `query` (required): Search query
- `region`: Region (us-en, uk-en, ru-ru, etc.) - default "us-en"
- `safesearch`: Filtering level (on, moderate, off) - default "moderate"
- `timelimit`: Time limit (d, w, m, y)
- `max_results`: Maximum number of results - default 10
- `page`: Result page number - default 1
- `backend`: Search engines (auto, google, bing, etc.) - default "auto"

### `search_images`
Image search via DDGS

**Parameters:**
- `query` (required): Search query
- `region`: Region - default "us-en"
- `safesearch`: Filtering level (on, moderate, off) - default "moderate"
- `timelimit`: Time limit (d, w, m, y)
- `max_results`: Maximum number of results - default 10
- `page`: Result page number - default 1
- `backend`: Search engines - default "auto"
- `size`: Image size (Small, Medium, Large, Wallpaper)
- `color`: Image color (color, Monochrome, Red, etc.)
- `type_image`: Image type (photo, clipart, gif, etc.)
- `layout`: Image layout (Square, Tall, Wide)
- `license_image`: Image license (any, Public, Share, etc.)

### `search_videos`
Video search via DDGS

**Parameters:**
- `query` (required): Search query
- `region`: Region - default "us-en"
- `safesearch`: Filtering level (on, moderate, off) - default "moderate"
- `timelimit`: Time limit (d, w, m)
- `max_results`: Maximum number of results - default 10
- `page`: Result page number - default 1
- `backend`: Search engines - default "auto"
- `resolution`: Video resolution (high, standard)
- `duration`: Video duration (short, medium, long)
- `license_videos`: Video license (creativeCommon, youtube)

### `search_news`
News search via DDGS

**Parameters:**
- `query` (required): Search query
- `region`: Region - default "us-en"
- `safesearch`: Filtering level (on, moderate, off) - default "moderate"
- `timelimit`: Time limit (d, w, m)
- `max_results`: Maximum number of results - default 10
- `page`: Result page number - default 1
- `backend`: Search engines - default "auto"

### `search_books`
Book search via DDGS

**Parameters:**
- `query` (required): Search query
- `max_results`: Maximum number of results - default 10
- `page`: Result page number - default 1
- `backend`: Search engines - default "auto"

## Usage Examples

### Text Search
```json
{
  "method": "search_text",
  "params": {
    "query": "python programming",
    "max_results": 5,
    "region": "us-en"
  }
}
```

### Image Search
```json
{
  "method": "search_images",
  "params": {
    "query": "cats",
    "max_results": 10,
    "color": "Monochrome"
  }
}
```

### Getting Search Operators
```json
{
  "method": "get_search_operators",
  "params": {}
}
```

## DDG Search Operators

- `cats dogs` - Results about cats or dogs
- `"cats and dogs"` - Exact match results for "cats and dogs"
- `cats -dogs` - Fewer mentions of dogs in results
- `cats +dogs` - More mentions of dogs in results
- `cats filetype:pdf` - PDF files about cats
- `dogs site:example.com` - Pages about dogs from example.com
- `cats -site:example.com` - Pages about cats, excluding example.com
- `intitle:dogs` - Page title contains the word "dogs"
- `inurl:cats` - Page URL contains the word "cats"

## Configuration Examples
### Configuration for Direct Launch
```json
{
  "mcpServers": {
    "ddg-stdio": {
      "command": "python",
      "timeout": 120,
       "type": "stdio",
      "args": [
        "Path_to_duck_duck_MCP_folder\\ddg_mcp_server.py"
      ],
      "env": {},
      "active": true
    }
  }
}
```

### Configuration Using Python from venv (Recommended)
```json
{
  "mcpServers": {
    "ddg-stdio": {
      "command": "Full_path_to_duck_duck_MCP_folder\\venv\\Scripts\\python.exe",
      "timeout": 120,
       "type": "stdio",
      "args": [
        "Full_path_to_duck_duck_MCP_folder\\ddg_mcp_server.py"
      ],
      "env": {},
      "active": true
    }
  }
}
```
*Replace `Full_path_to_duck_duck_MCP_folder` with the actual path to your project. For example: `E:\\Users\\Igory\\Desktop\\duck_duck_MCP\\venv\\Scripts\\python.exe`*

## Error Handling

The server may return the following errors:
- Request limit exceeded
- Request timeout
- General search errors

## Proxy Support

To use a proxy, you can set the `DDGS_PROXY` environment variable:
```bash
export DDGS_PROXY="socks5h://user:password@1.2.3.4:8080"
```