Booster MCP

ドキュメント: English | Русский | 简体中文

Boosterは、AIコーディングエージェント向けのローカルModel Context Protocol (MCP) サーバー兼認知ランタイムです。リポジトリの境界のある検索可能なワールドモデルを構築し、エージェントがコードを変更する前にアーキテクチャ、履歴、診断、プロジェクトルール、検証要件を調査できるようにします。

ほとんどのエージェントはすでに手を持っています。パッチを素早く書けるのです。Boosterは、通常欠けている知覚レイヤーを提供します。

Boosterが存在する理由

大規模リポジトリがエージェントを圧倒するのは、ファイル数が多いからではありません。重要な関係性がソースコード、テスト、git履歴、診断、プロジェクトの規約に散在しているからです。

Boosterがなければ、エージェントはしばしば次のループを繰り返します:

request -> grep/search -> read a few files -> write a patch -> stop

そのループでは、次のような情報を見落とす可能性があります:

• 対象シンボルの呼び出し元と呼び出し先;

• インターフェース変更の影響を受けるファイルとテスト;

• 意外なコードの背後にある歴史的な理由;

• プロジェクト固有のルールと保存されたアーキテクチャ上の決定;

• 既存のコンパイラ、型、lint、セキュリティ診断;

• パッチ後に実行すべき検証コマンド。

Boosterはそれらのシグナルをループに追加します:

request
  -> project memory
  -> repository map and hybrid search
  -> AST impact graph
  -> git history and blame
  -> diagnostics and security checks
  -> validation plan
  -> focused patch
  -> validation and repair

Related MCP server: SRC (Structured Repo Context)

機能

アーキテクチャ

Boosterには2つの補完的なプレーンがあります:

• MCPコントロールプレーン: リポジトリインデックス作成、意味的検索、グラフ、メモリ、 診断、スキル、検証ツール。

• Booster Homeデータプレーン: コンテキストをコンパイルし、回復可能なアーティファクトを保存し、 リクエストをローカルまたはリモートのモデルバックエンドに転送する、オプションのローカルOpenAI互換ゲートウェイ。

既存のリポジトリインデックスとCognitive Runtimeは再利用されます。Homeは2つ目のリポジトリインデックス、ゲートウェイ、ベクトルデータベースを作成しません。

MCPコントロールプレーン

コアサーバーが提供するもの:

• hybrid_search による正規化されたFAISSコサイン検索、BM25語彙検索、相互ランク融合;

• 再現可能なスキャンプロファイルによる境界のあるリポジトリスキャン;

• 生成された .agents/booster/ アーティファクト、例: repo_map_architecture.md、repo_map_symbols.md、index_health.json、 repo_map.md、code_city.html、scan_config.json、scan_report.json;

• repo://map、repo://stack、repo://conventions、repo://artifacts のコンテキストリソース;

• シンボル、インポート・コールグラフ、フリップチャート、Code City、リポジトリ診断;

• 影響分析、gitインテリジェンス、構造化プロジェクトメモリ、セキュリティチェック、検証ループ;

• ~/.agents/skills に同期される12のバンドル済みワークフロースキル;

• MCPクライアント、スキャン設定、診断、ランチャー管理のためのクロスプラットフォーム制御サーフェス booster control。

Booster Homeランタイム

Homeはオプションのローカルデータプレーンです。MCPコントロールプレーンをそのまま維持し、決定的なコンテキストコンパイル、境界のあるローカルワーカー、セッションスコープの生アーティファクト、既存のBoosterインデックスとCognitive Runtimeへのターゲット統合を備えたOpenAI互換ゲートウェイを追加します。

ループバックで起動します:

booster home \
  --base-url http://127.0.0.1:1234/v1 \
  --model nvidia/nemotron-3-nano-4b \
  --api-key lm-studio \
  --project .

Homeが公開するもの:

• /v1/models;

• /v1/chat/completions;

• /v1/responses;

• /health;

• /booster/status。

アップストリームのモデルIDは /v1/models から検出されます。ローカルのOpenAI互換サーバーが報告するIDに置き換えてください。Nemotronデプロイメントでは、出力予算が推論に消費された場合、message.content の代わりにプロバイダー固有の reasoning_content が返されることがあります。Homeはそのフィールドを保持し、不完全な推論応答を黙って成功した回答に変換することはありません。

ストリーミング応答はチャンクとして転送されます。ブロックが退避される前に、その生のコンテンツは不変のアーティファクトとして保存され、コンテンツハッシュによって検証されます。永続化に失敗した場合、コンテキストを黙って失う代わりに、リクエストはフェイルクローズします。

リポジトリのインデックス作成はジョブベースです。add_repo(wait=true) は互換性のために引き続き受け付けられますが、MCPリクエストをブロックしなくなりました。index_status、cancel_index、境界のある wait_until_ready を使用してジョブを監視してください。各ステータスには job_id、フェーズ、処理済み/合計、経過時間、ETA、最後の進捗、世代ID、古い状態、最後の準備完了スナップショットが含まれます。読み取り専用のリポジトリメソッドは、新しい世代が構築されている間も、その準備完了スナップショットを返し続けます。

生成されたアーティファクトは目的別に分割されます:

• repo_map_architecture.md は、トップレベルのモジュール多様性、エントリーポイント/設定/コントラクトのカバレッジ、カバレッジサマリーを備えた境界のあるマクロマップ;

• repo_map_symbols.md は、ファイルごとの上限を持つ詳細なシンボルマップ;

• index_health.json は、世代、古いパス、選択/スキップされたファイル、マップの完全性を記録;

• repo_map.md は、アーキテクチャマップの互換性コピーとして残ります。

設定の優先順位は:

defaults
  -> ~/.booster/home.toml
  -> <project>/.agents/booster/home.toml
  -> explicit --config
  -> CLI flags

APIキーはアップストリームのリクエストヘッダーでのみ使用され、ステータス、テレメトリ、タイムライン、ログ、例外テキストからは編集されます。これらのコマンドは、2つ目のサーバーやリポジトリインデックスを起動せずにHomeを検査します:

booster home status
booster home doctor --json
booster home inspect-context --input request.json --json
booster home sessions delete <session-id>

ループバックがデフォルトであり、ゲートウェイトークンは不要です。ループバック以外のバインドは、home.auth_token がTOML、BOOSTER_HOME_AUTH_TOKEN、または --auth-token で設定されていない限り拒否されます。リモートリクエストは Authorization: Bearer <token> を送信する必要があります。トークンはステータスやログによって返されることはありません。

実証: Booster + Nemotron 4B

Boosterを理解する最良の方法は、難しい問題でループを見ることです。同じ4BクラスのNemotronモデルを使用した手動LM Studio実行では、もっともらしい最初の解決策が隠れたケースで失敗しました。Boosterコンテキスト、明示的な制約、修復・送信ループの後、同じワークフローが受理された提出物を生成しました:

このパターンは追加の難しい動的プログラミングタスクでも繰り返されました:

• 689. Maximum Sum of 3 Non-Overlapping Subarrays: タイブレーク失敗 -> 43/43 受理;

• 123. Best Time to Buy and Sell Stock III: 214/214 受理;

• 記録された受理実行は 36 ms と 170 ms のローカルランタイムを示しています。

これはエビデンスのケーススタディであり、統制されたベンチマークではありません。顧客向けの価値を示しています: Boosterは、単に見た目が正しいコードで止まるのではなく、制約、プロジェクトコンテキスト、診断、検証を1つのループに保ちます。

ベースライン、修復手順、スクリーンショット、再現チェックリストについては、完全なLeetCodeケーススタディを参照してください。

コンテキスト圧縮

Homeは圧縮を、不可逆的な忘却ではなくコンテキストコンパイルとして扱います:

1. ロールとコンテンツタイプによってメッセージを分類します。

2. 重複行、進捗出力、ANSIエスケープシーケンスなどの決定的なノイズを正規化します。

3. 退避される前に元のブロックを永続化します。

4. 関連性をスコアリングし、優先度によって利用可能な入力予算を割り当てます。

5. オプションで境界のある意味的ワーカーとターゲット指向のワールドモデル検索を実行します。

6. 保護されたコンテキストとツール呼び出しの整合性を維持しながら、選択されたメッセージをパックします。

コンパイラーは original_tokens、compiled_tokens、removed_tokens、compression_ratio、操作、警告、アーティファクト参照を報告します。主な不変条件は次のとおりです:

• システムとアクティブなユーザーコンテキストは保護されます;

• 保護されたコンテキストが収まらない場合、既知のハードリミットはフェイルクローズします;

• 生データは退避前に永続化されます;

• アーティファクトのコンテンツは書き込みと読み取り後にハッシュ検証されます;

• 圧縮は無効化できますが、policy=off でも既知のハード入力予算を超えるリクエストは拒否されます;

• reasoning_content を含むプロバイダー固有のフィールドは保持されます。

同梱のストレステストベンチマークを実行します:

uv run python benchmarks/home_context_benchmark.py

ベンチマークは、生、決定的、取得、最終トークン数、圧縮率、コンパイラーのレイテンシ、正確なアーティファクト回復、ターゲット指向の拡張結果を出力します。成功した実行には以下が含まれている必要があります:

exact_artifact_recovery=True

リサーチコプロセッサー

Homeには、ローカル実験のための境界のあるリサーチコプロセッサーも含まれています。research_state.json、memory_bank.md または memory-bank/*.md、メトリクス、レポートファイルからエビデンスを読み取ります。不透明なモデル生成サマリーを真実として提示する代わりに、構造化JSONを返します。

バイナリチェックポイント本体は読み取られず、インデックス化されず、モデルに送信されることもありません。ファイル名、サイズ、ステップ、親、メトリクス、実験、ステータス、keepフラグ、ブランチなどのメタデータのみが利用可能です。サイドカーメタデータは、.pt.json、.json、_metadata.json、.metadata.json の規約を使用してチェックポイントの隣で検索されます。

コンテキストパックは次のように構成されています：

L0  current task
L1  current experiment and active hypotheses
L2  recent evidence and relevant code
L3  project invariants and runtime contract
L4  archive

通常の推論では L0、L1、および L2 と L3 の関連部分を使用します。重複ログ、古い失敗バージョン、バイナリアーティファクト、無関係な履歴はポリシーにより除外されます。リポジトリコンテンツ、メトリクス、レポート、メモリは信頼できないデータであり、設定として実行されません。

許可されるワーカーロールは次のとおりです：

log_analyst
code_search
benchmark_reader
artifact_indexer
summarizer

研究状態とレジストリは <project>/research_state.json にアトミックに書き込まれます。ホームセッションアーティファクトは .agents/booster/runtime/sessions/ に別途保持されます。研究状態はチャットタイムラインやレガシーの .agents/booster/memory.json と混在しません。

リポジトリレイアウト

.
├── booster_home/              # Optional OpenAI-compatible data plane
├── assets/                    # README and Code City visual assets
├── algocheck/                 # Customer-facing LeetCode validation evidence
├── benchmarks/                # Reproducible context and runtime benchmarks
├── docs/                      # Architecture and maintainer documentation
├── skills/                    # Bundled agent workflow skills
├── tests/                     # Pytest suite, including Home regressions
├── server.py                 # MCP server entrypoint
├── cli.py                    # `booster` CLI entrypoint
├── cognitive_runtime.py      # Impact, memory, diagnostics, and validation tools
├── indexer.py                # Repository indexing and graph construction
├── visualizer.py             # Code City generation
├── AGENTS.md                 # Agent-first bootstrap and project instructions
├── RECOMENDET_PROMPT.md      # Repository-wide engineering prompt for agents
├── CONTRIBUTING.md           # Development and contribution workflow
├── CHANGELOG.md              # Release history
├── pyproject.toml            # Package metadata and tool configuration
├── MANIFEST.in               # Source distribution contents
└── uv.lock                   # Reproducible dependency lockfile

レガシーMCPコントロールプレーンモジュールは意図的にリポジトリルートに残されています。パッケージエントリポイント（server:main および cli:main）と既存の統合は、これらの安定したモジュール名に依存しています。それらを src/ に移動することは、別の互換性マイグレーションとして扱うべきであり、日常の機能作業に混ぜるべきではありません。

推奨エージェントプロンプト

このリポジトリには専用のエンジニアリングシステムプロンプトが含まれています： RECOMENDET_PROMPT.md。

エージェントがパッチジェネレータではなくエンジニアとして作業する必要がある場合、非自明なコーディングセッションの開始時にそれを読み込んでください。このプロンプトは、プロジェクトコンテキストルーティングルール、PERCEIVE -> MODEL -> PLAN -> ACT -> VERIFY -> LEARN ワークフロー、Boosterファーストのコンテキスト取得、根本原因分析、セキュリティチェック、検証要件、メモリ規律を定義します。

これはコーディングエージェント向けのリポジトリガイダンスであり、アプリケーションのランタイム設定ではありません。このプロンプトは、エージェントツールが最初の編集前に発見できるように、意図的にルートに保持されています。

インストール

要件

• Python 3.11、3.12、または3.13。Python 3.12が推奨されます。

• Git。

• 埋め込みモデルをダウンロードするための初回実行時のインターネットアクセス。

Windows

Invoke-WebRequest https://raw.githubusercontent.com/NeuroGhostDev/Booster-mcp/main/install.ps1 -OutFile install.ps1
.\install.ps1

macOSおよびLinux

curl -fsSL https://raw.githubusercontent.com/NeuroGhostDev/Booster-mcp/main/install.sh | bash

各インストーラは、ユーザーローカルのbinディレクトリに booster ランチャーを作成します：

• Windows: %USERPROFILE%\.local\bin\booster.cmd；

• macOSおよびLinux: ~/.local/bin/booster。

インストーラはそのディレクトリを PATH に追加します。現在のシェルがランチャーをまだ認識しない場合は、新しいターミナルを開いてください。

開発インストール

git clone https://github.com/NeuroGhostDev/Booster-mcp.git
cd Booster-mcp
uv sync --locked --extra dev

uv がない場合は、Python 3.12仮想環境を使用します：

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

Windowsでは、\.venv\Scripts\Activate.ps1 でアクティブ化し、ランチャーがインストールされるまで \.venv\Scripts\booster.exe を使用します。

エージェントブートストラップ：GitHubリンクを貼り付けてワークフローを取得

このリポジトリがAIコーディングエージェントでGitHub URLから開かれた場合、エージェントは AGENTS.md をプロジェクトブートストラップ契約として扱う必要があります。コードを編集する前に、ローカル依存関係をインストールし、Boosterスキルを同期し、エンジニアリングガイダンスを読み込み、境界付きリポジトリアーティファクトを作成し、MCPサーバーを接続する必要があります。

リポジトリルートからこれを一度実行します：

# 1. Install the project and its development dependencies.
uv sync --locked --extra dev

# 2. Install or update the bundled Booster skills for the current agent.
uv run python -c "from skill_installer import install_bundled_skills; print(install_bundled_skills())"

# 3. Load the repository into the bounded Booster world model.
uv run booster expand --profile balanced .

# 4. Connect the current repository to VS Code MCP.
uv run booster control connect \
  --client vscode \
  --scope workspace \
  --project . \
  --with-repository \
  --force

# 5. Verify the environment and generated artifacts.
uv run booster control doctor --project .
uv run booster control status --client vscode --scope workspace --project .

Claude Desktopの場合は、代わりにユーザーレベルの接続を使用します：

uv run booster control connect \
  --client claude \
  --scope user \
  --project . \
  --with-repository \
  --force

uv が利用できない場合は、python -m pip install -e ".[dev]" を使用し、uv run booster を python -m cli またはインストールされた booster ランチャーに置き換えます。

エージェントはその後、すべての非自明なタスクを次のもので開始する必要があります：

Read AGENTS.md and RECOMENDET_PROMPT.md.
Call inject_context(include_map=true, include_stack=true, include_conventions=true).
Use preflight_analysis and impact_analysis before editing code.
Use run_validation_checks after the patch.
Call booster.task_complete(task_id="<task-id>") before the final response.

これは意図的にプロジェクトレベルでポータブルです。リポジトリは、ホストアプリケーションの隠れたシステムプロンプトや無関係なグローバルクライアント設定を黙って書き換えてはなりません。AGENTS.md はエージェントホストが発見できる命令ファイルです。booster control connect は選択されたMCPクライアントエントリのみを変更し、他のサーバーを保持します。

VS Codeへの接続

管理したいリポジトリからコントロールメニューを実行します：

booster control

1つのリポジトリにはワークスペース接続を使用します：

cd path/to/project
booster control connect --client vscode --scope workspace --project .
booster expand --profile balanced

BoosterがすべてのVS Codeワークスペースに表示される必要がある場合は、ユーザー接続を使用します：

booster control connect --client vscode --scope user --project .

ユーザーレベルのサーバーが起動した後、現在編集中のリポジトリに対してエージェントに add_repo を呼び出すよう依頼します。インデックス作成はデフォルトでバックグラウンドで実行されます。index_status はフェーズと進捗を報告します。add_repo(wait=true) は互換性のために引き続き受け入れられますが、これも非ブロッキングです。必要に応じて cancel_index または境界付きの wait_until_ready を使用します。--with-repository を使用して、ユーザーレベルのサーバーを1つのリポジトリにバインドします。

VS CodeはワークスペースとユーザーのMCP設定を別々に保持します。サーバーを変更した後、MCP: List Servers を実行し、Boosterを選択して起動または再起動し、信頼プロンプトを受け入れます。それでも見つからない場合は、Developer: Reload Window を実行し、MCP: List Servers -> Booster -> Show Output を検査します。

Boosterコントロール

booster control は、対話型の接続管理、スキャンプロファイル、アーティファクト更新、診断、サーバー削除、ランチャー更新を提供します。同じ操作は非対話型でも利用可能です：

# Show the active runtime, client entry, scan policy, and artifacts.
booster control status --client vscode --scope workspace --project .

# Add or remove a client entry.
booster control connect --client vscode --scope workspace --project .
booster control disconnect --client vscode --scope workspace --project .

# Connect another desktop client in the user profile.
booster control connect --client claude --scope user --project .

# Inspect and persist the bounded scan policy.
booster control scan --project .
booster control scan --project . --profile deep --max-files 2000

# Verify Python, FastMCP, FAISS, BM25, and embedding dependencies.
booster control doctor --project .

境界付きリポジトリスキャン

大きなリポジトリをアタッチする前に booster expand を実行します。これによりスキャンポリシーが保存され、ライブMCP接続を必要とせずに初期マップが生成されます。

booster expand --profile balanced

スキャナは従来のソースルートを優先し、生成されたディレクトリと依存関係ディレクトリをデフォルトで無視し、すべての制限決定を .agents/booster/scan_report.json に記録します。ディレクトリが現在のタスクに無関係な場合は、.boosterignore にローカル除外を追加します。

認知ランタイムワークフロー

エージェントがコードを変更しようとしているときにこのフローを使用します：

1. project_memory_recall でプロジェクトルールを呼び出します。

2. hybrid_search、semantic_search、または find_symbol でターゲットを見つけます。

3. impact_analysis で影響範囲を推定します。

4. コードが驚くように見える場合は、git_intelligence で履歴を確認します。

5. スコープ内のファイルについて collect_diagnostics で診断を収集します。 セキュリティに敏感な変更の場合は、別のアドバイザリ security_audit を実行します。

6. プロジェクトの既存パターンを使用して狭くパッチを適用します。

7. run_validation_checks で検証し、合格するか仮説が棄却されるまで同じスライスを修正します。

典型的な事前チェック：

project_memory_recall(query="refactor billing invoice flow", repo="<repo>")
impact_analysis(target="InvoiceService", repo="<repo>", max_depth=3)
git_intelligence(symbol="InvoiceService", repo="<repo>", limit=8)
collect_diagnostics(paths=["src/billing/invoice.py"], repo="<repo>")

典型的なパッチ後検証：

run_validation_checks(
  paths=["src/billing/invoice.py"],
  commands=["pytest tests/billing -q"],
  repo="<repo>"
)

診断はフェイルクローズ

Boosterは診断をエンジニアリング証拠として扱います。タイムアウト、クラッシュ、または解析不能な出力を返す診断ツールは、error の発見として報告されます。これにより、エージェントが壊れた検証実行をクリーンなコードベースと誤認することを防ぎます。

例

リファクタリング前

impact_analysis(target="AuthService", repo="<repo>", max_depth=4)
git_intelligence(symbol="AuthService", repo="<repo>")
collect_diagnostics(paths=["src/auth/service.py"], repo="<repo>")

エージェントは、サービスを呼び出すもの、サービスが呼び出すもの、影響を受けるファイル、関連するテスト、既存の赤い診断がすでに存在するかどうかを回答できます。

バグハンティング中

analyze_error("<stacktrace>")
git_intelligence(path="src/payments/locks.py", symbol="payment_lock")
flipchart_call_graph(symbol="payment_lock", max_depth=4)

エージェントは、スタックトレース、コールグラフ、疑わしい行の背後にある履歴的理由を組み合わせることができます。

長期的なプロジェクト知識のために

remember_project_fact(
  category="architecture",
  fact="Frontend talks to backend only through the BFF layer",
  confidence=0.95,
  source="repo_map+impact_analysis"
)

将来のセッションは、APIまたはフロントエンドを編集する前にその事実を呼び出すことができます。

バンドルされたワークフロースキル

• booster-architecture-map

• booster-bug-hunt

• booster-context-inject

• booster-cognitive-runtime

• booster-deep-dive

• booster-feature-add

• booster-flipchart

• booster-mcp-workflow

• booster-onboard

• booster-project-memory

• booster-refactor

• booster-review

主要なMCPツール

リポジトリバインディングは共有ユーザーレジストリの ~/.booster/repositories/ に永続化されるため、独立して起動された MCP プロセスでも同じアクティブなプロジェクトを参照できます。booster.task_complete は、タスクのリポジトリに対して最終的な制限付き再インデックスをキューに登録します。完了した各インデックスは、不変の .agents/booster/snapshots/<commit>-<state>-<digest>/ ディレクトリに .agents/booster/repo_map.md、code_city.html、scan_config.json、scan_report.json を保持します。以前のスナップショットは決して削除されません。.agents/booster/latest.json は最新のものを指します。各スナップショットは、repo_map_architecture.md、repo_map_symbols.md、index_health.json も保持します。アーキテクチャマップは、トップレベルモジュールの多様性とエントリーポイント/設定/コントラクトのカバレッジのためにスペースを確保します。シンボルマップはファイルごとの上限を適用するため、大きなファイルがコンテキスト予算全体を消費することはありません。

トラブルシューティング

VS Code に Booster が表示されない

両方の設定スコープを確認してください:

booster control status --client vscode --scope workspace --project .
booster control status --client vscode --scope user --project .

そのワークスペースにはワークスペースエントリのみが表示されます。ユーザーエントリはすべてのワークスペースで表示されます。MCP: List Servers を使用して、サーバーの起動、信頼、再起動、または検査を行います。MCP: Open User Configuration を使用して、VS Code が読み取っている正確なグローバルファイルを開きます。

No module named rank_bm25

クライアントが Booster の環境ではなく、別のシステム Python を起動しています。環境を修復し、Booster Control から再接続してください:

uv sync --locked --extra dev
booster control doctor --project .
booster control connect --client vscode --scope user --project . --force

スキャン範囲が狭すぎる

レポートを確認し、より広いプロファイルまたは明示的な制限を選択してください:

booster control scan --project . --profile deep
booster expand --profile deep

リリース検証

uv lock --check
uv run python -m pytest tests -q
uv run ruff check .
uv run python -m compileall -q booster_home indexing_jobs.py server.py
uv build

詳細なワークフローについては、COOKBOOK.md を参照してください。公開とクライアント配布については、MARKETPLACE.md を参照してください。メンテナは CONTRIBUTING.md と CHANGELOG.md もお読みください。

ロードマップ

Booster はすでにインメモリの Tree-sitter シンボル、コール、インポートグラフを維持しています。計画されている本番環境向けの改善点は次のとおりです:

• ナレッジグラフを Neo4j または Memgraph に永続化し、セッションをまたいだグラフクエリとより深い依存関係のトラバースを可能にする。

• Pyright、TypeScript、rust-analyzer、gopls、clangd、Java 言語サーバー向けのヘッドレス LSP クライアントを追加する。

• コミットをプルリクエストとイシューにリンクし、git_intelligence が変更された内容だけでなく、なぜコードが変更されたのかも説明できるようにする。

• Docker Compose、ヘルスチェック、サービスログ向けの検証レシピを追加する。

• バンドルされたスキルを、エージェント固有のアーキテクチャ、デバッグ、メモリ、品質パックに拡張する。

ライセンス

MIT