Free Search

Run a multi-engine web search and return a ranked, deduplicated link list. Best for: - Discovery queries ("what is X", "find me X", "who is X"). - Getting a list of URLs you can hand to `fetch` / `fetch_batch` next. - Topics likely to be after your knowledge cutoff (use `freshness="week"`). - Filtering to specific domains (`include_domains=["python.org"]`) or a kind of source (`category="paper"` / `"finance"`, or a sub-group like `category="paper.biomed"` / `"finance.filings"`; see `engines()` for the full tree). - Looking a fact up at its registry, with no category needed: a current version or support end date ("latest fastapi version"), a CVE ("CVE-2024-3094": NVD record, OSV advisories, CISA exploited status), a forecast ("上海明天天气"), an exchange rate ("100 usd to cny": ECB, and the PBOC parity for 人民币), a coin price, a country indicator ("china gdp", "japan population"), public holidays ("2026年放假安排"), the current time in a city, a domain's expiry, a company's legal entity, an iOS app's version, Wikidata facts ("Shanghai population"). The source that fits the words joins the search and its record arrives as the first result with the publisher's date in `dated …`, so it can be cited without a fetch. Name the thing plainly. `category=` ("software", "security", "weather", "finance.fx", "stats", "calendar", "reference", "docs", "gov") asks the same sources explicitly. Not recommended for: - You already know the URL -> use `fetch` instead. - You want both links AND their full text in one call -> use `research`. - You want to query pages already in the local cache -> use `cache_search`. - Reading PDFs/DOCX from a known URL -> use `read_doc`. - Following one paper's references or citations -> use `paper_graph`. Returns: - markdown (default): numbered list of `n. title`, `<url>`, snippet. About 40% fewer tokens than json

Fetch one URL: page text, or a description of a non-text resource. Handles any http(s) resource, not just HTML: - HTML pages -> reader-mode Markdown (nav/footer/scripts stripped). - PDF/DOCX/XLSX/PPTX/EPUB/CSV/code/archives -> parsed text (same engine as `read_doc`, which you should prefer when you need pagination). - Images, video, audio, fonts, opaque binaries -> a description (media type, byte size, dimensions, sha256), NOT the bytes. Best for: - You already have a URL (from `search`, the user, or your own knowledge) and need the actual page text. - Verifying a single claim by reading the source. - Checking what a resource IS before deciding to spend tokens on it. Not recommended for: - Multiple URLs at once -> use `fetch_batch` (concurrent, one round-trip). - "Search then read top N" -> use `research` (one call, not two). - Long documents you need to page through -> use `read_doc` (start/length). - You don't have a URL yet -> use `search` first. Returns: - markdown (default): a small header (URL, render method, token count) plus the cleaned page body. - json: {url, title, content, method, truncated, tokens_estimated, author, published_date, sitename}, plus {media_type, bytes_size, sha256, width, height} for non-text resources. - With `inline=True` on an image: the image itself, viewable by a vision-capable model. Common mistakes: - Passing a search query instead of a URL. - Using `render="http"` on a JS-only SPA: it returns near-empty content; use "auto" (default) or "browser". - Setting `inline=True` on a large image out of habit. A 1MB image costs well over a thousand tokens; fetch it plainly first and inline only if the description says it's worth looking at. - Forgetting that results are cached 7 days: use `force_refresh=True` or `max_age_hours=0` for a fresh pull. The header says `cached N days ago`

Fetch a list of URLs in parallel. Per-URL failures do not raise. Best for: - 2+ URLs you want to read in one round-trip. - Reading the top N results of a previous `search` call. Not recommended for: - A single URL -> `fetch` (no list-wrapping overhead). - "Search and then read" -> `research` collapses both into one tool call. - PDFs/DOCX -> `read_doc` per file. Returns: - markdown (default): each page rendered as a Markdown section, separated by horizontal rules; failed URLs become inline error notes. - json: list[dict], one entry per URL, with `error` set on failures. Common mistakes: - Passing a single URL inside a 1-element list: use `fetch` directly. - Assuming an exception means the whole batch failed; check each item's `error` field instead. Args: urls: List of absolute http(s) URLs (max 20 per call). render: Same as `fetch`. format: "markdown" or "json".

Read an http(s) document (or a sandboxed local file) into Markdown. Best for: - Remote PDFs and DOCX from an http(s) URL (parsed locally, no remote API). - Local PDF/DOCX/text/Markdown files, ONLY when local reads are enabled (see Security below). - Paginating through a long document via `start` / `length`. Not recommended for: - Arbitrary HTML web pages -> `fetch` does reader-mode cleanup that this tool does not. - Pages discovered through search -> `fetch` or `research`. Security (local files are sandboxed and OFF by default): - Local-file reads are DISABLED unless the server operator sets the SEARCH_MCP_DOCUMENT_ROOT env var to a directory. With it unset, a local path raises a "local file reads are disabled" error. Pass an http(s) URL instead, or ask the operator to enable the sandbox. - When enabled, `source` must resolve INSIDE that root; relative paths resolve against the root (not the process CWD) and any `..` traversal that escapes the root is rejected. `file://` URLs are always rejected. - Remote http(s) sources are unaffected by this setting. Returns: - markdown (default): rendered document text with a small header. - json: {content, title, format, total_chars, start, returned_chars, truncated}. Use `total_chars` and `returned_chars` to drive pagination. Common mistakes: - Calling this on a normal article URL: you'll get raw HTML noise. Use `fetch` instead. - Forgetting to advance `start` when paginating: next call should pass `start = previous_start + returned_chars`. - Passing a negative `length` (raises an error) or a `start` past the end (clamped to EOF: you'll get `returned_chars == 0`, `start == total_chars`, and `truncated == False`, which is the signal you've paged off the end). Args: source: http(s) URL, or a local path UNDER SEARCH_MCP_DOCUMENT_ROOT when local reads are enabl

One-shot research: search the web, fetch the top results, return both. Best for: - Open-ended questions that need finding sources AND reading them ("what's new with X", "summarize the controversy around Y"). - Replacing a `search` + N x `fetch` chain with one call. - Producing a citable brief with [n]-style source references. Not recommended for: - You only need links -> `search` (cheaper, no fetching). - You only need to read one URL you already have -> `fetch`. - You want to query previously-fetched cached pages -> `cache_search`. - Checking or expanding one paper's citations -> `paper_graph`. Returns: - markdown (default): a "Research brief" with a Sources index then the full Markdown body of each fetched document, separated by horizontal rules; includes a token estimate. - json: {question, engines, sources:[{rank,title,url,snippet,...}], documents:[...], tokens_estimated, errors}. Common mistakes: - Using `depth=8` for a quick lookup: that's 8 page fetches, and 2-3 is almost always enough. - Calling `research` for a known URL: that is what `fetch` is for. - Forgetting that `fetch=False` returns sources only (much cheaper if the LLM only needs to pick which one to read). Args: question: What you want to know, in natural language. depth: How many top results to fetch (1-8). 3 is a good default. engines: Override the engine set (see `engines()` for names). Prefer `category=`. Naming engines turns category routing off. fetch: If False, return source list without reading them. freshness: "day"|"week"|"month"|"year". Restricts to recent results. Best-effort; undated results are kept rather than dropped. include_domains: Restrict to these domains (e.g. ["python.org"]). exclude_domains: Drop results from these domains. category: Which KIND of source to search; a bare group wid

Follow the citations of ONE paper, and check whether it still stands. `search` finds papers that MENTION your words. This follows the edges instead: what a specific paper built on, and what has built on it since. Best for: - Checking a citation before repeating it: is the DOI real, and has the paper been retracted or corrected? - "What happened after this result": citing works come back ordered by how much the field cited them, so a 2019 paper leads to the current state of the art rather than to the most recent preprint about it. - Building a reading list backwards from one good paper. Not recommended for: - Finding papers by topic -> `search(category="paper")`, or a sub-group like `"paper.biomed"` / `"paper.cs"` / `"paper.preprint"`. - Reading the paper itself -> `read_doc` on the returned URL. Returns: - markdown (default): the paper with its retraction/correction notices, then "References" and "Cited by" sections. - json: {paper, references, citations, notes}, where `paper.crossref` carries `registered` and every post-publication `notices` entry. Common mistakes: - Passing a topic instead of a paper. A title resolves to its single best match; a phrase that names no specific paper resolves to the wrong one. - Reading an empty `citations` list as "uncited" when `notes` says the lookup was truncated. Args: paper: DOI (`10.1145/1571941.1572114`, or a doi.org URL), an OpenAlex ID (`W2148972377`), or the paper's exact title. direction: "both", "references" (what it cites) or "citations" (what cites it). limit: Max neighbours per direction, 1-50. format: "markdown" or "json".

Full-text search over pages already fetched into the local SQLite FTS5 index. Best for: - Recalling something the user/agent fetched earlier in the conversation ("what did that Wikipedia page say about X"). - Avoiding re-fetching content already in the local cache. - Quick keyword grep across the corpus you've built up. Not recommended for: - Discovering new pages on the open web -> use `search` or `research`. - When the cache is empty (fresh install) -> `search`/`research` first to populate it. Returns: - markdown (default): a per-hit list of title, URL, and a `[bracket]`- highlighted snippet around the matched terms. - json: list of {url, title, snippet, author, date, sitename}. The last three are "" when the cached row predates metadata capture. Common mistakes: - Treating this like web search: it ONLY hits pages already in the local cache. If the user hasn't fetched anything, you'll get zero hits. - Using natural-language phrases without quoting them; FTS5 splits on whitespace as AND. For an exact phrase use `"like this"`. Args: query: FTS5 query. Bare terms = AND. Supports OR / NOT, prefix (`term*`), and phrase (`"exact phrase"`). limit: Max hits to return. format: "markdown" or "json".

List the available sources, grouped by what they index. Best for: - Choosing a source deliberately: which one indexes filings, or preprints, or Chinese-language pages. - Checking a name before passing it to `engines=` on `search` / `research`. Not recommended for: - Calling on every search: the list is static, so read it once. Returns (markdown): a `group -> sub-group -> engine` tree, one line of description per engine. `group="paper"` restricts it to that group. Returns (json): `{"engines": [...names...], "taxonomy": {...}, "descriptions": {...}}`. Prefer `category=` over `engines=`. `category="paper"` WIDENS: it routes to one specialist per sub-group. A dotted sub-group NARROWS: `"paper.biomed"` queries only the biomedical indexes. Naming engines explicitly turns that routing off entirely, so reach for it only to force a specific source. Common mistakes: - Passing one of these names as `query`: they belong in `engines=`. - Passing a key-only engine with no key configured; it returns an actionable error, not results.

Fetch 2-5 URLs concurrently and return per-URL excerpts so the LLM can compare them against a single question in one round trip. Best for: - Side-by-side product/feature/article comparisons. - "Compare X to Y" or "How does A differ from B" queries. - Triangulating a fact across multiple sources. Not recommended for: - >5 URLs -> use `fetch_batch`. - 1 URL -> use `fetch`. - Don't have URLs yet -> use `search` or `research` first. Returns: - markdown (default): a comparison brief with per-URL sections, each containing title, sitename, published date, and a smart-truncated excerpt. - json: {question, urls, excerpts:[{url, title, excerpt, ...}], tokens_estimated}. Common mistakes: - Asking `compare` to actually answer the question: it returns material, the LLM does the comparison. - Passing >5 URLs and expecting them all to fit in context: use `fetch_batch` for bulk reads. Args: question: The comparison question the LLM will answer using the returned excerpts. urls: 2-5 absolute http(s) URLs. format: "markdown" (default) or "json".

Pull JSON-LD, OpenGraph, Twitter cards, and microdata from a web page. Best for: - Product pages (price, currency, availability, brand, rating). - Article pages (author, publish date, image, headline). - Recipe / event / video pages where rich metadata IS the answer. - Cases where `fetch` returns prose but you need fields. Not recommended for: - Just reading a page -> use `fetch`. - PDFs / DOCX -> use `read_doc`. - Pages that don't publish schema.org metadata (most blogs): you'll get empty lists; fall back to `fetch`. Returns: - json: {url, json_ld:[], microdata:[], opengraph:[], rdfa:[]}. Twitter card meta tags are surfaced inside the `opengraph` list. - markdown (default): a flattened key/value view with each block printed as a JSON code block under its syntax heading. Common mistakes: - Calling on every URL "just in case": most sites have no structured data, and `fetch` is what you actually want. Args: url: Absolute http(s) URL. format: "markdown" (default) or "json".

Save a file from a URL to a local, auto-expiring download directory. Downloads are enabled by default and saved under `SEARCH_MCP_CACHE_DIR/downloads`. Set `SEARCH_MCP_DOWNLOAD_ENABLED=false` to disable them or `SEARCH_MCP_DOWNLOAD_DIR` to override the destination. Best for: - Keeping an actual file (installer, dataset, archive, image) rather than its text. - Handing a path to another tool that needs a real file on disk. Not recommended for: - Reading a document's contents -> use `read_doc`, which parses it without touching the filesystem. - Looking at a web page -> use `fetch`. - Viewing an image -> use `fetch(inline=True)`. Returns: - markdown (default): where the file was saved, its size and type. - json: {url, saved_path, media_type, bytes_size, sha256, expires_in_hours}. An expires_in_hours value of 0 means TTL cleanup is disabled. Retention: files older than SEARCH_MCP_DOWNLOAD_TTL_HOURS (default 24) are deleted before the next download and at startup. A value of 0 disables TTL cleanup. Otherwise, treat the path as short-lived and copy it elsewhere if you need to keep it. Args: url: Absolute http(s) URL of the file to save. format: "markdown" or "json".