researchsearch

researchsearch

researchsearch は、Tavily API を利用したウェブ向けのリサーチデスクです。順位付けされたコンテンツ付きの検索結果（任意で生成された回答も含む）を検索し、特定のページから読みやすいテキストを抽出し、設定した制限の範囲内でサイトをページごとにクロールし、サイトの構造をマッピングして、読む前に掲載内容を確認できます。コマンドラインから、またはエージェント向けの MCP サーバーとして利用できます。

Tavily API キーが必要です。TAVILY_API_KEY 環境変数に設定してください。設定されていない場合、リクエストを送信する前に、不足している変数名を示すエラーが発生し、すべての操作が停止します。

インストール

export TAVILY_API_KEY="tvly-..."
npx @reneturcios/researchsearch search "composting basics"

または、コンテナイメージを実行します。

docker run -i -e TAVILY_API_KEY="tvly-..." ghcr.io/cloudcorprecords/researchsearch

コンテナはデフォルトで MCP サーバーを起動します（下記を参照）。CLI として使うには、CLI 引数を渡してください。

CLI

# Search; results print as JSON
researchsearch search "composting basics"
researchsearch search "rate decision" --topic news --days 3 --max-results 5 --answer

# Extract the clean content of one or more pages
researchsearch extract https://example.com/article
researchsearch extract https://example.com/a https://example.com/b --depth advanced

# Crawl a site from a starting page
researchsearch crawl https://example.com --max-depth 2 --limit 25
researchsearch crawl https://example.com --instructions "Focus on the guides"

# Map a site's structure (URLs only, no page content)
researchsearch map https://example.com --max-depth 1 --limit 50

researchsearch --version

終了コード：成功時は 0、操作の失敗時は 1（TAVILY_API_KEY の未設定、サービスからの HTTP エラー、ホストに到達できない場合）、使用方法のエラー時は 2 です。

MCP サーバー

1 つの実行ファイルで両方の使い方に対応します。mcp サブコマンドで、標準入出力を使用する MCP サーバーを起動します。

npx -y @reneturcios/researchsearch mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "researchsearch": {
      "command": "npx",
      "args": ["-y", "@reneturcios/researchsearch", "mcp"],
      "env": {
        "TAVILY_API_KEY": "tvly-..."
      }
    }
  }
}

ツール

ツール	入力	返される内容
tavily-search	query（文字列、必須）、search_depth、topic、days、max_results、include_answer、include_raw_content、include_domains、exclude_domains（すべて任意）	順位付けされた結果とコンテンツの抜粋およびスコア。さらに、要求された場合は生成された回答とページの生コンテンツも返します。
tavily-extract	urls（文字列配列、必須）、extract_depth、include_images、query（任意）	各ページから抽出した読みやすいコンテンツ。失敗は個別に報告されます。
tavily-crawl	url（文字列、必須）、max_depth、max_breadth、limit、instructions、extract_depth（任意）	開始 URL から訪問したページと、それぞれから抽出したコンテンツ。
tavily-map	url（文字列、必須）、max_depth、max_breadth、limit、instructions（任意）	ページのコンテンツを含まない、開始ページから到達可能な URL の一覧。

各ツールは、対応する Tavily API エンドポイントを 1 回呼び出します。設定したパラメーターのみが送信されます。未設定の任意パラメーターは省略され、サービス独自のデフォルト値が適用されます。各レスポンスはサービスの JSON で、変更されずに返されます。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。