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 是一个用 Go 编写的 Model Context Protocol 服务器。它以三个只读工具的形式，向任何兼容 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`	任何未分类的情况。

全失败消息刻意不区分超时与其他原因：混合批次可能同时因多种原因失败，而只要至少有一个条目存活，逐条 status 就已经携带了该细节。

已知限制

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 工具链）：

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

预编译二进制 — 从最新发布中获取适合你平台的压缩包，解压后将 mcp-retrieval 放到你的 PATH 中。

MCP Bundle — 对于支持安装 .mcpb 文件的客户端，从最新发布下载 mcp-retrieval_<version>_<os>_<arch>.mcpb 并用你的客户端打开。该 bundle 携带编译好的二进制文件，因此既不需要 Docker 也不需要 Go。请选择与你操作系统和 CPU 架构匹配的文件：一个 bundle 只包含一个原生二进制文件。

从源码构建：

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）。

配置

所有内容都通过环境变量进行配置，每个值在启动前都会经过验证：非数字或非正数的值都会导致启动错误。限制之间的相互关系不会在启动时检查——请参阅限制。环境中已有的变量优先于 .env 文件，因此 MCP 客户端的 env 块始终生效。每个字段都有合理的默认值，因此服务器可以在完全没有配置的情况下运行（stdio 传输）。

请参阅 .env.example 获取完整列表及其默认值，可直接复制到 .env。

MCP 服务器

环境变量	默认值	说明
`MCP_TRANSPORT`	`stdio`	`stdio` 或 `http`。
`MCP_NAME`	`mcp-retrieval`	向客户端通告的服务器名称。
`MCP_PATH`	`/mcp`	HTTP 路由（仅 http 传输）。

向客户端通告的版本不可配置：它在构建时从 git 标签写入二进制文件。

HTTP 服务器（仅 http 传输）

环境变量	默认值
`SERVER_PORT`	`8080`
`SERVER_READ_TIMEOUT`	`60s`
`SERVER_WRITE_TIMEOUT`	`60s`

HTTP 客户端和代理

环境变量	默认值	说明
`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` 时必需。

配置代理后，每个出站请求都会在登录名后附加一个唯一的会话 ID，因此上游提供商会为每个请求轮换出口 IP。

限制

环境变量	默认值
`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_*] 范围内，因此大于其 MAX_* 的 DEFAULT_* 只会产生 MAX_*；
如果 MIN_* 超过 MAX_*，则以最大值为准。

因此，有效限制始终在配置的最大值之内，配置错误会降级为可工作的服务器，而不是启动失败。代价是它会静默降级：诸如 MAX_RESULTS=2 而不是 20 这样的拼写错误不会产生任何警告，只会悄悄产生更小的响应。当结果看起来被截断时，值得仔细检查这些值。

日志

环境变量	默认值	说明
`LOG_MODE`	`local`	`local` → 调试级别的文本处理器；`prod` → 信息级别的 JSON 处理器。日志输出到 `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 通过可读性提取器处理，并将主要文章转换为 Markdown（包括表格）。不需要搜索引擎 API 密钥。
浏览器模拟。 适配器启用了 WithBrowserRotation()，因此每个请求都从约 11 个真实浏览器配置文件中随机选择一个发送。每个配置文件都将真实的 TLS/JA3 指纹（通过 uTLS）与匹配的 User-Agent 和客户端提示头配对——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。

许可证

根据 MIT License 发布。

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

ActivityNo data

ResponsivenessSyncing

Resources

Related MCP Connectors

SearchPipe A
tech.searchpipe
Web search API and MCP server for developers building AI agents.
Search Browser Automation Agent Orchestration
31
https://searchpipe.tech/mcp/
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

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
11 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
417 npm
10
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 5 days ago (2026-10-31 08:44 UTC)
11
169
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
666 npm
MIT