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 サーバーです。Web取得機能を、MCP互換の任意のクライアント（Claude Desktop、IDEエージェント、カスタムLLMアプリ）に3つの読み取り専用ツールとして公開します。内部では retrieval-go ライブラリを使用してWeb検索とページ取得を行い、結果をモデルに渡す準備の整ったクリーンなMarkdownとして返します。

このライブラリは APIキーを必要としません。Web検索はDuckDuckGo Lite、画像検索はBing Imagesを経由し、ページ取得ではHTMLを可読性抽出器（readability extractor）に通してからMarkdownに変換します。ボット対策に対して信頼性を保つため、TLSレベルで実際のブラウザを模倣し、ブラウザフィンガープリントとプロキシの両方をローテーションできます — 取得エンジンを参照してください。

MCP SDKがサポートする両方のトランスポートが利用可能で、どちらも同一のツールセットを公開します。

stdio — クライアントがバイナリを起動し、stdin/stdoutで通信します（デフォルト。デスクトップクライアントに最適）。
http — 長時間実行されるストリーミング可能なHTTPサーバー（リモート/共有デプロイに便利）。

Related MCP server: mcp-web-calc

ツール

ツール	説明
`web_search`	1つ以上のクエリを並列実行し、クエリごとに重複排除・再ランク付けされたスニペットとリンクを返します。
`web_search_images`	1つ以上の画像クエリを並列実行し、クエリごとに重複排除された画像結果を返します。
`web_scrape`	1つ以上のページを並列ダウンロードし、主要な記事テキストをMarkdownとして返します。

3つすべてが 読み取り専用 として注釈付けされています。各ツールは出力スキーマに一致する構造化JSONペイロードを返します。SDKは structuredContent を読み取らないクライアントのために、同じJSONをテキストコンテンツブロックにもミラーリングします。

`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ごとに1エントリを返します。各エントリには独自の status — success、failed、timeout — があり、部分的な失敗でも成功した項目は返されます。

count は実際に返された項目数で、要求した max_results / max_images より 少なくなることがあります。単一クエリの結果内の重複は上限が適用される前に除去され、また上流が単純に提供できる項目が少ない場合もあります。count が小さいのは正常な結果であり、エラーではありません。

重複排除は クエリごとであり、クエリ間では行われません。各エントリは個別に重複排除されるため、同じ呼び出し内の2つのクエリで見つかったリンクは両方のエントリに現れます。必要であれば、自分で和集合の重複排除を行ってください。

エラー

リクエストレベルの失敗は、JSON-RPCエラーではなく、isError: true とプレーンテキストメッセージを持つツール結果として返されます。モデルはメッセージを読み、呼び出し自体を修正できます。項目ごとの失敗はこのようにはならず、ペイロード内に 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`	分類不能なもの。

全失敗メッセージは意図的にタイムアウトと他の原因を区別しません。混合バッチは複数の理由で同時に失敗し得るため、少なくとも1つの項目が生き残る場合は、項目ごとの 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バンドル — .mcpb ファイルをインストールするクライアント向けに、最新リリースから mcp-retrieval_<version>_<os>_<arch>.mcpb をダウンロードし、クライアントで開きます。バンドルにはコンパイル済みバイナリが含まれているため、DockerもGoも不要です。OS と CPUアーキテクチャの両方に一致するファイルを選択してください。バンドルにはネイティブバイナリが1つだけ含まれています。

ソースから:

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

フラグは1つだけで、オプションです:

フラグ	意味
`-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にコピーできる状態で.env.exampleを参照してください。

MCPサーバー

Env	デフォルト	備考
`MCP_TRANSPORT`	`stdio`	`stdio`または`http`。
`MCP_NAME`	`mcp-retrieval`	クライアントに通知されるサーバー名。
`MCP_PATH`	`/mcp`	HTTPルート（httpトランスポートのみ）。

クライアントに通知されるバージョンは設定できません: ビルド時にgitタグからバイナリに刻印されます。

HTTPサーバー（httpトランスポートのみ）

Env	デフォルト
`SERVER_PORT`	`8080`
`SERVER_READ_TIMEOUT`	`60s`
`SERVER_WRITE_TIMEOUT`	`60s`

HTTPクライアントとプロキシ

Env	デフォルト	備考
`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をローテーションします。

制限

Env	デフォルト
`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_*の3つ組は起動時に相互チェックされません。一貫性のないセットでもサーバーは停止しません。代わりにリクエストごとに調整されます:

呼び出し元が省略した値、またはゼロや負の値で渡された値は、対応するDEFAULT_*にフォールバックします;
結果は[MIN_*, MAX_*]にクランプされるため、DEFAULT_*がMAX_*より大きい場合は単純にMAX_*になります;
MIN_*がMAX_*を超える場合は、最大値が優先されます。

したがって、有効な制限は常に設定された最大値以内に収まり、設定ミスは起動失敗ではなく動作するサーバーへの劣化になります。トレードオフは、それが静かに劣化することです: MAX_RESULTS=2のようなタイプミス（20の代わり）は警告を生成せず、静かに応答が小さくなるだけです。結果が切り詰められているように見える場合は、これらの値を再確認する価値があります。

ロギング

Env	デフォルト	備考
`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で設定されます。知っておくべきこと:

ソース。 Web検索はDuckDuckGo Liteを使用します; 画像検索はBing Imagesを使用します; ページ取得は生のHTMLをreadability抽出器で処理し、メイン記事を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）、キープアライブは無効化されます（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

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