searchport

searchport

searchport は、5 種類の Brave 検索にアクセスできる単一の窓口です。1 つの質問を、ウェブ全般のインデックス、地域のお店のリスト、最新ニュース、画像、動画のいずれかに対して検索できます。どの検索結果も同じ形式で返されます。タイトル、掲載先の URL、短い抜粋に加え、検索の種類に応じた詳細が 1 行表示されます。記事が公開されてからの経過時間、動画の再生時間、店舗の所在地と評価などです。コマンドラインから実行することも、エージェント向けの MCP サーバーとして実行することもできます。

Brave Search API のサブスクリプションキーが必要です。BRAVE_API_KEY 環境変数に設定してください。キーは X-Subscription-Token ヘッダーで API に送信され、出力には表示されません。環境変数が設定されていない場合、すべての検索でその名前を示すエラーが発生します。

インストール

npx @reneturcios/searchport web "trail running shoes"

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

docker run -i -e BRAVE_API_KEY ghcr.io/cloudcorprecords/searchport

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

CLI

export BRAVE_API_KEY="your subscription key"

# General web search; --count is results per page (max 20),
# --offset pages forward (max 9)
searchport web "composting basics"
searchport web "composting basics" --count 5 --offset 1

# The other four kinds take the same query and --count
searchport local "bakery near the mission" --count 5
searchport news "trail network vote"
searchport images "ridge sunrise"
searchport videos "trail running form"

# Machine-readable output for any kind
searchport web "composting basics" --json

searchport --version

終了コード：成功時は 0、検索失敗時（BRAVE_API_KEY が設定されていない場合や API エラーを含む）は 1、使用方法のエラー時は 2 です。

MCP サーバー

1 つの実行ファイルで両方の用途に対応します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/searchport mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "searchport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/searchport", "mcp"],
      "env": { "BRAVE_API_KEY": "your subscription key" }
    }
  }
}

ツール

ツール	入力	返される内容
brave_web_search	query（文字列、必須）、count（数値、省略可）、offset（数値、省略可）	番号付きのテキストブロック形式のウェブ検索結果：結果ごとのタイトル、URL、抜粋。
brave_local_search	query（文字列、必須）、count（数値、省略可）	ローカルの店舗情報：名前、URL、API が提供する場合は住所、電話番号、評価を含む詳細行。
brave_news_search	query（文字列、必須）、count（数値、省略可）	ニュース記事：見出し、URL、概要、記事の経過時間。
brave_image_search	query（文字列、必須）、count（数値、省略可）	画像検索結果：タイトル、掲載元ページの URL、画像の直接 URL。
brave_video_search	query（文字列、必須）、count（数値、省略可）	動画検索結果：タイトル、URL、説明、再生時間。

件数は API の 1 ページあたりの上限である 20 件に、オフセットは最大値の 9 に制限されます。検索結果がない場合はその旨が返され、エラーにはなりません。キーが設定されていない場合や 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 を参照してください。