WebSearch Forge MCP

Легковесный унифицированный WebSearch MCP для AI-агентов.

Ищите, читайте, обходите, парсите и исследуйте публичный веб через один MCP-сервер.

Быстрый старт · Инструменты · Архитектура · Настройка движков · 中文文档

Что это такое

WebSearch Forge MCP — это автономный MCP-сервис для веб-исследований, управляемых агентами:

Question → search sources → fetch pages → extract content → crawl related pages → compile evidence

Он разделён на чёткие слои:

• transports предоставляет MCP stdio и опциональный адаптер FastAPI.

• core отвечает за конфигурацию, кэширование, проверки безопасности, оркестрацию и исследовательские рабочие процессы.

• providers реализуют функции поиска, загрузки, извлечения, обхода и работы с медиа.

• SearXNG — единственный поисковый шлюз для Bing, Baidu, Brave, DuckDuckGo и других настроенных движков.

Related MCP server: hidrix-tools

Ключевые возможности

Один MCP-сервер, шесть возможностей

Подключитесь один раз к transports/mcp_stdio.py:

Единый поисковый шлюз

Аргумент engines передаётся в SearXNG как фильтр. WebSearch Forge не выполняет самостоятельный обход поисковых сайтов:

WebSearch Forge MCP → SearXNG → Bing / Baidu / Brave / DuckDuckGo

Лёгкость по умолчанию

MCP stdio не требует открытого порта приложения или сервера базы данных. Кэш — SQLite. Опциональные пакеты добавляют Trafilatura, Readability, stealth-запросы, Playwright, парсинг Office/PDF, Scrapy, субтитры YouTube и FastAPI без изменения MCP-контракта.

Ограниченный обход

crawl_site поддерживает нативный бэкенд без зависимостей и опциональный бэкенд Scrapy. Он ограничивает количество страниц и глубину, остаётся на исходном хосте, разрешает относительные ссылки и изолирует сбои страниц.

Быстрый старт

Следующие команды предназначены для Windows PowerShell.

Установка

cd D:\my-websearch\my_websearch
py -3.12 -m pip install -r requirements.txt

Запуск SearXNG

docker version
cd D:\my-websearch\my_websearch
docker compose up -d searxng
docker compose ps

Шлюз по умолчанию — http://127.0.0.1:8080. Конфигурация находится в config/searxng/settings.yml.

Настройка MCP-клиента

Используйте mcp_config.example.json и укажите абсолютный путь:

{
  "mcpServers": {
    "websearch-forge": {
      "command": "py",
      "args": [
        "-3.12",
        "D:\\my-websearch\\my_websearch\\transports\\mcp_stdio.py"
      ],
      "env": {
        "SEARXNG_URL": "http://127.0.0.1:8080",
        "CACHE_TTL": "300"
      }
    }
  }
}

Адаптер stdio принудительно включает UTF-8 в Windows. Loopback-трафик по умолчанию обходит системные прокси-переменные; при необходимости задайте PROXY_URL явно.

Инструменты

search_web

Поиск через SearXNG без загрузки тел страниц.

{
  "name": "search_web",
  "arguments": {
    "query": "Python 3.14 new features",
    "engines": ["bing", "baidu", "brave"],
    "limit": 5,
    "time_range": "month"
  }
}

fetch_web_content

Загрузка и извлечение одного публичного URL. Поддерживаются HTML, PDF, DOCX, XLSX, PPTX, CSV, Markdown и обычный текст.

{
  "name": "fetch_web_content",
  "arguments": {
    "url": "https://www.python.org",
    "max_chars": 10000,
    "stealth_mode": "off",
    "render_mode": "auto",
    "extraction_mode": "auto"
  }
}

Ответ включает финальный URL, HTTP-статус, заголовок, метод извлечения, количество слов, содержимое и обнаруженные ссылки.

search_and_fetch

Сначала поиск, затем независимая загрузка лучших результатов. Неудачная страница фиксируется в соответствующем элементе и не отменяет весь пакет.

{
  "name": "search_and_fetch",
  "arguments": {
    "query": "FastAPI MCP server",
    "limit": 3,
    "max_chars": 12000
  }
}

deep_research

Параллельный запуск связанных запросов, загрузка наиболее релевантных результатов и возврат отчёта в Markdown с указанием сбоев на уровне источников.

{
  "name": "deep_research",
  "arguments": {
    "queries": ["SearXNG engine configuration", "MCP stdio deployment"],
    "breadth": 3,
    "max_chars": 12000
  }
}

crawl_site

Обход сайта с жёсткими ограничениями по количеству страниц и глубине.

{
  "name": "crawl_site",
  "arguments": {
    "url": "https://www.python.org",
    "max_pages": 10,
    "max_depth": 2,
    "backend": "native",
    "stealth_mode": "off"
  }
}

native используется по умолчанию. Установите Scrapy и задайте backend со значением scrapy, чтобы использовать опциональный бэкенд. Каждая страница сообщает URL, глубину, статус, метод загрузки, заголовок, содержимое и количество слов.

youtube_transcript

Получение субтитров YouTube с опциональными языками источника и перевода.

Формат ответа

{
  "query": "OpenAI",
  "provider": "searxng",
  "engines": ["bing", "baidu", "brave"],
  "total_results": 3,
  "results": [
    {
      "title": "OpenAI | Research & Deployment",
      "url": "https://openai.com/",
      "description": "...",
      "source": "openai.com",
      "engine": "bing",
      "score": 1.0
    }
  ],
  "partial_failures": []
}

Успешные частичные результаты сохраняются. Ошибки движков, страниц и документов возвращаются в виде структурированных записей о сбоях.

Архитектура

flowchart LR
    A[Agent / MCP Client] -->|stdio JSON-RPC| B[transports/mcp_stdio.py]
    B --> C[core/service.py]
    C --> D[providers/search]
    D --> E[SearXNG]
    E --> F[Bing / Baidu / Brave / DDG]
    C --> G[providers/content]
    G --> H[HTTP / stealth / Playwright]
    C --> I[providers/crawl]
    C --> J[providers/media]
    C --> K[(SQLite TTL cache)]

• transports адаптирует протоколы; MCP и FastAPI используют один и тот же сервис.

• core отвечает за оркестрацию, политику кэширования, конфигурацию и безопасность URL.

• providers/search взаимодействует с SearXNG и проверяет имена движков.

• providers/content обрабатывает HTTP, stealth-транспорт, рендеринг и извлечение.

• providers/crawl содержит нативный и Scrapy-бэкенды обхода.

• providers/media содержит провайдер субтитров YouTube.

Настройка поисковых движков

Исходный код SearXNG, принадлежащий проекту:

config/searxng/settings.yml

Два параметра определяют, можно ли вызывать движок:

1. settings.yml включает движок внутри SearXNG.

2. providers/search/registry.py перечисляет принятое имя в SUPPORTED_ENGINES.

Перезапустите после изменений:

cd D:\my-websearch\my_websearch
docker compose up -d --force-recreate searxng

Если SearXNG ещё не предоставляет движок, сначала реализуйте этот движок SearXNG.

Безопасность и надёжность

• Принимаются только URL с протоколами HTTP и HTTPS.

• Цели localhost, loopback, частные IPv4, link-local и частные IPv6 отклоняются.

• Адреса перенаправлений проверяются повторно.

• Операции поиска и загрузки используют SQLite-кэш с TTL, по умолчанию 300 секунд.

• Частичные сбои не отбрасывают успешную работу.

• stdout зарезервирован для MCP JSON-RPC.

Дополнительные возможности

Структура проекта

my_websearch/
├── assets/                     # Project logo
├── config/searxng/             # SearXNG settings.yml
├── core/                       # Config, cache, security, orchestration
├── providers/
│   ├── search/                 # SearXNG gateway and engine allow-list
│   ├── content/                # Requests, rendering, extraction
│   ├── crawl/                  # Native and Scrapy backends
│   └── media/                  # YouTube transcript provider
├── transports/                 # MCP stdio and FastAPI adapters
├── tests/                      # Dependency-free self-checks
├── docker-compose.yml          # Local SearXNG gateway
├── mcp_config.example.json     # MCP client template
├── requirements.txt            # Dependency entry point
├── README.md                  # English documentation
└── README.zh-CN.md            # 中文文档

Проверка разработки

cd D:\my-websearch
py -3.12 -m my_websearch.tests.test_server

Ожидаемый вывод:

my_websearch self-check: ok

Опциональный сервис FastAPI:

cd D:\my-websearch\my_websearch
py -3.12 -m transports.api

Затем откройте http://127.0.0.1:8787/docs.

Лицензия

Лицензия пока не установлена. Добавьте файл LICENSE в корень проекта перед публичным распространением.