Ratatoskr

ratatoskr

为 AI Agent 提供网页搜索和页面抓取功能，使用纯 Rust 编写，无需 API 密钥。

Ratatoskr 为 Agent 提供两种工具：

• web_search： 搜索网页、新闻、图片、视频或书籍，并汇总多个搜索引擎的结果；
• web_fetch： 将网页读取为保留链接的纯净文本，并且绝不会访问本地网络。

它可以作为供任何 Agent 使用的 MCP 服务（Claude Code、Codex、 Claude Desktop、Cursor、VS Code 等）、命令行工具、供脚本和自动化工具使用的本地 HTTP API，以及 Rust 库。在北欧神话中，Ratatoskr 是一只在世界树上往返传递消息的松鼠。

目录

• 快速入门 · 功能 · 安装
• MCP 服务 · 命令行 · HTTP API · 库
• 文档：工作原理、配置、性能、开发

快速入门

1. 安装 ratatoskr 命令，可以选择以下方式：
   • 使用 cargo binstall ratatoskr-web， 下载预构建的二进制文件，无需构建工具；
   • 从 发布页面 下载，同样是预构建版本；或
   • 使用 cargo install ratatoskr-web --locked 安装，此方式会进行构建，并需要 cmake 和 libclang。
2. 将它添加到你的 Agent 中，例如 Claude Code：

   claude mcp add ratatoskr -- ratatoskr mcp
   

   其他客户端请参阅 MCP 服务。
3. 或在终端中试用：

   ratatoskr search "tokio select macro"
   ratatoskr fetch https://www.rust-lang.org/
   

功能

• 无需 API 密钥。 开箱即用地进行搜索。Brave 和 Google 搜索 API 以及你自己的搜索服务都可作为可选备用方案。
• 五种搜索类型： 网页、新闻、图片、视频和图书，每种都提供类型化结果。每次搜索都可以按国家/地区本地化、限定为过去一天、一周、一个月或一年、通过安全搜索进行过滤，并支持分页。
• 元搜索，而非单一引擎： Yahoo、DuckDuckGo、Bing 和 Yandex， 以及 Wikipedia 和 Grokipedia 的最佳页面。结果会合并并排序，依据是有多少个引擎给出相同结果，以及结果与查询的匹配程度。
• 弹性可靠： 每个引擎都有自己的速率、健康记录和熔断器。一个引擎拒绝请求不会中止搜索。
• 易读的页面： HTML 会转换为包含标题、列表、表格和 [text](url) 链接的文本。也支持读取 PDF。
• 安全抓取： 私有地址、环回地址和链路本地地址都会被拒绝；连接时和每次重定向时都会进行检查。
• 小巧快速： 单个 10 MB 二进制文件。作为 MCP 服务运行时，空闲时约占用 6 MB，并在 0.01 s 内就绪（参见性能）。

安装

命令（ratatoskr）：

• 使用 cargo-binstall： cargo binstall ratatoskr-web 会从发布版本中获取适用于你平台的预编译二进制文件，无需构建工具。
• 预编译版本： 从适用于 Linux（x86_64、aarch64）、macOS（Intel、Apple Silicon）或 Windows（x86_64）的 发布版本下载二进制文件。请使用 SHA256SUMS 验证文件。
• 从 crates.io 安装： cargo install ratatoskr-web --locked。这需要 cmake 和 libclang；参见从源代码构建。
• 作为容器运行（Linux、amd64 和 arm64）： ghcr.io/haszerobyte/ratatoskr， 每个版本以及 latest 标签均可使用：

  docker pull ghcr.io/haszerobyte/ratatoskr
  docker run -i --rm ghcr.io/haszerobyte/ratatoskr                          # the MCP server on stdio
  docker run --rm ghcr.io/haszerobyte/ratatoskr search "tokio select"       # any other command
  

  packaging/docker/Dockerfile 可从源代码构建相同的镜像：docker build -f packaging/docker/Dockerfile .

库： 该软件包名为 ratatoskr-web，因为 ratatoskr 这个名称已在 crates.io 上被占用。在代码中，它仍然叫作 ratatoskr。

cargo add ratatoskr-web
cargo add tokio --features macros,rt-multi-thread

use ratatoskr::{Ratatoskr, Sources};

MCP 服务

ratatoskr mcp 通过 stdio 向 MCP 客户端提供两个工具。

web_search

• query，必填：要搜索的内容。
• type：web（默认）、news、images、videos 或 books。
• limit：1–20，默认值为 8。
• country：ISO 3166-1 alpha-2 代码，例如 US、IN 或 DE。
• time：day、week、month 或 year。不用于图书搜索。
• safesearch：on、moderate（默认）或 off。
• page：从 1 开始。

返回一个编号列表：

type	每条结果包含
web	标题、URL、摘要
news	标题、来源和日期（ISO 8601）、URL、摘要
images	标题、图片的 URL、尺寸和网站，以及图片所在页面
videos	标题、时长、发布者、日期和观看次数、URL、描述
books	标题、作者和年份、图书页面

将其添加到客户端。如果客户端的 PATH 中没有 ratatoskr，请改用其完整路径。它也已列入官方 MCP 注册表， 名称为 io.github.haszerobyte/ratatoskr，供从该注册表安装的客户端使用。

Claude Code

claude mcp add ratatoskr -- ratatoskr mcp
# with an optional fallback key:
claude mcp add ratatoskr -e BRAVE_SEARCH_API_KEY=… -- ratatoskr mcp

Codex（~/.codex/config.toml）

[mcp_servers.ratatoskr]
command = "ratatoskr"
args = ["mcp"]
# env = { BRAVE_SEARCH_API_KEY = "…" }

Claude Desktop（claude_desktop_config.json）、Cursor （~/.cursor/mcp.json）和大多数其他客户端

{
  "mcpServers": {
    "ratatoskr": { "command": "ratatoskr", "args": ["mcp"] }
  }
}

使用 Docker 而非已安装的二进制文件时，在以上任一配置中，将容器用作命令：

{ "command": "docker", "args": ["run", "-i", "--rm", "ghcr.io/haszerobyte/ratatoskr"] }

VS Code（.vscode/mcp.json）

{
  "servers": {
    "ratatoskr": { "type": "stdio", "command": "ratatoskr", "args": ["mcp"] }
  }
}

这些工具保留原有名称；Claude Code 将它们显示为 mcp__ratatoskr__web_search 和 mcp__ratatoskr__web_fetch。搜索或抓取失败时，会以模型可读取的工具错误形式返回，绝不会导致崩溃；请求会并发处理。此服务支持协议修订版本 2025-06-18、2025-03-26 和 2024-11-05。

要将此服务嵌入自己的程序，请调用 ratatoskr::mcp::serve_stdio(Arc::new(rt)).await，或使用任意读取器和写入器调用 ratatoskr::mcp::serve。

命令行

ratatoskr search <query> [limit] [country] [options]
ratatoskr fetch <url>
ratatoskr mcp                  # the MCP server, on stdin/stdout
ratatoskr serve                # the HTTP API, on 127.0.0.1:8765 (see below)

搜索选项：

• --type web|news|images|videos|books（默认值为 web）
• --time day|week|month|year
• --safesearch on|moderate|off
• --page N
• --country XX

$ ratatoskr search "tokio select macro" 2
engine: meta (bing, yandex; cached: false)
1. select in tokio - Rust
   https://docs.rs/tokio/latest/tokio/macro.select.html
   tokio. Macro select.The select! macro must be used inside of async functions, closures, and blocks…

2. Select | Tokio - An asynchronous Rust runtime
   https://tokio.rs/tokio/tutorial/select
   The tokio::select! macro allows waiting on multiple async computations and returns when a single…

$ ratatoskr search "raspberry pi 5" 2 --type news --time week
sources: bing, yahoo (cached: false)
1. The Raspberry Pi 5 16GB now costs $385, more than triple its launch price
   TechSpot · 2026-11-06T20:04:12Z
   https://www.techspot.com/news/114465-raspberry-pi-5-16gb-now-costs-385-more.html
   …

$ ratatoskr search "cricket scores" 5 IN      # results localized to India
$ ratatoskr search "dune" 3 --type books
$ ratatoskr fetch https://www.rust-lang.org/

成功时退出代码为 0，所有来源均失败时为 1，用法错误时为 2。

HTTP API

适用于 MCP 客户端以外的场景：任何语言编写的脚本、n8n、Home Assistant、cron，以及不使用 MCP 的 Agent 框架。一个长期运行的进程可为所有调用方提供服务，因此它们共享该进程的缓存、引擎健康状态和请求间隔；命令行每次运行都会重新开始。

ratatoskr serve                                   # http://127.0.0.1:8765
curl -s localhost:8765/search -d '{"query": "tokio select macro", "limit": 3}'
curl -s localhost:8765/search -d '{"query": "raspberry pi 5", "type": "news", "time": "week"}'
curl -s localhost:8765/fetch  -d '{"url": "https://www.rust-lang.org/"}'

Endpoint	Body	Answer
GET /health		{"status": "ok", "name", "version"}
POST /search	web_search 的参数：query、type、limit、country、time、safesearch、page	{"type", "query", "engine", "sources", "merged", "from_cache", "results": [...]}（engine 和 merged 仅用于 web）
POST /fetch	{"url"}	{"url", "title", "content_type", "truncated", "text"}
POST /search/text	{"query", "max_results", "region", "safesearch", "timelimit", "page"}	{"results": [{"title", "href", "body"}]}

除非提供令牌，否则它仅监听本机，并会拒绝来自网页的请求。错误代码、令牌和搜索服务器端点 /search/text：参阅 docs/http-api.md。

库

use ratatoskr::{Ratatoskr, Sources};

#[tokio::main]
async fn main() {
    // Optional keyed sources come from the environment (docs/configuration.md).
    let rt = Ratatoskr::standard(&Sources::from_env());

    match rt.search("rust async runtime", 5).await {
        Ok(found) => {
            // e.g. "meta (bing, yandex; 2 duplicates merged; cached: false)"
            println!("{}", found.provenance());
            for hit in found.hits {
                println!("{}\n  {}\n  {}", hit.title, hit.url, hit.snippet);
            }
        }
        // Every source failed or refused; each attempt is listed with its reason.
        Err(failure) => eprintln!("{failure}"),
    }
}

只需构建一次 Ratatoskr 并共享，例如将其放入 Arc 中。请求间隔、健康记录、断路器和缓存只有在对同一实例的调用之间才会生效。

搜索选项、新闻、图片、视频和图书搜索、抓取，以及自定义引擎和设置：参阅 docs/library.md。

文档

• 工作原理：元搜索及其排名、页面读取方式、礼貌原则和条款
• 配置：环境变量和可选的密钥来源
• HTTP API：端点、错误和安全性
• 库：Rust API
• 性能：测量结果以及如何运行基准测试
• 开发：从源代码构建、仓库布局、贡献和发布

贡献

欢迎提交问题和拉取请求。构建、需要运行的检查以及仓库布局，请参阅 docs/development.md。

许可证

本项目根据 Apache License, Version 2.0 授权。其声明请参阅 NOTICE。

除非你明确另行声明，否则任何有意提交以纳入本项目的贡献，均应按照上述许可证授权，不附加任何条款或条件。