Crate ratatoskr 

Ratatoskr — the squirrel of Yggdrasil who runs messages between its roots and branches — carries questions out to the web and brings the answers back.

Ratatoskr::search asks sources in order and returns the first useful answer: its own meta-search first (Wikipedia’s and Grokipedia’s best page, and Yahoo, DuckDuckGo, Bing and Yandex, healthiest first, two or more at a time, each search from a fresh browser, merged and ranked; see engine::meta), then an external search server if configured, Brave’s and Google’s official APIs when keyed, and Wikipedia last — an encyclopedia, not web search, kept only for plain facts when nothing else answers. Ratatoskr::fetch reads a page as text.

Search is deliberately polite: a rate limit per engine, a cache so repeated questions never leave the machine, and a circuit breaker that stops asking an engine the moment it signals “no” (DuckDuckGo’s 202 anomaly page, 403, 429) and falls through to the next. A fetch reads one page a person asked for, as a browser would (see fetch), and can never reach loopback, private or link-local addresses.

Re-exports

pub use request::RequestError;

pub use request::SafeSearch;

pub use request::SearchRequest;

pub use request::TimeLimit;

Modules

engine

Search engines behind one interface.

fetch

Fetching a page as text, safely.

format

Results as numbered plain text: what the MCP tools hand a model and the command line prints. One block per result, its URL on its own line.

http

A local HTTP API: the MCP tools’ search and fetch for anything that can make an HTTP request (a script in any language, n8n, cron, an agent framework without MCP), served by one long-running process whose cache, engine health and pacing every caller shares. ratatoskr serve runs it.

mcp

An MCP server (Model Context Protocol, https://modelcontextprotocol.io) over stdio, offering two tools: web_search and web_fetch.

polite

Being a good citizen: a minimum spacing between requests to one engine, a circuit breaker that stops asking an engine that said no, and a small TTL cache so repeated questions never leave the machine.

request

What a search asks for, beyond the words: how many results, where, how recent, how safe, which page. Every engine reads what it supports and ignores the rest (an encyclopedia has no “past week”).

text

HTML to readable text for a model: headings, list items and paragraphs on their own lines, table cells separated by |, and links as Markdown [text](url) with absolute URLs, as Claude Code’s own WebFetch gives its model: without them a page’s “Scorecard” or “Next page” could not be followed.

vertical

Searches beyond web pages: news, images, videos and books.

Structs

Found

The results of a news, images, videos or books search.

Ratatoskr

SearchFailure

Why no engine could answer.

SearchOutcome

What a search produced, and where it came from.

Settings

Tunables; Settings::default is what production uses.

Sources

Which optional sources are configured. The meta-search (first) and Wikipedia (last) need nothing and are always present.

Verticals

The sources of the news, images, videos and books searches.

Functions

user_agent

The User-Agent of the API engines (Wikipedia, Grokipedia, Brave’s and Google’s APIs, a search server): who is asking, not a browser. The scraped engines and page fetches present as a browser instead (engine::browser).