Big Indexer

Name: Big Indexer
Author: ahmedxuhri

ローカル

github.com/ahmedxuhri開発ツール410 週間前に更新

リポジトリ

Big Indexer について

Big Indexerは、大規模コードベースの構造を調べる静的アーキテクチャ分析ツールです。コードを振る舞いの役割でまとめ、リポジトリ内のパターンに基づく境界情報とAI向けコンテキストを提供します。

主な機能

01振る舞いに基づくコード分類
02結合と境界のシグナル検出
03機械可読なグラフ出力
04類似する振る舞いの検索
05複数言語の分析

活用シーン

01リファクタリング前の境界特定
02サブシステム間の危険な結合の把握
03自動化向けアーキテクチャデータの生成
04リポジトリのパターンに基づくAI変更の支援

MCP 対応

MCPサーバーとして動作し、task_fingerprint、behavioral_twins、twin_contextなどのツールを提供します。これらのツールは、振る舞いのコンテキスト、類似コード候補、境界に関する提案をMCPクライアントに返します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "ahmedxuhri-bigindexer": {
      "command": "uvx",
      "args": [
        "bigindexer"
      ]
    }
  }
}

起動コマンドuvx bigindexer

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

pypibigindexer0.1.2stdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

BGI - Big Indexer

BGI は、大規模なコードベース向けの静的アーキテクチャ分析ツールです。コード単位を振る舞い上の役割ごとにグループ化し、明確なアーキテクチャ上の境界を出力します。プロジェクトのドメイン：bigindexer.com

MCP Registry 経由で利用する

Big Indexer は、io.github.ahmedxuhri/bigindexer として MCP Registry に公開されています。

pip install bigindexer==0.1.3
bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json

検証：https://bigindexer.com/validation

解決する課題

ほとんどのアーキテクチャグラフは、大規模になると次の 2 つの問題を抱えます。

ノイズの多いエッジが多すぎる
無関係なコンポーネントがひとまとめになる巨大なクラスター

BGI はこの両方を抑え、大規模なリポジトリでも出力を使いやすく保つように設計されています。

できること

「リファクタリングの前に、この境界をどこに設けるべきか？」
BGI は、振る舞い上の役割（COV トークン + DRS クラスタリング）ごとに単位をグループ化し、コンポーネントの境界候補を見つけやすくします。
「どのサブシステム間の結合にリスクがあるか？」
BGI は、クラスター間の結合度の高い接点やヒューズ境界のシグナルを明らかにし、統合リスクを見つけやすくします。
「アーキテクチャデータを自動化にどう組み込むか？」
BGI は機械可読な成果物（bgi-graph.json、fuse-graph.json）に加え、任意で人が読むためのコンテキスト（bigindexer.md）を出力します。
「AI による変更をよりランダムでなくするには？」
MCP ツール（task_fingerprint、behavioral_twins、twin_context）は、プロンプトの根拠としてリポジトリ内の振る舞いパターンを活用します。
「実例として PR 上で自動実行できますか？」
はい。専用のアクションリポジトリ ahmedxuhri/bigindexer-pr-risk-bot を使うと、影響範囲、接点、リスクのヒントを PR に自動でコメントできます。

30 秒デモ

同梱のフィクスチャリポジトリで BGI を実行します。

git clone https://github.com/ahmedxuhri/bigindexer
cd bigindexer
pip install -e .
bgi scan tests/fixtures --lang python --out /tmp/bgi-example.json
head -50 /tmp/bgi-example.json

このリポジトリでの実行結果：

単位：12
エッジ：14
クラスター：2
サンプル内の最大クラスター：6 単位

生成されたエッジの例：

{
  "source": "auth_module.py::AuthService::__init__",
  "target": "auth_module.py::AuthService::__del__",
  "key": "COV.INIT",
  "lock": "COV.TEARDOWN",
  "type": "HARD"
}

重要な点：生の構文参照だけでなく、アーキテクチャの判断に役立つ、振る舞い上の関係とクラスター構造を得られます。

平易な用語集

BGI 用語	平易な意味
COV token	単位の振る舞いを表すラベル（例：`FETCH`、`PERSIST`、`AUTHENTICATE`）
Key-Lock edge	相補的な役割を持つ 2 つの単位間の振る舞い上のつながり
DRS cluster	振る舞い上の役割ごとに単位レベルでグループ化したもの。実際には主にファイル内でのグループ化です。ファイルレベルのアーキテクチャコンポーネントは、BGI エッジグラフまたはヒューズグラフの境界シグナルでより適切に表現されます。詳しくは外部ベンチマークをご覧ください
Fuse edge / fuse event	クラスターの拡大が上限に達したため拒否された統合。境界シグナルとして扱われます
Spectral masks	マッチング可能な範囲（グローバル、ディレクトリ、ファイル）を制限するスコープルール

アーキテクチャの概要

Source files
   ->
Gate 1: fingerprint unit behavior (COV tokens)
   ->
Gate 2: create behavioral edges with scoped matching
   ->
Gate 3: cluster with hard size cap + boundary emission
   ->
Artifacts: bgi-graph.json, fuse-graph.json, bigindexer.md, optional routes/graphml/html

中核となるアプローチ：

TOKEN-CENSUS - リポジトリごとにトークン頻度を分類します。
SPECTRAL-MASKS - トークン頻度に基づいて照合範囲を制限します。
FUSE-MAP - クラスターの拡大に上限を設け、拒否されたマージを記録します。
MASK-4-GATE-3 - インポートの近接性をクラスタリングのシグナルとして使用します。
WATER-CLOCK + .scm - Gate 1 でクエリを単一パスで抽出します。

BGI が一般的な代替手段と異なる点

機能	LSP / SCIP インデックス	コールグラフ + 汎用コミュニティ検出	BGI
高速なシンボル検索	強い	中程度	利用可能（Phase 6 インデックス）
動作トークンモデル	なし	通常なし	あり
厳密に上限を設けたクラスタリング	なし	通常なし	あり（ユニットレベル）
第一級の境界アーティファクト	なし	通常なし	あり（`fuse-graph.json`）
スコープ制約付きエッジ生成	限定的	まれ	あり（スペクトルマスク）

外部との直接比較ベンチマーク（BGI のエッジに対する Louvain と、生のインポートに対する Louvain を実行し、パッケージ構成を基準に評価）：BGI のエッジは Python で優れており（django F1 0.38 対 0.29、MoJoFM 0.45 対 0.34）、Go では現在、tier-2 スキャナーのファイル間エッジ密度が低いため、同等か劣ります。結果と方法論の詳細はdocs/VALIDATION_EVIDENCE.mdをご覧ください。

エビデンス（現時点で検証可能）

大規模リポジトリでの規模に関するエビデンス

kubernetes の比較可能なサンプル（go 比較可能モード、162,917 ユニット）：

Gate 1：141.964s
Gate 2：67.261s（過去の比較可能なベースライン：138.869s）
Gate 3：9.359s
合計：218.584s
最大クラスター：1.113%
Fuse イベント：0

アーティファクト：output/validation/kubernetes-optionb-controlled-median-v21.json

品質ガードに関するエビデンス（生の速度以外）

Gate 2 のスコープ安全性テストでは、無効なスコープ間マージをブロックします（tests/test_gate2.py を参照）。
Gate 3 のテストでは、インポートのエビデンスがない状態で、レガシー名前空間が過剰にマージされないことを検証します（tests/test_gate3.py を参照）。
現在の全テストスイートの状態：python3 -m pytest tests/ -x -q（プロジェクトのベースライン目標は引き続き合格です）。

エビデンスの概要

現在公開されている検証セット：5 つのリポジトリと 3 つのモデルにわたる、評価済みの 100 回の実行。
BGI-TWIN コンテキスト（task → COV → top-3 twins + seam + rubric）に対する、出荷後のベンチマーク全 20 回の更新が完了しました：実用性 4.75/5（p04 スライス：4.8/5）、境界 1.0、ハルシネーション 0。
独立モデルによる再現検証は、azure/gpt-4o（20 回）と gemini/auto（20 回）で完了しました。GPT-4o の実用性は 4.85/5、Gemini の実用性は 4.25/5 で、どちらもハルシネーションはゼロです。Gemini の境界スコア 0.95 は、実際に発生した django/p02 の見落とし 1 件を反映しています。
未実施：外部コーパスを使ったラベル付き適合率／再現率ベンチマークと、同じラベル付きデータセットでの外部ツールとの定量的な直接比較ベンチマーク。

言語サポートの段階（明示）

BGIでは、すべての言語を同等には扱わず、サポートを段階化しています。

クエリベース（.scm）：python、typescript、tsx、javascript、go、rust、java、csharp、php、ruby、kotlin、scala
Tree-sitter スキャナー＋ルールパス：c、lua、elixir
拡張子ごとの汎用正規表現フォールバック：swift、r、dart、bash、nim、zig、haskell、ocaml、fsharp、clojure、erlang、matlab、vb、crystal、cobol、groovy

これを信頼性の目安としてご利用ください。クエリベースと専用スキャナーの段階は、汎用フォールバックより信頼性が高くなっています。

ファイル間エッジ密度に関する注意点： 上記の言語段階はパーサーの品質を示しています。これとは別に、ファイル間の動作エッジ密度という軸があります。これは、異なるファイルの単位をリンクするキーとロックのペアをスキャナーがどれだけ生成するかを示します。Tier-1（.scm ベース）の言語は、高密度のファイル間エッジを生成します。現在、Tier-2 のスキャナーベース言語では、トークンの大半が構造トークン（INTAKE／OUTPUT／CONDITIONAL／LOOP）であり、gate-2 では O(N²) のノイズを防ぐため、これらを意図的に同一ファイル内に限定していることから、ファイル間エッジはより疎になります。ユーザー向けの MCP 製品（境界検出、双子検索、AI アシスタントのコンテキスト）は、検証結果が示すとおり、Tier-2 の言語でも引き続き機能します。ただし、インポートグラフを基準とするクラスタ復元ベンチマークには、この密度の差が反映されます。具体的な数値はdocs/VALIDATION_EVIDENCE.mdをご覧ください。

制限事項と対象外

BGI は静的解析を行うもので、ランタイムトレースは取り込みません。
ファイル間の意味的解決はヒューリスティックであり、言語によって異なります。
クラスターサイズの健全性は測定していますが、外部データを用いた適合率／再現率はまだ公開していません。
共有ホストでのベンチマークにはばらつきが生じるため、判断には条件を統制した中央値を使用してください。

インストール

pip install -e .

クイックスタートコマンド

# scan
bgi scan /path/to/repo --lang auto --out bgi-graph.json

# optional outputs
bgi scan /path/to/repo --lang auto \
  --fuse-graph fuse-graph.json \
  --routes routes.json \
  --graphml graph.graphml \
  --html

# incremental
bgi scan /path/to/repo --lang auto --incremental --cache .bgi-cache.json

# diff
bgi diff /path/before /path/after --lang auto --out diff.json

# run MCP server over generated artifacts
bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json

MCP の使用パターン例（クライアントのプロンプトから）：

Use MCP tool twin_context for:
"Add endpoint that validates input and persists data."
Return top twin candidate, seam suggestion, and rubric checklist.

テレメトリー

BGI には、オプトインで、デフォルトでは無効の匿名テレメトリーが含まれています。有効にするには：

export BGI_TELEMETRY=1
bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json

有効時に収集される情報：BGI のバージョン、OS、リポジトリサイズの区分、リポジトリの git リモートの 12 文字のハッシュ（リポジトリを特定することなく「同じリポジトリが二度確認された」ことを重複排除するため）。収集しない情報：ファイルパス、ソースコード、リポジトリ名、ユーザー ID、IP アドレス。完全なスキーマと無効化の手順はdocs/TELEMETRY.mdをご覧ください。

ドキュメント一覧

MEMORANDUM.md - 設計上の契約と不変条件
docs/LANGUAGE_SUPPORT.md - 言語の実装詳細
docs/CONTRIBUTING_LANGUAGES.md - 言語への貢献ガイド
docs/INDEX_SCHEMA.md - インタラクティブインデックスのスキーマ
docs/QUERY_PLANNER.md - クエリプランナーのスコアリング
docs/MCP_SETUP.md - MCP サーバーのセットアップと使用方法
docs/MCP_WITH_CONTINUE.md - Continue と BGI の 5 分間ウォークスルー
docs/TELEMETRY.md - オプトインテレメトリー：収集する情報と無効化の方法
https://bigindexer.com/validation - 公開されている検証結果
docs/MCP_QUICKSTART_DEMO.md - 5 分間のデモウォークスルー
docs/MCP_EXAMPLE_TRANSCRIPTS.md - 実際の MCP ツール呼び出し例
docs/MCP_REAL_TRANSCRIPT.md - FastAPI 解析の未編集トランスクリプト
scripts/mcp-demo.sh - 複数の CLI とリポジトリを対象とする自動デモスクリプト

ライセンスと著作権

ライセンス：Apache License 2.0（LICENSE）
貢献者の規約：プルリクエストでは Developer Certificate of Origin（DCO）の遵守が必須です

法務情報

Big Indexer は、イングランドおよびウェールズで登記された SUDO SOFTWARES LTD（会社番号 16976948）の製品です。連絡先：[email protected] · https://bigindexer.com

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。