codescout

codescout

コードベース検索は仕事の半分にすぎません。検索結果として数十個のファイルが返されたあと、どれを最初に開くかは、誰かが判断しなければなりません。codescout は、固定されていて確認可能なルールを使って、その判断を行います。すでに得られた検索結果を渡してください。各結果について、対象のファイル、そのファイル内の一致数、ファイルが最後に変更されてから経過した日数、分かる場合はファイルの所有者を指定します。すると、スコアと所有者の情報を付けて、最適なものから順にランク付けした結果が返されます。独自の検索は行わず、インデックスにも触れません。ランキングルールそのものが、このツールのすべてです。

すべての検索結果は同じ方法でスコア化されます。matches * 100 - last_modified_days。一致ごとに100点を加算するため関連性が優先され、一方で経過日数に応じてファイルのスコアが少しずつ下がります。一致が1件だけの古いファイルはスコアが0を下回ることがあり、その負のスコアは0に丸められず、そのまま報告されます。スコアの順に並べ、同点の場合は、一致数が多いファイル、より最近変更されたファイル、コードユニット順のパスの順で順位を決めます。ルールは変わらないため、入力された順序にかかわらず、同じ検索結果のセットからは常に同じランキングが得られます。

リストの上位だけが返されます。limit で返す結果の最大数を指定でき、既定値は10です。返される各項目には、返されたリスト内の1始まりの位置を示す rank と、入力値をそのまま反映した path、matches、last_modified_days、owner が含まれます。所有者については、所有者が指定されていない、空、または空白文字のみの場合、そのファイルは所有者なしとみなされ、所有者は null として報告されます。それ以外の所有者文字列は、指定されたとおりにそのまま反映されます。件数には、入力された検索結果の数と返された検索結果の数が示されます。

形式が不正な入力（検索結果リストがない、または空、検索結果がオブジェクトではない、path がない、空、または文字列ではない、matches がない、小数、または1未満、last_modified_days がない、小数、または負の値、owner が文字列ではない、あるいは limit が1未満）は、該当するパスを示す検証エラーとなり、部分的な結果は返されません。同じパスの検索結果が2件ある場合は、重複したパスを示すエラーとなります。不明な追加フィールドは無視されます。

CLI

npx @reneturcios/codescout rank --input args.json
npx @reneturcios/codescout --version

args.json には、引数オブジェクト全体が含まれます。

{
  "hits": [
    {
      "path": "src/search/rank.ts",
      "matches": 14,
      "last_modified_days": 2,
      "owner": "alice"
    },
    {
      "path": "src/legacy/old-index.ts",
      "matches": 1,
      "last_modified_days": 240
    },
    {
      "path": "src/search/tokenize.ts",
      "matches": 9,
      "last_modified_days": 30,
      "owner": "bob"
    }
  ],
  "limit": 2
}

ランキング結果は JSON として出力されます。

{
  "results": [
    {
      "path": "src/search/rank.ts",
      "matches": 14,
      "last_modified_days": 2,
      "owner": "alice",
      "score": 1398,
      "rank": 1
    },
    {
      "path": "src/search/tokenize.ts",
      "matches": 9,
      "last_modified_days": 30,
      "owner": "bob",
      "score": 870,
      "rank": 2
    }
  ],
  "counts": {
    "hits": 3,
    "returned": 2
  }
}

3件目の検索結果のスコアは 1 * 100 - 240 = -140 となるため、limit が2の場合、この結果は完全に除外されます。

終了コード：成功時は 0、実行時エラー時（入力ファイルが読み取れない、または無効な場合や、入力が無効な場合を含む）は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/codescout mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "codescout": {
      "command": "npx",
      "args": ["-y", "@reneturcios/codescout", "mcp"]
    }
  }
}

ツール

• rank_search_results — 呼び出し元が指定したコードベース検索結果を、固定された関連性と新しさのスコアでランク付けし、ファイル所有者の情報も付加します。

  • hits（配列、必須、1件以上）— 呼び出し元が指定した順序の、ランク付けする検索結果。各項目：
    • path（文字列、必須、空でない値）— 検索結果が含まれるファイル
    • matches（整数、必須、1以上）— ファイル内の一致数
    • last_modified_days（整数、必須、0以上）— ファイルが最後に変更されてからの経過日数
    • owner（文字列、任意）— ファイルの所有者。指定なし、空、または空白文字のみの場合は所有者なしとみなされます
  • limit（整数、任意、1以上、既定値は10）— 返す結果の最大数

  {results, counts} を返します。results には、ランキング順に、返された各検索結果について1つの {path, matches, last_modified_days, owner, score, rank} が含まれます（所有者がいない場合、owner は null です。score は matches * 100 - last_modified_days です。rank は返されたリスト内の位置に基づく1始まりの値です）。counts は {hits, returned} です。

Docker

docker run -i ghcr.io/cloudcorprecords/codescout
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/codescout rank --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios