de en es ja ko ru zh

mcp-retrieval

Name: mcp-retrieval
Author: Role1776

by Role1776

Overview Schema Source Related Servers Discussions Admin

Hybrid

Что это

mcp-retrieval — это сервер Model Context Protocol, написанный на Go. Он предоставляет возможности веб-поиска любому MCP-совместимому клиенту (Claude Desktop, IDE-агентам, пользовательским LLM-приложениям) в виде трёх инструментов только для чтения. Под капотом используется библиотека retrieval-go для поиска в вебе и получения страниц, возвращая результаты в виде чистого Markdown, готового для передачи модели.

Библиотеке не нужны API-ключи: веб-поиск идёт через DuckDuckGo Lite, поиск изображений — через Bing Images, а получение страниц прогоняет HTML через экстрактор читаемости перед преобразованием в Markdown. Чтобы оставаться надёжным против защиты от ботов, она имитирует реальные браузеры на уровне TLS и может ротировать как отпечатки браузеров, так и прокси — см. Поисковый движок.

Оба транспорта, поддерживаемые MCP SDK, доступны и предоставляют идентичный набор инструментов:

stdio — клиент запускает бинарник и общается через stdin/stdout (по умолчанию, идеально для десктопных клиентов).
http — долгоживущий потоковый HTTP-сервер (полезен для удалённых/общих развёртываний).

Related MCP server: mcp-web-calc

Инструменты

Инструмент	Описание
`web_search`	Выполняет один или несколько запросов параллельно и возвращает по каждому запросу дедуплицированные, переранжированные сниппеты со ссылками.
`web_search_images`	Выполняет один или несколько запросов изображений параллельно и возвращает по каждому запросу дедуплицированные результаты изображений.
`web_scrape`	Загружает одну или несколько страниц параллельно и возвращает основной текст статьи в виде Markdown.

Все три аннотированы как только для чтения. Каждый инструмент возвращает структурированный JSON-ответ, соответствующий его схеме вывода; SDK зеркалирует тот же JSON в текстовый блок содержимого для клиентов, которые не читают structuredContent.

`web_search`

Параметр	Тип	По умолчанию	Примечания
`queries`	`[]string`	—	Обязательный. Выполняются параллельно.
`max_results`	`int`	`5`	Сниппетов на запрос, ограничено конфигом `max_results` (`20`).
`timeout_ms`	`int64`	`5000`	Таймаут всего вызова; ограничивается `[min, max]` из конфига.
`date`	`string`	—	Фильтр свежести: `d` (день), `w` (неделя), `m` (месяц), `y` (год).

`web_search_images`

Параметр	Тип	По умолчанию	Примечания
`queries`	`[]string`	—	Обязательный. Выполняются параллельно.
`max_images`	`int`	`5`	Изображений на запрос, ограничено конфигом `max_images` (`10`).
`timeout_ms`	`int64`	`5000`	Таймаут всего вызова; ограничивается `[min, max]` из конфига.
`date`	`string`	—	Фильтр свежести: `d` / `w` / `m` / `y`.

`web_scrape`

Параметр	Тип	По умолчанию	Примечания
`urls`	`[]string`	—	Обязательный. Загружаются параллельно.
`robots_txt`	`bool`	`false`	Уважать `robots.txt` страницы.
`timeout_ms`	`int64`	`5000`	Таймаут всего вызова; ограничивается `[min, max]` из конфига.
`remove_links`	`bool`	`false`	Удалить Markdown-ссылки из текста.
`max_chars`	`int`	`20000`	Обрезать текст страницы до N символов, ограничено конфигом `max_document_chars` (`20000`).

Списки queries/urls ограничены max_queries (10) элементами на вызов. Запросы должны быть ≤ 512 символов; URL ≤ 2048 символов и только http/https.

Результаты и счётчики

Каждый вызов разворачивается по входному списку и возвращает по одной записи на запрос/URL, каждая со своим status — success, failed или timeout — так что частичный сбой всё равно возвращает элементы, которые сработали.

count — это количество фактически возвращённых элементов, и оно может быть меньше запрошенного max_results / max_images: дубликаты в результатах одного запроса удаляются до применения лимита, а вышестоящий сервис может просто иметь меньше элементов. Меньший count — это нормальный результат, а не ошибка.

Дедупликация выполняется по запросу, а не между запросами. Каждая запись дедуплицируется отдельно, поэтому ссылка, найденная двумя запросами в одном вызове, появляется в обеих записях — если нужно, дедуплицируйте объединение самостоятельно.

Ошибки

Сбои на уровне запроса возвращаются как результат инструмента с isError: true и текстовым сообщением, а не как ошибка JSON-RPC — модель читает сообщение и может сама исправить вызов. Сбои по отдельным элементам никогда так не делают; они остаются внутри полезной нагрузки как status: "failed" / "timeout".

Вызов полностью проваливается только тогда, когда входные данные отклоняются до начала работы, или когда каждый элемент в нём проваливается:

Сообщение	Значение
`invalid request`	Аргументы не прошли валидацию.
`too many queries` / `too many urls`	Список превышает `MAX_QUERIES`.
`query must not be empty`	Пустой запрос или пустой список `queries`.
`query is too long`	Запрос превышает 512 символов.
`invalid url`	URL некорректен, длиннее 2048 символов или не `http`/`https`.
`robots.txt denied`	`robots_txt: true`, и страница запрещает загрузку.
`upstream service unavailable`	Вышестоящий сервис ответил неожиданным кодом состояния.
`every url failed to be scraped; the pages may be unreachable or hold no extractable text`	Все URL провалились. Отдельные причины логируются в `stderr`, не возвращаются.
`every query failed; the search upstream may be unreachable`	Все запросы провалились.
`internal server error`	Что-то неклассифицированное.

Сообщения о полном провале намеренно не различают таймауты и другие причины: смешанный пакет может провалиться по нескольким причинам одновременно, а статус по каждому элементу уже несёт эту деталь, когда выживает хотя бы один элемент.

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

web_scrape обрабатывает только HTML. Страницы прогоняются через экстрактор читаемости, которому нужна разметка статьи, поэтому ответы text/plain ничего не дают и возвращаются как status: "failed". Обычный случай — хостинг сырых файлов: raw.githubusercontent.com, github.com/.../raw/..., cdn.jsdelivr.net. Извлекайте отрендеренную страницу, а не сырой файл.
Релевантность web_search_images не гарантируется. Для некоторых запросов Bing Images отдаёт страницу, которая не является набором результатов, и она парсится как таковая — инструмент тогда возвращает несвязанные изображения с status: "success". Относитесь к результатам изображений как к лучшим усилиям и проверяйте их перед показом пользователю.
Нет JavaScript. Страницы загружаются как есть; контент, отрендеренный на стороне клиента, невидим для экстрактора.

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

Установка

Выбирайте любой вариант — все дают идентичный сервер.

Контейнер (не нужен Go toolchain):

docker pull ghcr.io/role1776/mcp-retrieval:latest

Готовый бинарник — возьмите архив для вашей платформы из последнего релиза, распакуйте его и поместите mcp-retrieval в ваш PATH.

MCP Bundle — для клиентов, которые устанавливают файлы .mcpb, скачайте mcp-retrieval_<version>_<os>_<arch>.mcpb из последнего релиза и откройте его своим клиентом. Пакет содержит скомпилированный бинарник, поэтому ему не нужны ни Docker, ни Go. Выберите файл, соответствующий вашей ОС и архитектуре CPU: пакет содержит один нативный бинарник.

Из исходников:

go install github.com/Role1776/mcp-retrieval/app/cmd/mcp-retrieval@latest   # needs Go 1.25.5+

Или соберите бинарник на месте (модуль Go находится в app/):

make build          # -> bin/mcp-retrieval

Запуск

# defaults: stdio transport, no configuration needed
./bin/mcp-retrieval

# with an explicit env file
./bin/mcp-retrieval -env /absolute/path/to/.env

Единственный флаг необязателен:

Флаг

Значение

-env

Путь к файлу .env. Если опущен — или если файл не существует — сервер запускается с настройками по умолчанию и тем, что уже есть в окружении. Неявного поиска нет: при stdio рабочая директория выбирается MCP-клиентом, поэтому относительный путь по умолчанию был бы непредсказуемым.

Подключение MCP-клиента (stdio)

Укажите вашему клиенту на собранный бинарник. Пример конфигурации Claude Desktop:

{
  "mcpServers": {
    "retrieval": {
      "command": "/absolute/path/to/mcp-retrieval",
      "env": {
        "MAX_RESULTS": "20"
      }
    }
  }
}

Блок env необязателен — одного "command" достаточно.

Подключение MCP-клиента (контейнер)

Запустите образ на stdio. Конфигурация по-прежнему передаётся через блок env, но Docker требует, чтобы каждая переменная была указана в командной строке с -e, чтобы она достигла процесса:

{
  "mcpServers": {
    "retrieval": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MAX_RESULTS",
        "-e", "DEFAULT_TIMEOUT_MS",
        "ghcr.io/role1776/mcp-retrieval:latest"
      ],
      "env": {
        "MAX_RESULTS": "20",
        "DEFAULT_TIMEOUT_MS": "5000"
      }
    }
  }
}

-i обязателен — без него контейнер не получает stdin, и клиент видит, что сервер немедленно умирает. Клиенты, устанавливаемые из MCP Registry, сами собирают этот вызов и запрашивают переменные, объявленные в server.json.

Запуск через HTTP

Установите MCP_TRANSPORT=http, и сервер будет слушать SERVER_PORT по пути MCP_PATH (по умолчанию http://localhost:8080/mcp).

Конфигурация

Всё настраивается через переменные окружения, и каждое значение проверяется перед запуском: нечисловое или неположительное значение является ошибкой запуска. Связи между лимитами не проверяются при запуске — см. Limits. Переменные, уже присутствующие в окружении, имеют приоритет над файлом .env, поэтому блок env MCP-клиента всегда действует. Каждое поле имеет разумное значение по умолчанию, так что сервер работает без какой-либо конфигурации (транспорт stdio).

См. .env.example для полного списка со значениями по умолчанию, готового для копирования в .env.

MCP-сервер

Env	Default	Notes
`MCP_TRANSPORT`	`stdio`	`stdio` или `http`.
`MCP_NAME`	`mcp-retrieval`	Имя сервера, сообщаемое клиентам.
`MCP_PATH`	`/mcp`	HTTP-маршрут (только для http-транспорта).

Версия, сообщаемая клиентам, не настраивается: она встраивается в бинарник при сборке из git-тега.

HTTP-сервер (только для http-транспорта)

Env	Default
`SERVER_PORT`	`8080`
`SERVER_READ_TIMEOUT`	`60s`
`SERVER_WRITE_TIMEOUT`	`60s`

HTTP-клиент и прокси

Env	Default	Notes
`MAX_IDLE_CONNS_PER_HOST`	`100`	Пул HTTP-соединений.
`PROXY_HOST`	—	Необязательно. Если задано, запросы направляются через прокси с ротацией сессий.
`PROXY_PORT`	—	Обязательно, если задан `PROXY_HOST`.
`PROXY_SCHEME`	—	Обязательно, если задан `PROXY_HOST`.
`PROXY_LOGIN`	—	Обязательно, если задан `PROXY_HOST`.
`PROXY_PASSWORD`	—	Обязательно, если задан `PROXY_HOST`.

Когда прокси настроен, каждый исходящий запрос получает уникальный идентификатор сессии, добавляемый к логину, поэтому вышестоящий провайдер ротирует исходящий IP для каждого запроса.

Лимиты

Env	Default
`MAX_QUERIES`	`10`
`DEFAULT_RESULTS`	`5`
`MAX_RESULTS`	`20`
`DEFAULT_TIMEOUT_MS`	`5000`
`MAX_TIMEOUT_MS`	`10000`
`MIN_TIMEOUT_MS`	`1000`
`DEFAULT_IMAGES`	`5`
`MAX_IMAGES`	`10`
`DEFAULT_DOCUMENT_CHARS`	`20000`
`MAX_DOCUMENT_CHARS`	`20000`

Каждое значение проверяется отдельно — оно должно быть больше нуля, — но тройки DEFAULT_*, MIN_* и MAX_* не перекрёстно проверяются друг с другом при запуске. Несогласованный набор не останавливает сервер; вместо этого он согласуется для каждого запроса:

значение, которое вызывающий опускает или передаёт как ноль или отрицательное, откатывается к соответствующему DEFAULT_*;
затем результат ограничивается диапазоном [MIN_*, MAX_*], так что DEFAULT_*, превышающий свой MAX_*, просто даёт MAX_*;
если MIN_* превышает MAX_*, побеждает максимум.

Таким образом, эффективный лимит всегда находится в пределах настроенного максимума, и неправильная конфигурация приводит к работающему серверу, а не к неудачному запуску. Обратная сторона — деградация происходит молча: опечатка, например MAX_RESULTS=2 вместо 20, не вызывает предупреждений, только тихо уменьшает ответы. Стоит перепроверять эти значения, когда результаты выглядят усечёнными.

Логирование

Env	Default	Notes
`LOG_MODE`	`local`	`local` → текстовый обработчик на уровне debug; `prod` → JSON-обработчик на уровне info. Логи идут в `stderr`.

Архитектура

Проект следует чистой многослойной структуре. Зависимости направлены внутрь к домену, и каждый слой общается со следующим через интерфейсы.

app/                       the Go module: sources plus its build files
                           (Dockerfile, .dockerignore, .goreleaser.yaml)

cmd/mcp-retrieval/main.go  entry point: parse flags, load config, run app

internal/
  app/                     wiring + lifecycle (build server, run, graceful shutdown)
  config/                  config loading (.env → env vars → validate)
  domain/                  core types (Query, Link, Document, Snippet, Image) and errors
  dto/web/                 request/response shapes for the MCP tools
  transport/mcp/           MCP layer
    router/                registers every tool group on the MCP server
    web/                   tool handlers
    utils/                 schema helpers and error → tool-result mapping
  usecase/web/             business logic: validation, parallelism, timeouts, dedupe/limit/rerank
  adapter/web/             retrieval-go client wiring (search, images, scrape, proxy)
  pkg/                     reusable building blocks (mcpserver, server, logger, validator)

Поток запроса для вызова инструмента:

MCP client → transport/mcp/web (handler) → usecase/web → adapter/web → retrieval-go → the web
                     ↑ maps errors               ↑ validates, fans out, limits results

Поиск и скрейпинг оба разворачиваются по списку входных данных конкурентно и агрегируют результаты по каждому элементу, каждый со своим статусом (success, failed, timeout). Вызов полностью завершается ошибкой только тогда, когда каждый элемент в нём терпит неудачу.

Поисковый движок

Вся сетевая работа делегируется retrieval-go, настраиваемому в app/internal/adapter/web. Полезно знать:

Источники. Веб-поиск использует DuckDuckGo Lite; поиск изображений — Bing Images; при получении страницы необработанный HTML пропускается через экстрактор readability и преобразуется в Markdown (включая таблицы). Ключи API поисковых систем не требуются.
Имитация браузера. Адаптер включает WithBrowserRotation(), поэтому каждый запрос отправляется из одного из ~11 реальных профилей браузера, выбранных случайным образом. Каждый профиль сочетает подлинный TLS/JA3-отпечаток (через uTLS) с соответствующим User-Agent и заголовками client-hint — Chrome 133/131/120 (Windows/macOS/Linux), Edge 131, Firefox 120 (Windows/macOS), Safari 18.4 (macOS) и iOS 18.4 Safari. Это делает трафик похожим на обычные браузеры, а не на Go HTTP-клиент, что и позволяет обращаться к бесплатным источникам.
Ротация прокси. Когда задан PROXY_HOST, адаптер устанавливает фабрику прокси, которая добавляет уникальный session-<id> к имени пользователя прокси в каждом запросе. С провайдером резидентных/ротационных прокси на основе сессий это даёт новый исходящий IP для каждого запроса, распределяя нагрузку и избегая ограничений скорости. Без прокси запросы идут напрямую.
Обработка ответов. Ответы прозрачно распаковываются (gzip, br, zstd, deflate), и keep-alive отключён (WithDisableKeepAlive()), чтобы пул соединений не закреплял один отпечаток/IP между запросами.

Ничто из этого не требует настройки для работы — указанные выше значения по умолчанию применяются автоматически. Только учётные данные прокси являются необязательными дополнениями.

Разработка

Весь код на Go находится в app/, поэтому либо используйте makefile из корня репозитория, либо передайте -C app в инструментарий:

make build          # compile the binary
make test           # run tests

go -C app build ./...      # compile everything
go -C app test ./...       # run tests
go -C app vet ./...        # static checks

См. CONTRIBUTING.md для руководства по pull-request.

Лицензия

Выпущено под лицензией MIT.

Available Tools

3 tools

web_scrapeWeb scrapeA

Read-onlyIdempotent

Downloads pages by their links and returns the main text as markdown. Use this to read a page in full after 'web_search' found it; snippets alone are often not enough. Links are fetched in parallel, up to 10 per call, so batch all links into one call.

Size: 'max_chars' is a per-page character limit (not tokens). A page cut short ends with '[truncated]' and has 'truncated' set; the rest cannot be fetched afterwards.

Results are reported per URL with a 'status' field (success, failed or timeout). A failed URL does not fail the others; the call errors only if every URL fails. Target sites may block or rate-limit the request, which shows up as a failed URL.

Name	Required	Description
`urls`	Yes	1-10 absolute http(s) page URLs, fetched in parallel; one malformed URL rejects the whole call
`max_chars`	No	character limit applied to each page separately, not to the whole response; default and maximum 20000, so it can only lower the limit; a cut page ends with '[truncated]'
`robots_txt`	No	if true, pages disallowed by the site robots.txt are not fetched; default false
`timeout_ms`	No	timeout for the whole call in milliseconds, shared by all URLs; default 5000, clamped to 1000-10000; unfinished pages get status 'timeout'
`remove_links`	No	if true, markdown links are replaced by their text; default false

Output Schema

Name	Required	Description
`results`	Yes
`metadata`	Yes

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description still adds real substance: per-URL status values, partial-failure semantics ('a failed URL does not fail the others'), all-fail error condition, external blocking/rate-limiting, and the irreversibility of truncation. Minor gap: it doesn't mention the robots_txt opt-in or the call-wide timeout being shared across URLs, both of which affect real call behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the batching rule, then cleanly separated into size and result-reporting sections. Every sentence carries a constraint or a consequence an agent would otherwise get wrong; nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the things that actually break an agent's plan: batching limit, per-page truncation, partial failure isolation, and timeouts. An output schema exists, yet the description still summarizes the per-URL status contract, which is a useful addition rather than redundancy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds interpretive value beyond the schema: 'max_chars' is a per-page limit, not tokens, and a cut page cannot be recovered afterwards. The remaining parameters (robots_txt, timeout_ms, remove_links) are left entirely to the schema, which is acceptable given full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Downloads pages by their links and returns the main text as markdown') and explicitly positions itself against the sibling 'web_search' by naming the gap in snippets. An agent can distinguish it from web_search and web_search_images without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit sequencing rule ('use this to read a page in full after web_search found it; snippets alone are often not enough') and an operational rule ('batch all links into one call'). The alternative tool is named together with the condition that selects it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

web_searchWeb searchA

Read-onlyIdempotent

Searches the web for one or more queries and returns snippets with links. Queries run in parallel. IMPORTANT: Always write search queries in English for best results and relevance. Use this to find sources; then call 'web_scrape' to read a full page, or 'web_search_images' when you need pictures (both can be called in the same turn).

Freshness: set the 'date' field to restrict results by recency - 'd' (past day), 'w' (past week), 'm' (past month), 'y' (past year). Use it to prefer the most recent pages when the user asks about news or anything time-sensitive; leave it empty for all time.

Query operators (put them inside the query string itself): 'site:example.com term' limits the search to one site; 'filetype:pdf term' restricts to a file type; double quotes "exact phrase" force an exact match; a leading '-' excludes a word (term -foo); 'intitle:term' requires the word in the page title. Operators can be combined, e.g. 'site:arxiv.org filetype:pdf transformers'.

Results are reported per query with a 'status' field (success, failed or timeout). A failed query does not fail the others; the call errors only if every query fails. The upstream search engines may rate-limit or block requests, which shows up as a failed or timed-out query - retry later or rephrase.

Name	Required	Description
`date`	No	freshness filter: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time; use only these values
`queries`	Yes	1-10 search queries in English, run in parallel; each must be non-empty and at most 512 characters, otherwise the whole call is rejected
`timeout_ms`	No	timeout for the whole call in milliseconds, shared by all queries; default 5000, clamped to 1000-10000; unfinished queries get status 'timeout'
`max_results`	No	maximum snippets per query, not in total; default 5, values above 20 are clamped to 20

Output Schema

Name	Required	Description
`results`	Yes
`metadata`	Yes

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnly/openWorld/idempotent annotations: it explains per-query status reporting (success/failed/timeout), that a failed query does not fail the others and the call errors only if all queries fail, and that upstream rate-limiting surfaces as failed/timed-out queries requiring retry or rephrasing. That is exactly the operational context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose before the operational detail, and section labels (Freshness, Query operators) make it scannable. Minor redundancy: the date filter values are spelled out in both the description and the schema's date property description, costing a sentence that adds no new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything an agent needs for a multi-query search tool: batching behavior, partial-failure semantics, timeout/rate-limit handling, query formatting, and result shape at a high level. An output schema exists, so return values need not be enumerated here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 100%, the description adds substantial meaning: it mandates English queries, enumerates the supported query operators (site:, filetype:, quoted phrases, leading '-', intitle:) with a combined example, and explains freshness semantics. This is syntax guidance the schema does not express.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('searches the web') plus scope ('one or more queries', parallel execution, snippets with links). It explicitly distinguishes itself from both siblings by naming web_scrape for full-page reads and web_search_images for pictures.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use routing ('Use this to find sources; then call web_scrape...') and notes both can be called in the same turn. It also supplies conditional guidance for the date filter ('use it when the user asks about news or anything time-sensitive; leave it empty for all time').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

web_search_imagesWeb image searchA

Read-onlyIdempotent

Searches for images by one or more queries, executed in parallel. IMPORTANT: Queries must be in English ONLY. Use this only when you need pictures; use 'web_search' for text answers and links, and 'web_scrape' to read a page.

Freshness: set the 'date' field to restrict results by recency - 'd' (past day), 'w' (past week), 'm' (past month), 'y' (past year); leave it empty for all time.

Query operators can be embedded in the query string: 'site:example.com term' limits to one site, double quotes "exact phrase" force an exact match, and a leading '-' excludes a word.

Results are reported per query with a 'status' field (success, no relevant, failed or timeout). A failed query does not fail the others; the call errors only if every query fails. The upstream image search may rate-limit or block requests, which shows up as a failed or timed-out query.

Name	Required	Description
`date`	No	freshness filter: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time; other values are ignored
`queries`	Yes	1-10 image search queries in English, run in parallel; each must be non-empty and at most 512 characters, otherwise the whole call is rejected
`max_images`	No	maximum images per query, not in total; default 5, values above 10 are clamped to 10
`timeout_ms`	No	timeout for the whole call in milliseconds, shared by all queries; default 5000, clamped to 1000-10000; unfinished queries get status 'timeout'

Output Schema

Name	Required	Description
`results`	Yes
`metadata`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, yet the description still adds real value: per-query status semantics, partial-failure behavior ("a failed query does not fail the others"), and the upstream rate-limit/block risk. It does not explain result ordering or what fields come back, but the output schema covers that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core behavior and routing decision, then broken into scannable paragraphs for freshness, operators, and failure semantics. Slightly dense, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param parallel search tool with annotations and an output schema, this covers everything an agent needs: language constraint, batching, freshness, operator syntax, and failure modes. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, and the description goes beyond it by documenting query operators (site:, "exact phrase", leading '-') that are absent from the schema entirely. The freshness codes and clamping are repeated from the schema rather than adding to it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Searches for images by one or more queries") plus the parallel-execution trait. It explicitly names both siblings and what each is for, so an agent can pick the right tool without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit use condition ("use this only when you need pictures") and names the two alternatives with their respective purposes. The English-only constraint is flagged as IMPORTANT and front-loaded.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.10Oct 24, 2026

Changedweb_scrape6 fields changed

changedInput schema / properties / max_chars / description

Previous value: -"truncate each page separately to N characters, default and maximum 20000; only lowers the limit, higher values are ignored"New value: +"character limit applied to each page separately, not to the whole response; default and maximum 20000, so it can only lower the limit; a cut page ends with '[truncated]'"

changedInput schema / properties / remove_links / description

Previous value: -"strip markdown links from the text"New value: +"if true, markdown links are replaced by their text; default false"

changedInput schema / properties / robots_txt / description

Previous value: -"respect the page robots.txt"New value: +"if true, pages disallowed by the site robots.txt are not fetched; default false"

changedInput schema / properties / timeout_ms / description

Previous value: -"timeout for the whole call in milliseconds"New value: +"timeout for the whole call in milliseconds, shared by all URLs; default 5000, clamped to 1000-10000; unfinished pages get status 'timeout'"

changedInput schema / properties / urls / description

Previous value: -"links to pages, downloaded in parallel"New value: +"1-10 absolute http(s) page URLs, fetched in parallel; one malformed URL rejects the whole call"

addedInput schema / properties / urls / maxItems
```
Added value: +10
```

Changedweb_search5 fields changed

changedInput schema / properties / date / description

Previous value: -"filter results by freshness: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time"New value: +"freshness filter: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time; use only these values"

changedInput schema / properties / max_results / description

Previous value: -"maximum number of snippets per query"New value: +"maximum snippets per query, not in total; default 5, values above 20 are clamped to 20"

changedInput schema / properties / queries / description

Previous value: -"search queries in English, executed in parallel"New value: +"1-10 search queries in English, run in parallel; each must be non-empty and at most 512 characters, otherwise the whole call is rejected"

addedInput schema / properties / queries / maxItems
```
Added value: +10
```

changedInput schema / properties / timeout_ms / description

Previous value: -"timeout for the whole call in milliseconds"New value: +"timeout for the whole call in milliseconds, shared by all queries; default 5000, clamped to 1000-10000; unfinished queries get status 'timeout'"

Changedweb_search_images5 fields changed

changedInput schema / properties / date / description

Previous value: -"filter results by freshness: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time"New value: +"freshness filter: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time; other values are ignored"

changedInput schema / properties / max_images / description

Previous value: -"maximum number of images per query"New value: +"maximum images per query, not in total; default 5, values above 10 are clamped to 10"

changedInput schema / properties / queries / description

Previous value: -"queries in English for image search"New value: +"1-10 image search queries in English, run in parallel; each must be non-empty and at most 512 characters, otherwise the whole call is rejected"

addedInput schema / properties / queries / maxItems
```
Added value: +10
```

changedInput schema / properties / timeout_ms / description

Previous value: -"timeout for the whole call in milliseconds"New value: +"timeout for the whole call in milliseconds, shared by all queries; default 5000, clamped to 1000-10000; unfinished queries get status 'timeout'"

3 tool updatesv1.0.0Aug 22, 2026
- First observedweb_scrape
- First observedweb_search
- First observedweb_search_images

Deploy Server

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

TDQS

A4.7/5.0

Scored 2026-10-24 17:35 across 3 tools

Disambiguation5/5

Each tool targets a distinct modality+action: text search, image search, and full-page fetching. The descriptions explicitly cross-reference each other ('use web_search for text, web_scrape to read a page'), leaving no realistic chance of misselection.

Naming Consistency5/5

All three names follow the same snake_case verb_noun pattern sharing the 'web_' prefix (web_search, web_search_images, web_scrape). The shared prefix makes the family immediately recognizable while the distinguishing suffix stays descriptive.

Tool Count5/5

Three tightly scoped tools for a retrieval-only server; none is redundant and no filler exists. Search-text, search-images, and scrape cover the full surface without bloat.

Completeness4/5

The retrieve-then-read workflow is fully supported, with batching, truncation signaling, and per-URL status handling. Minor gaps remain (no structured/raw fetch beyond markdown extraction, no crawl or sitemap traversal), but agents can work around these via repeated scrape calls.

Maintenance

ActivityMaintained

ResponsivenessSlow

Resources

Related MCP Connectors

SSearch B
cc.ssearch
Free web search for AI agents. No API key required. Hosted MCP in active development.
Search Browser Automation
82
https://api.ssearch.cc/mcp
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
https://llmse.ai/mcp
Keenable Web Search A
ai.keenable.api
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Research & Data Search Web Scraping
23
https://api.keenable.ai/mcp?keenable_title=glama
Novada MCPOAuth
io.github.NovadaLabs
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Browser Automation Web Scraping Search
13
https://mcp.novada.com/mcp

Related MCP Servers

ISIS MCP
RAG Systems Web Scraping Search
alucardeht
A
license
B
quality
D
maintenance
A local web scraping MCP server with RAG capabilities that provides intelligent web search, content extraction, and screenshot tools without requiring API keys.
Updated 8 months ago (2026-02-25 04:07 UTC)
4
6 npm
MIT
mcp-web-calc
Search Browser Automation Text Summarization
tickernelz
A
license
A
quality
D
maintenance
An MCP server that enables web searching, URL content extraction, and summarization without requiring API keys. It also provides advanced mathematical evaluation and multi-language Wikipedia summary retrieval tools.
Updated 6 months ago (2026-05-03 08:45 UTC)
5
400 npm
7
MIT
free-search-mcp
Browser Automation Search Web Scraping
sweetcornna
A
license
A
quality
A
maintenance
A local-first, no-API-key MCP server that enables LLMs to search the web, fetch pages, and read documents using multiple engines and smart fallbacks.
Updated 2 days ago (2026-10-29 08:11 UTC)
11
167
MIT
web-basics-mcp
Browser Automation Search
yoloyash
A
license
A
quality
A
maintenance
A self-hosted MCP server providing web search and URL fetching tools, running locally without external API keys or accounts.
Updated 2 months ago (2026-08-26 07:41 UTC)
2
380 npm
MIT