Ratatoskr

ratatoskr

AI エージェント向けのウェブ検索とページ取得機能を、API キー不要で純粋な Rust で提供します。

Ratatoskr はエージェントに 2 つのツールを提供します。

• web_search: 複数のエンジンを統合して、ウェブ、ニュース、画像、動画、書籍を検索します。
• web_fetch: リンクを保持したままページを読みやすいテキストに変換し、ローカルネットワークには決してアクセスしません。

あらゆるエージェント（Claude Code、Codex、Claude Desktop、Cursor、VS Code など）向けの MCP サーバー、コマンドラインツール、スクリプトや自動化ツール向けのローカル HTTP API、そして Rust ライブラリとして利用できます。北欧神話では、Ratatoskr は世界樹を駆け上がったり駆け下りたりしてメッセージを運ぶリスです。

目次

• クイックスタート · 機能 · インストール
• MCP サーバー · コマンドライン · HTTP API · ライブラリ
• ドキュメント：仕組み、設定、パフォーマンス、開発

クイックスタート

1. ratatoskr コマンドをインストールします。方法は次のとおりです。
   • cargo binstall ratatoskr-web を使います。ビルド済みバイナリをダウンロードするため、ビルドツールは不要です。
   • リリースから入手します。こちらもビルド済みです。
   • cargo install ratatoskr-web --locked を使います。ビルドが必要で、cmake と libclang が必要です。
2. エージェントに追加します。例として 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、および独自の検索サーバーは、任意のフォールバックです。
• 5 種類の検索： ウェブページ、ニュース、画像、動画、書籍。それぞれ 型付きの結果を返します。すべての検索で、国によるローカライズ、過去 1 日、 1 週間、1 か月、1 年への期間制限、セーフサーチによるフィルタリング、 ページ分割が可能です。
• 単一エンジンではなく、メタ検索です： Yahoo、DuckDuckGo、Bing、Yandexに 加え、Wikipedia と Grokipedia の最適なページも検索します。結果は、合致する エンジンの数とクエリとの一致度に基づいて統合・ランキングされます。
• 高い耐障害性： 各エンジンはそれぞれ独自の処理速度、稼働状況の記録、 サーキットブレーカーを備えています。1 つのエンジンが応答を拒否しても、 検索全体は停止しません。
• 読みやすいページ： HTML を、見出し、リスト、表、[text](url)形式の リンクを含むテキストに変換します。PDF も読み取れます。
• 安全な取得： プライベート、ループバック、リンクローカルのアドレスへの 接続は、接続時およびリダイレクトのたびに拒否されます。
• 小型で高速： 10 MB のバイナリ 1 つです。MCP サーバーとしてのアイドル時の メモリ使用量は約 6 MB で、0.01 秒で起動します（パフォーマンスを参照）。

インストール

コマンド（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 .

ライブラリ： crates.io ではratatoskrという名前がすでに使われているため、 パッケージ名はratatoskr-webです。コード内では引き続きratatoskrです。

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

use ratatoskr::{Ratatoskr, Sources};

MCP サーバー

ratatoskr mcp は、stdio 経由で MCP クライアントに 2 つのツールを提供します。

web_search

• query、必須：検索する内容です。
• type：web（デフォルト）、news、images、videos、books のいずれかです。
• limit：1～20、デフォルトは 8 です。
• country：US、IN、DE などの ISO 3166-1 alpha-2 コードです。
• 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 Registry にも 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 を使わないエージェントフレームワークなどから利用できます。1 つの長時間実行プロセスがすべての呼び出しを処理するため、キャッシュ、エンジンの稼働状態、リクエスト間隔を共有します。コマンドラインでは、実行のたびに新しく起動します。

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/"}'

エンドポイント	本文	応答
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
• パフォーマンス：測定結果とベンチマークの実行方法
• 開発：ソースからのビルド、リポジトリの構成、コントリビュート、リリース

コントリビュート

Issue とプルリクエストを歓迎します。ビルド方法、実行すべきチェック、リポジトリの構成については、docs/development.md をご覧ください。

ライセンス

Apache License, Version 2.0 の下でライセンスされています。通知については NOTICE をご覧ください。

特に明記されていない限り、この作品への収録を意図して提出されたすべてのコントリビューションは、追加の条件を付さず、上記と同じライセンスの下でライセンスされます。