tinysearch

TinySearch

トークンはウェブページではなく、回答に使いましょう。

TinySearch はウェブをローカルで検索、クロール、再ランキングし、エージェントのコンテキストに含める価値のある根拠だけを提供します。

ドキュメント · クイックスタート · Python · Discord

TinySearch は AI エージェント向けのセルフホスト可能なウェブ調査ツールです。ウェブを検索し、最適なページを読み込み、価値の低いコンテンツを取り除いて、ソース URL 付きの簡潔な根拠を返します。

モデルはウェブページ全体の処理にトークンを費やすことなく、有用な文章を受け取れます。

TinySearch は TinySuite の一部です。スマートな検索、選択、コンテキスト管理の手法によってトークン使用量を最小限に抑え、エージェントによる操作のコスト削減を目指す、特化型ツールのスイートです。

利用するティアを選ぶ

ティア	こんな場合に使用	エントリーポイント	検索バックエンド
1. Python ライブラリ	TinySuite または Python を使って開発する場合	pip install tinysuite-search	DDGS
2. ワンコマンド MCP	MCP クライアントから TinySearch を起動する場合	uvx --from "tinysuite-search[server]" tinysearch	DDGS
3. Docker + SearXNG	セルフホスト可能なフルスタックと HTTP MCP が必要な場合	docker compose ... up -d	同梱の SearXNG

ティア 1 と 2 では検索サービスは不要です。ティア 3 では専用の SearXNG サービス、永続的なモデルストレージ、ネットワーク MCP エンドポイントが追加されます。Docker のセットアップについてはインストールガイドをご覧ください。

エージェントによるリサーチでコストがかかるのはコンテキストです

検索結果は、まだ有用な証拠ではありません。エージェントは多くの場合、複数のページを開き、ナビゲーションや定型文を読み込み、どの箇所が重要かを判断するために有料の入力トークンを消費します。

TinySearch は、こうした処理をモデルの前段階で行います。

flowchart LR
    A[Question] --> B[Search and crawl]
    B --> C[Local hybrid reranking]
    C --> D[Compact evidence<br/>with source URLs]
    D --> E[Your agent]

これにより、次の 3 つの方法でコストを削減できます。

• モデルのコンテキストを縮小。 厳密に設定された証拠の予算内で、最も順位の高い証拠チャンクのみを返します。
• デフォルトでは従量課金制の検索 API は不要。 TinySearch は有料の検索プロバイダーを使わずに DDGS で検索できます。
• デフォルトではローカルで検索。 ONNX 埋め込みとハイブリッド再ランキングは、埋め込み API の料金を発生させずに、お使いのマシン上で実行されます。

幅広く検索し、ローカルで読み込みます。重要な証拠にだけモデルの料金を支払います。

これは要約ではなく、検索です。TinySearch はローカルの BM25 と埋め込みの再ランキングを使って残す価値のある箇所を選択します。ページをモデルに処理させて書き換えたり、要約したりすることはありません。返される各チャンクは元のページのテキストそのままで、編集されていません。そのため、引用する内容はページに実際に書かれている内容です。専用の縮約モデルほど積極的にコンパクト化できない代わりに、パイプラインは高速で、ローカルで無料で実行できます。学習済みの縮約ステップは今後検討する可能性がありますが、現時点では TinySearch に含まれていません。

実際の節約効果は、ページ、証拠の上限、クライアントのモデル、プロバイダーの料金設定によって異なります。TinySearch はモデルに送るウェブコンテンツを削減しますが、その後クライアントが証拠をどのように扱うかは制御しません。

コストのパネルでは、入力トークン 100 万個あたり 3.00 ドルという参考レートを使用し、検索、クロール、モデルの出力、および後続のエージェントによる利用は除外しています。

素朴なベースラインは、現実離れした比較対象ではありません。各クエリで TinySearch がクロールしたのと同じページを、フィルタリングせずにモデルへ渡しています。これは、汎用的な「検索してからページを取得する」ツール（ほとんどのコーディングエージェントに組み込まれている、単純なウェブ検索と取得のループ）の動作を再現したものです。現時点で推奨されているフロー（search の後に scrape_urls）を使い、TinySearch の主要インターフェースである、実際の MCP ツール結果のテキストを対象に測定しています。自分で再現または再実行できます。

python scripts/benchmark_token_savings.py --json-out report.json

クイックスタート

uv がインストールされていれば、任意の MCP クライアントに TinySearch を追加できます。

{
  "mcpServers": {
    "tinysearch": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "tinysuite-search[server]",
        "tinysearch"
      ]
    }
  }
}

クライアントは必要に応じて、stdio 経由で TinySearch を起動します。リポジトリのクローン、ホスト型アカウント、有料の検索キーは必要ありません。

高速な search は、Chromium や埋め込みモデルなしで開始できます。最初のスクレイピング時に Chromium が初期化され、対象を絞ったスクレイピングでは設定済みの埋め込みモデルも初期化されます。これらのワークフローを使う場合は、事前に両方をウォームアップしてください。

uvx --from "tinysuite-search[server]" tinysearch setup

MCP サーバーと FastAPI サーバーは、連続したリクエストの間はスクレイパーのブラウザーを起動したままにし、browser_idle_shutdown_seconds 経過後に終了します。Python を直接呼び出す場合は、呼び出し元が管理する短時間のライフサイクルが維持されます。

Docker、リモート MCP エンドポイント、またはソースコードからのチェックアウトをご希望ですか？インストールガイドをご覧ください。

MCP ツール

ツール	使用する場面
search(items)	クロールや再ランキングを行わず、バックエンド順で素早く検索したい場合。必要に応じて、独立したサブ質問をまとめて検索します
scrape_urls(items)	1〜5 ページが既知の場合。各項目では、設定済みのページ順トークン予算に * を使用できます
browser_navigate / browser_act	ページを読む前に操作が必要な場合。ブラウザー自動化を参照してください
get_current_datetime()	質問が現在の日付や時刻に関する場合

TinySearch は意図的に対象を絞っています。これは検索レイヤーであり、別の エージェント、チャットインターフェイス、ホスト型検索製品、永続的なウェブインデックスではありません。

パラメーターとレスポンスの仕様については、完全版のMCP ツールリファレンス を参照してください。

エージェントが取得できる内容

TinySearch は、最終回答を作成するために別のモデル呼び出しを行いません。推奨される流れは、軽量な検索に search を使い、読む価値のあるページに scrape_urls を使うことです。

検索結果は構造化 JSON で返されます。単純な検索には 1 項目を使用し、独立したサブ質問やソース戦略がある場合にのみ複数の項目を追加してください。domains はソースを厳密に指定する肯定的な制限で、ドメインとそのサブドメインを指定できます。

{"items":[{"query":"Form 8-K Tesla","domains":["sec.gov"]}]}

各検索項目には、それぞれの結果と簡潔なバックエンド試行情報が含まれます。結果が 0 件の場合のレスポンスは、ブロックされた場合、利用できない場合、無効なバックエンドの場合とは区別されます。 scrape_urls は、選択した Markdown の根拠情報と、関連リンクの個別のナビゲーション候補を返します。それぞれに、独立した設定済みトークン上限が適用されます。

MCP では引き続き、プロトコルレベルのエラーやオプションの structuredContent を含む標準の JSON-RPC トランスポートエンベロープが使用されます。Python と FastAPI は、根拠情報を保存、検査、変換する必要があるアプリケーション向けに、構造化 JSON の仕様を維持しています。

仕組み

1. search は、Chromium や埋め込みモデルを起動せずに、バックエンド順のタイトル、URL、プレビュー、上流の日付、バックエンドの結果を返します。
2. scrape_urls は、既知の 1〜5 ページを並行して読み込みます。項目のクエリを省略するか "*" を使用すると、設定済みのトークン予算内でページ順のクリーンな Markdown が返されます。
3. TinySearch がページをチャンク化し、ハイブリッドランキングを行ってから根拠情報を返すようにするには、項目に焦点を絞ったクエリを指定します。
4. scrape_urls でコンテンツにアクセスできず、操作が必要な場合にのみ、browser_* ツールを使用します。ブラウザー自動化を参照してください。

Python ライブラリ

TinySearch は通常の Python パッケージとしても使用できます。

pip install tinysuite-search

オプションの OpenTelemetry エクスポート

TinySearch は、OpenTelemetry が明示的に設定されている場合にのみ、ベンダーに依存しないトレースとメトリクスを出力します。テレメトリがインストールされていない場合や設定されていない場合でも、通常のライブラリ、MCP、FastAPI の動作に変更はありません。

スタンドアロン MCP サーバーにオプションのエクスポーターサポートをインストールします。

uvx --from "tinysuite-search[server,telemetry]" tinysearch

公式 Docker イメージにも同じオプションのサポートが含まれています。どちらのデプロイ方法でも標準の OTel 変数を設定できます。共通のエンドポイントを設定すると、トレースとメトリクスが有効になります。

OTEL_SERVICE_NAME=tinysearch \
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
tinysearch serve

デフォルトは http/protobuf で、grpc もサポートされています。テレメトリを無効にするには、OTEL_TRACES_EXPORTER=none、OTEL_METRICS_EXPORTER=none、または OTEL_SDK_DISABLED=true を使用してください。標準のリソース、ヘッダー、タイムアウト、サンプラー、およびシグナル固有のエンドポイント設定は OpenTelemetry SDK に渡されます。OTEL_EXPORTER_OTLP_HEADERS はシークレットとして扱ってください。

TinySearch は、操作／ステージの所要時間、結果、件数、バックエンドの状態、ブラウザーの使用状況、トークン数、埋め込みモデルのメタデータを出力します。クエリ、URL、ドメイン、プロンプト、ドキュメント、スニペット、リクエストヘッダー、認証情報、設定パス、生のエラー、例外スタック、MCP の引数、MCP の結果は出力しません。Python ライブラリを直接使用する場合、OTel プロバイダーは各自で設定してください。TinySearch が自動設定するのは、スタンドアロン MCP サーバーと FastAPI サーバーのエントリーポイントのみです。

import asyncio
from tinysearch import scrape_urls, search


async def main():
    results = await search([{"query": "Python async tasks"}])
    print(results["items"][0]["results"])

    page_url = results["items"][0]["results"][0]["url"]
    evidence = await scrape_urls([{
        "url": page_url,
        "query": "How does asyncio cancellation work?",
    }])
    print(evidence["results"])


asyncio.run(main())

Python API は、安定した JSON シリアライズ可能な結果を返します。search は 1～5 件の項目を受け付け、設定された項目ごとの結果上限を使用します。scrape_urls は呼び出しごとの max_tokens 予算（デフォルトは 4,000）を受け付けます。項目のスクレイプクエリを省略するか、ページ順モードには "*" を使用してください。構造化されたエビデンスを LLM プロンプトに変換する処理は明示的に行うため、アプリケーションでは結果を先に保存、確認、変換したり、予算を設定したりできます。

オプションの FastAPI アプリは、これらのインターフェースに対応しています。POST /search は同じバッチ JSON コントラクトを受け付けます。 POST /scrape は 1～5 件の { "url", "query" } 項目を受け付け、項目ごとに構造化された結果を常に返します。 POST /browser/navigate と POST /browser/act は 2 つの MCP ブラウザーツールに対応し、アクセシビリティビューを { "result": "..." } として返します。 また、アプリは /health、/current_datetime、読み取り専用の /config も公開します。設定の書き込みには、明示的な環境変数によるオプトインが必要です。

検索バックエンド

TinySearch は設定からウェブ検索バックエンドを選択するため、検索サービスなしで始め、後からコードを変更せずに追加できます。

• "ddgs"（ネイティブのデフォルト）：ddgs パッケージの自動バックエンド選択機能をプロセス内で呼び出します。SearXNG のデプロイは不要です。
• "searxng"（Docker のデフォルト）：セルフホストした SearXNG インスタンスにクエリを送信します。search_backend_fallback が false に設定されていない限り、バックエンドでエラーが発生すると ddgs にフォールバックします。
• "duckduckgo"：SearXNG を経由せず、DuckDuckGo のみを使用するモードで ddgs にクエリを送信します。
• "auto"：SearXNG を試し、バックエンドでエラーが発生した場合は ddgs にフォールバックします。

BRAVE_SEARCH_API_KEY 環境変数を設定すると、ddgs および duckduckgo バックエンドのキー認証付きフォールバックとして、Brave の公式 Web Search API を追加できます。Brave が呼び出されるのは、プライマリの呼び出しでエラーが発生した場合、または結果が返されない場合のみです。

キーの完全なリファレンス、SearXNG の JSON 出力設定、Compose の詳細については、設定リファレンスをご覧ください。

ブラウザーの自動化

scrape_urls は静的なフェッチです。読み込み後に JavaScript が描画するコンテンツ、Cookie 同意画面の背後にあるコンテンツ、「さらに読み込む」コントロール、クライアント側の検索 UI は取得できません。そうしたページでは、TinySearch が実際のブラウザーを操作します。

追加のインストール費用はかかりません。TinySearch はすでに Crawl4AI 経由で Playwright に依存しており、スクレイピング用の Chromium もインストールするため、ブラウザーツールは同じドライバーと同じブラウザーを再利用します。2 つ目のランタイムもブラウザーも子プロセスも必要ありません。

ツールは 2 つあります。browser_navigate と browser_act です。後者は、look、click、type、wait_for、tabs、close を 1 つの action パラメーターにまとめています。

この分け方は意図的です。MCP にはツールをグループ化したり入れ子にしたりする方法がありません。tools/list はフラットで、リクエストごとにすべてのスキーマがモデルに再送されます。そのため、ブラウザー用ツールを 7 つに分けると、サーバーのスキーマの大半を占めてしまいます。エントリーポイントを独立したツールとして公開し、1 つのページセッションのライフサイクルをディスパッチャーにまとめることで、ツール 5 つ分のサーバースキーマ全体を小さく保てます。

検索は結果に対するフィルターであり、クリックと並ぶ機能ではないため、独立した検索ツールはありません。どちらのツールも find 引数を 1 つ受け取り、まず正規表現として試します（そのため、"a|b" もそのまま使えます）。有効な正規表現ではない場合は、大文字と小文字を区別しないリテラル部分文字列検索にフォールバックし、ツリー全体ではなく、一致したノードとそのコンテキストに返却内容を絞り込みます。これにより、1 回の呼び出しで操作と結果の報告の両方ができます。テーブルを表示するクリック操作では、そのテーブルが返されるため、エージェントが最初の応答を絞り込むために 2 回目の呼び出しをする必要はありません。以前のバージョンでは、これを find と find_regex に分けていました。プレーンな部分文字列用パラメーターに対してモデルが交互選択構文を使い、「ヒント」ではなく「一致なし」が返されるたびに、無駄な往復が発生していたため、2 つを統合しました。

モデルは、各ノードに安定した ref が付いた簡潔なアクセシビリティツリーを読み取り、ref に名前を付けます。TinySearch は実際のブラウザー入力イベントを使って操作します。

browser_navigate  -> url: "...", find: "Accept"   -> "- button \"Accept all\" [ref=e79]"
browser_act       -> action: "click", target: "e79", find: "Results"

DOM イベントを合成したり、CSS セレクターを作り出したりすることはありません。click／type が受け付けるのは、モデルが実際に確認した ref のみで、生のセレクターは受け付けません。

意図的に採用した設計上の選択肢は 3 つあります。

• コードを実行できるツールはありません。 evaluate ツールはなく、フォーム入力、アップロード、ドラッグを行うツールもありません。ページが描画したテキストに指示を埋め込んでも、危険な操作に使える機能はありません。利用を控えるよう促すのではなく、機能自体を備えていないためです。
• トークンを節約する手段は find、代替手段は depth です。 ビューを返すすべての呼び出しで find を指定でき、一致したノードとそのコンテキストに結果を絞り込みます。対象を指定するフィルターがない場合、depth は切り詰めた文字列ではなく、浅くても有効なツリーを返します。大きなページでは、約 33,000 文字ではなく約 700 文字になります。
• Cookie は保持しますが、セッションは保持しません。 browser_storage_state_path を設定すると、一度同意した同意バナーが、その後のナビゲーションのたびに表示されることはありません。セッションは分離されるため、ブラウザープロファイルのロックは発生せず、同時に接続するクライアント同士も競合しません。このファイルはサーバー側のパスであり、モデルにも HTTP 経由にも公開されません。

ツールを完全に無効にするには、"browser_backend": "off" を設定します。その場合、ツールは実行を拒否するだけでなく、ツール一覧から削除されます。

CDP 経由の外部ブラウザー

別途操作するブラウザーを制御するには、その Chrome DevTools Protocol エンドポイントを設定します。この設定は、スクレイピングパイプラインとブラウザーツールの両方で使用されます。

{
  "browser_cdp_url": "http://browser:9222"
}

サーバープロセスは TINYSEARCH_BROWSER_CDP_URL も受け付けます。外部ブラウザーの実行ファイル、プロファイル、プロキシ、フィンガープリントの設定は外部ブラウザー側で管理されます。TinySearch が特定のブラウザーバックエンドを選択したり、インストールしたりすることはありません。

CDP エンドポイントは、ブラウザーをリモートから制御できる特権的なエンドポイントとして扱ってください。プライベートネットワークまたはループバックインターフェース上で運用し、ホストの境界を越えて接続する場合は認証を必須にしてください。また、ポート 9222 をパブリックインターネットに直接公開しないでください。TinySearch 自体を Docker で実行する場合、localhost は TinySearch コンテナを指すため、そのコンテナから到達可能なエンドポイントを使用してください。

browser_backend、browser_cdp_url、browser_storage_state_path はオペレーターが管理する設定であり、設定の書き込みが有効な場合でも、HTTP の PUT /config エンドポイントから変更することはできません。起動環境（TINYSEARCH_BROWSER_BACKEND など）または TINYSEARCH_CONFIG_PATH で指定したファイルで設定し、その後 TinySearch を再起動してください。HTTP クライアントは、部分更新からこれらのフィールドを省略すれば、引き続き他の設定を更新できます。

プロキシ

クロールをプロキシ経由で行うには、browser_proxy_server を設定します。

{
  "browser_proxy_server": "http://gateway.proxyprovider.com:8000",
  "browser_proxy_username": "your-username",
  "browser_proxy_password": "your-password"
}

Playwright が受け付けるものと同様に、http、https、socks5 のプロキシ URL をサポートしています。プロバイダーから固定ゲートウェイのエンドポイントが複数提供される場合は、コンマで区切って指定すると、TinySearch は新しいブラウザーコンテキストごとに 1 つをラウンドロビン方式で選択します。

{
  "browser_proxy_server": "http://gw1.proxyprovider.com:8000, http://gw2.proxyprovider.com:8000"
}

プロキシを経由させないホストのコンマ区切りリストを指定するには、browser_proxy_bypass を使用します。上記の CDP 設定と同様、これら 4 つのフィールドはオペレーターが管理します。TINYSEARCH_BROWSER_PROXY_SERVER、TINYSEARCH_BROWSER_PROXY_USERNAME、TINYSEARCH_BROWSER_PROXY_PASSWORD、TINYSEARCH_BROWSER_PROXY_BYPASS、または設定ファイルで設定できますが、HTTP 経由では設定できません。

TinySearch を選ぶ理由

• ベンダーを介しません。 TinySearch アカウントも、必須の API キーも、リクエストごとの課金も、分析サービスも、スクレイピングデータをホストするキャッシュも必要ありません。検索 API に支払うことになるインフラストラクチャは、お使いのマシン上で動作します。
• 仕組み上、情報源に基づいています。 すべてのエビデンスチャンクは、元のページのテキストであり、取得元の URL と引き続き紐づいています。そのため、エージェントの回答内の主張は、「ベンダーのモデルがこう言った」というところで止まらず、特定の箇所までたどれます。
• トークン効率を重視して設計されています。 コンテンツがモデルのコンテキストに入る前に、ページと文章の選択がローカルで行われます。
• 有料インフラストラクチャがなくても便利です。 DDGS 検索とローカルの ONNX 埋め込みがデフォルトです。
• 必要に応じて独自のスタックを利用できます。 SearXNG と OpenAI 互換の埋め込みプロバイダーも、オプションで利用できます。
• エージェントがすでに動作している環境で利用できます。 stdio、Streamable HTTP、Python、FastAPI、Docker 経由で MCP を使用できます。

TinySuite の一部

TinySuite は、「エージェントは運用上のオーバーヘッドではなく、有用な作業にトークンを使うべきである」という考えに基づいて構築された製品スイートです。

各ツールはエージェントのワークフローの異なる部分に特化し、モデルに届く前に不要なコンテキストを減らすための手法を用います。TinySearch は、ページを小規模で順位付けされた、情報源に基づくエビデンスパケットに変換し、ウェブ調査のレイヤーを担います。

ドキュメント

README は製品の概要です。詳細なセットアップと運用に関する資料は、TinySuite のドキュメントにあります。

• TinySearch の概要とインストール
• 設定リファレンス
• MCP ツール
• トラブルシューティング

リポジトリには、注釈付きの設定例も configs/tinysearch_config.json に含まれています。

TinySearchを使用すべきでない場合

TinySearchは意図的に軽量に設計されています。次の要件がある場合は、商用検索API、永続的なクローラー、または完全な検索インデックスを使用してください。

• 検索範囲の保証またはSLA
• 大規模なインデックス作成、またはスケジュールされたインデックス作成
• 長期的なページ保存と変更履歴
• エンタープライズ向けの可観測性とアクセス制御

開発

git clone https://github.com/TinySuiteHQ/TinySearch
cd TinySearch
python -m venv .venv
source .venv/bin/activate
pip install -e ".[server]"
python -m unittest discover tests

TinySearchはPython 3.12以降に対応しています。CIでは、Linux、macOS、WindowsでPython 3.12、3.13、3.14をテストしています。

エントリーポイント

• tinysearch.search と tinysearch.scrape_urls：構造化Python API
• tinysearch.get_current_datetime：構造化されたUTC日時
• tinysearch.to_prompt：構造化されたエビデンスのみを使うプロンプトレンダラー
• tinysearch mcp：stdio MCP サーバー（引数なしの場合のデフォルトでもあります）
• tinysearch serve：Streamable HTTP MCP サーバー
• tinysearch.servers.fastapi_server:app：オプションのFastAPIアプリケーション

コミュニティ

質問、アイデア、バグ報告を歓迎します。

• TinySearch Discordに参加
• GitHub issueを作成
• メンテナーにメール

プライバシーとライセンス

TinySearchは公開ページを読み取り、選択した抜粋を呼び出し元のクライアントに返します。検索、クロール、ローカル埋め込み、再ランキングは、ページの内容を埋め込みプロバイダーに送信せずに実行できます。OpenAI互換の埋め込みバックエンドを選択した場合、そのプロバイダーにはベクトル化のために送信されたテキストが渡されます。

TinySearchはMITライセンスの下で利用できます。ダウンロードしたモデルの重みには、それぞれのモデルカードのライセンスが適用されます。サードパーティの配布に関する詳細は、NOTICEをご覧ください。