Web Research MCP

Высококачественный MCP-сервер для веб-исследований из нескольких источников, предназначенный для ИИ-агентов. Подключите его к Claude Desktop, Hermes, Cursor или любому MCP-совместимому клиенту и получите поиск и загрузку страниц производственного уровня в Wikipedia, arXiv, Hacker News, Stack Exchange, Crossref, Brave, Tavily и на любом URL-адресе в интернете.

# One-line install (anywhere on disk)
git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research --command "$(pwd)/web-research-mcp/bin/web-research-mcp"
# 6 of 7 tools work with zero API keys. Add Brave or Tavily to unlock general web search.

Зачем это существует

Большинство MCP-серверов «веб-поиска» пытаются скрейпить Google через headless-браузер со случайными отпечатками. Такой подход — проигрышная гонка вооружений: поисковые системы обнаруживают и банят скрейперов в течение нескольких дней, а даже когда это работает, вы получаете «суп» из DOM, который вашей LLM приходится вычищать.

Этот сервер использует другой подход — он общается с API, которые созданы для агентов:

Все семь источников работают без каких-либо API-ключей. Добавление ключа Brave или Tavily открывает поиск по реальному веб-индексу в реальном времени. Это подход наивысшего качества — вы получаете лучшие результаты, чем при скрейпинге, потому что настоящие API веб-индекса используют сигналы (модели кликов, свежесть, анализ ссылок), которые не может воспроизвести ни один скрейпер.

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

Вариант A — pip install (когда будет опубликовано)

pip install web-research-mcp
hermes mcp add web-research --command "$(which web-research-mcp)"

Вариант B — Клонирование из исходников

git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research \
  --command "$(pwd)/bin/web-research-mcp"

При появлении запроса примите все 7 инструментов. Готово.

Вариант C — Установка с Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "web-research": {
      "command": "/Users/code/mcp-servers/web-research/bin/web-research-mcp"
    }
  }
}

Вариант D — Установка с Cursor / любым stdio MCP-клиентом

{
  "mcpServers": {
    "web-research": {
      "command": "/absolute/path/to/web-research-mcp/bin/web-research-mcp"
    }
  }
}

Скрипт запуска автоматически создаёт виртуальное окружение при первом запуске, устанавливает зависимости из pyproject.toml и подключает web-research.env для любых настроенных вами API-ключей.

2. (Необязательно) Добавьте API-ключи для реального веб-поиска

cp web-research.env.example web-research.env
$EDITOR web-research.env

Скрипт запуска подхватывает ключи из web-research.env при каждом вызове — перезапуск вашего MCP-клиента не требуется.

3. Используйте его

Задавайте агенту вопросы, например:

«Найди на Hacker News и Stack Overflow лучшие MCP-серверы, выпущенные в 2026 году»

«Используй pro_mode для исследования текущего состояния малых языковых моделей»

«Загрузи https://arxiv.org/abs/2506.06962 и резюмируй методологию»

«Сверь это утверждение с Wikipedia и arXiv»

Инструменты

Все 7 инструментов зарегистрированы в tools/list:

search_web — многоисточниковый общий веб-поиск

search_web(
    query: str,                  # search query
    max_results: int = 10,       # per source, before dedup (1–30)
    pro_mode: bool = False,      # also fetch top 3 URLs and append excerpts
) -> str

Работает на Brave + Tavily с дедупликацией по канонизации URL и повышением рейтинга при совпадении из нескольких источников. Требует BRAVE_API_KEY и/или TAVILY_API_KEY. Без ключей возвращает понятное сообщение о том, как их включить.

pro_mode: true — ключевая функция для исследований: она выполняет обычный поиск, загружает топ-3 результата через Jina и добавляет их содержимое в качестве сниппета. Один вызов заменяет то, что иначе потребовало бы search_web + 3 × fetch_url.

fetch_url — чистый markdown любой страницы

fetch_url(url: str) -> str

Идёт через Jina Reader, который:

• рендерит страницы с тяжёлым JS (SPA, React-приложения)

• обходит большинство систем защиты от ботов (Jina в белом списке)

• возвращает чистый markdown с блоком метаданных (Title:, URL Source:, Published Time:)

• обрезает до ~20 тыс. символов, чтобы защитить ваш контекст

search_wikipedia — энциклопедическая база

search_wikipedia(query: str, max_results: int = 5) -> str

Wikipedia MediaWiki API. Без ключа. Быстро. Лучше всего подходит для определений и исторического контекста.

search_academic — препринты arXiv

search_academic(query: str, max_results: int = 5) -> str

Возвращает название, авторов, фрагмент аннотации, дату публикации, URL PDF. Без ключа. Лучше всего для CS, физики, математики, био.

search_news — сигнал Hacker News

search_news(query: str, max_results: int = 10) -> str

Возвращает название, URL, очки, комментарии, дату. Без ключа. Лучше всего для того, что сейчас в тренде в технологиях.

search_stackexchange — Q&A с 180+ сайтов

search_stackexchange(query: str, max_results: int = 5, site: str = "stackoverflow") -> str

Установите site в любое сообщество SE: serverfault, superuser, askubuntu, math, tex, datascience, ai и т.д. Без ключа.

search_scholar_meta — рецензируемые статьи через Crossref

search_scholar_meta(query: str, max_results: int = 5) -> str

Возвращает название, DOI, количество цитирований, издателя, дату публикации, аннотацию. Охватывает статьи, которых нет в arXiv (Elsevier, Springer, Wiley, IEEE, ACM). Без ключа.

Архитектура

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│  (Claude Desktop, Hermes, Cursor, custom agent)          │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC over stdio
                     ▼
┌─────────────────────────────────────────────────────────┐
│              bin/web-research-mcp                         │
│  • Boots venv (or reuses cached one)                     │
│  • Sources web-research.env for API keys                 │
│  • Execs python -m web_research.server                   │
└────────────────────┬────────────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────────────┐
│           web_research.server (MCPServer)                 │
│  7 tool functions registered via @app.tool() decorator    │
│  • Pydantic-driven JSON schemas from type hints           │
│  • Single shared httpx.AsyncClient per call              │
│  • Graceful degradation: one bad source ≠ failed call    │
└────────────────────┬────────────────────────────────────┘
                     │ asyncio.gather for parallel fan-out
                     ▼
┌─────────────────────────────────────────────────────────┐
│          web_research.providers (7 backends)              │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ brave    │ │ tavily   │ │ jina_fetch  │  ← general web│
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ wikipedia│ │ arxiv    │ │ crossref    │  ← academic   │
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐                                │
│  │ hn_algolia│ │stackex   │  ← tech signal               │
│  └──────────┘ └──────────┘                                │
│  + merge_results() with URL-canonical dedup               │
└─────────────────────────────────────────────────────────┘

Ключевые проектные решения

API-первый, а не скрейпинг-первый. Это основная идея. Каждый источник — официальный API, предназначенный для программного доступа. Вы получаете чистые структурированные данные, без банов по IP, без затрат на обслуживание при редизайне сайтов.

Изоляция ошибок по источникам. Каждый провайдер оборачивает свой HTTP-вызов в try/except. Ошибка 429 от одного источника никогда не обрушивает весь поиск — вы получаете частичные результаты плюс понятное сообщение о том, какой источник не сработал.

Канонизация URL. merge_results() удаляет параметры отслеживания (utm_*, fbclid, gclid, ref) перед дедупликацией, нормализует регистр хоста, отбрасывает фрагменты. Когда Brave и Tavily возвращают одну и ту же статью, вы видите её один раз с also_found_in: [brave, tavily] и повышенным рейтингом.

Общий HTTP-клиент на вызов. httpx.AsyncClient с пулом соединений (max_connections=20), разумными таймаутами (по умолчанию 30s, 45s для fetch_url) и автоматическим следованием редиректам. Новый клиент на каждый вызов, потому что stdio MCP-серверы обрабатывают по одному запросу за раз, и мы хотим чистого состояния.

Без headless-браузеров. Никаких Playwright, Selenium, Puppeteer или ротации прокси. Меньше поверхность атаки, меньше зависимостей, нет следов JVM/Chrome. Jina берёт на себя тяжёлую работу на тех немногих сайтах, которым нужен рендеринг JS.

Сравнение с альтернативами

Тестирование

.venv/bin/python tests/e2e_protocol.py

Это запускает реальный сервер, выполняет настоящее рукопожатие MCP initialize + tools/list, затем делает живые JSON-RPC-вызовы ко всем инструментам и проверяет, что:

• Реальные API возвращают реальные данные (не заглушки)

• Ответ каждого инструмента имеет ожидаемую структуру

• Ошибочные состояния обрабатываются корректно

• search_web без ключей возвращает понятное сообщение «установите API-ключи»

Последний запуск: 7/7 инструментов проходят проверку на живых API.

Устранение неполадок

Сервер запускается, но инструменты не отображаются в моём MCP-клиенте

Проверьте hermes mcp list (или эквивалент). Сервер зарегистрирован с --command, что означает, что Hermes будет выполнять скрипт запуска напрямую. Убедитесь, что скрипт запуска исполняемый:

chmod +x bin/web-research-mcp

fetch_url возвращает усечённое содержимое

Это задумано — лимит в 20 тыс. символов защищает ваш контекст. Для более длинных материалов загрузите страницу самостоятельно и передайте выдержки в search_web для уточняющих вопросов, либо разбейте на разделы с помощью нескольких вызовов.

search_web возвращает «Нет результатов поиска. Вероятно, не настроен API-ключ»

Вам нужен хотя бы один из BRAVE_API_KEY или TAVILY_API_KEY, установленный в web-research.env. Остальные 6 инструментов (Wikipedia, arXiv, HN, Stack Exchange, Crossref, fetch_url) работают без ключей.

Stack Exchange возвращает 400 Bad Request

Если вы настроили пользовательский параметр filter, API отклоняет неизвестные ID фильтров. Используйте фильтр по умолчанию (опустите параметр) — он возвращает больше полей, чем нужно, но всё работает. Этот сервер использует значение по умолчанию.

Сервер падает при первом запуске

Проверьте stderr на фактическую трассировку. Частая причина: Python <3.10. Проверьте с помощью python3 --version.

Ограничения частоты запросов

У каждого API без ключа свои лимиты. Если вы их достигли:

• Wikipedia: ~200 запросов/мин, идентифицируйте себя реальным User-Agent (этот сервер отправляет его)

• arXiv: ~1 запрос/3с для неаутентифицированных, пожалуйста, снизьте частоту

• Hacker News Algolia: 10 тыс. запросов/час с API-ключом, 5 тыс. без

• Stack Exchange: 300 запросов/день без ключа (более чем достаточно для исследовательских сессий)

• Crossref: пожалуйста, добавьте mailto в User-Agent (этот сервер делает это), тогда лимит вежливого пула безграничен

Разработка

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

web-research-mcp/
├── bin/
│   └── web-research-mcp          # Launcher: venv bootstrap + exec
├── src/web_research/
│   ├── __init__.py
│   ├── server.py                  # MCPServer + 7 @app.tool functions
│   └── providers.py               # 7 search backends + Result dataclass
├── tests/
│   └── e2e_protocol.py            # Real subprocess JSON-RPC test
├── web-research.env.example       # API key template
├── pyproject.toml                 # PEP 621, uv-installable
├── README.md
├── CHANGELOG.md
├── LICENSE
└── .gitignore

Добавление нового инструмента

1. Добавьте асинхронную функцию в providers.py:

   async def search_my_source(query: str, max_results: int, client: httpx.AsyncClient) -> list[Result]:
       try:
           # ... your HTTP call ...
       except Exception as e:
           print(f"[my_source] error: {e}", flush=True)
           return []
       return [Result(title=..., url=..., snippet=..., source="my_source")]

2. Зарегистрируйте её в server.py:

   @app.tool(name="search_my_source", description="...", annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
   async def search_my_source(query: Annotated[str, Field(description="Search query")], max_results: Annotated[int, Field(ge=1, le=10, default=5)] = 5) -> str:
       async with await _new_client() as client:
           res = await providers.search_my_source(query, max_results, client)
       return _format_results(query, res, "my_source") if res else f"No my_source results for: {query}"

3. Добавьте живой тестовый пример в tests/e2e_protocol.py.

4. Обновите раздел «Инструменты» в README.

Стиль кода

• Python 3.10+, асинхронный подход

• Аннотации типов везде; пусть Pydantic выводит JSON-схему MCP

• Каждый провайдер оборачивает свой сетевой вызов в try/except и деградирует до []

• HTTP-клиент на каждый вызов (_new_client()) — не используйте общий клиент между вызовами в stdio-режиме

Вклад

PR приветствуются. Перед открытием:

1. Запустите e2e-тест на живой установке: .venv/bin/python tests/e2e_protocol.py

2. Добавьте тестовый пример для любого нового инструмента

3. Держите providers.py независимым от MCP-специфичных типов — он должен быть переиспользуемым как обычный Python-модуль

4. Не добавляйте зависимости от headless-браузеров или ротации прокси — это нарушает основную идею проекта

Для крупных изменений сначала откройте issue.

Лицензия

MIT — см. LICENSE.

Благодарности

• Создано на основе Model Context Protocol от Anthropic

• Использует Jina Reader для чистого получения страниц

• Поисковые API: Brave, Tavily, Wikipedia, arXiv, Crossref, Hacker News Algolia, Stack Exchange