deepsearch

deepsearch

deepsearch は、研究者のように Exa のニューラルインデックスに質問します。通常の検索では、クエリの意味に最もよく一致するページが、テキストを取得済みの状態で返されます。コードに関する質問には、代わりにコンテキストパックが返されます。これは、ウェブ全体から集めたサンプルとドキュメントの抜粋を、指定したトークン予算に合わせたものです。目的のページがすでにわかっている場合は、クロールによってそのページを取得し、テキストを返します。コマンドラインから実行することも、エージェント向けの MCP サーバーとして実行することもできます。

Exa API キーが必要です。EXA_API_KEY 環境変数に設定してください。キーは x-api-key ヘッダーで API に送信され、出力には表示されません。この変数が設定されていない場合、すべての操作は変数名を示すエラーで失敗します。

インストール

npx @reneturcios/deepsearch search "vector index tradeoffs"

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

docker run -i -e EXA_API_KEY ghcr.io/cloudcorprecords/deepsearch

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

CLI

export EXA_API_KEY="your api key"

# Web search; --num-results defaults to 8
deepsearch search "ferry electrification programs"
deepsearch search "ferry electrification programs" --num-results 5

# Code context; --tokens sets the budget (1000-50000, default 5000)
deepsearch code "React useState hook examples" --tokens 3000

# Fetch one page in full
deepsearch crawl https://example.com/some/article
deepsearch crawl https://example.com/some/article --tokens 2000

# Machine-readable output for any command
deepsearch search "ferry electrification programs" --json

deepsearch --version

終了コード：成功時は 0、操作の失敗時（EXA_API_KEY が未設定の場合や API エラーを含む）は 1、使用方法のエラー時は 2 です。

MCP サーバー

1 つのバイナリで両方の用途に対応します。mcp サブコマンドは stdio MCP サーバーを起動します。

npx -y @reneturcios/deepsearch mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "deepsearch": {
      "command": "npx",
      "args": ["-y", "@reneturcios/deepsearch", "mcp"],
      "env": { "EXA_API_KEY": "your api key" }
    }
  }
}

ツール

これらは、元のサーバーでデフォルトで有効になっているツールです。

ツール	入力	返される内容
web_search_exa	query（文字列、必須）、numResults（数値、省略可、デフォルトは 8）	一致するページを番号付きのテキストブロックとして返します。タイトル、URL、判明している場合は公開情報、および API が取得したページのテキストが含まれます。
get_code_context_exa	query（文字列、必須）、tokensNum（数値、省略可、1000～50000、デフォルトは 5000）	質問に関連するコードサンプルとドキュメントの抜粋を、出典ごとに見出しを付け、トークン予算に合わせて調整して返します。
crawling_exa	url（文字列、必須）、tokensNum（数値、省略可、デフォルトは 5000）	指定したページ 1 件の全文を、タイトル付きでトークン予算に合わせて調整して返します。

トークン予算は、ドキュメントに記載された 1000～50000 の範囲に収まるよう調整され、およそ 1 トークンあたり 4 文字として適用されます。結果が空の場合はその旨が報告されます。API が取得できないページ、キーの未設定、API 呼び出しの失敗は、ツールエラーとして報告されます。

開発

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 を参照してください。