MCP Scout (smarter-faster-better-mcp)

smarter-faster-better-mcp (MCP Scout 🚀)

AST ベースのコードインテリジェンスとセマンティック検索のための、超高速かつ超軽量な Model Context Protocol（MCP） サーバーです。npx 向けにコンパイル済みの Node.js JavaScript として実行され、JavaScript／TypeScript ではデフォルトで oxc-parser を使用し、複数言語に対応したリポジトリでは web-tree-sitter を選択できます。

---

🗺️ クイックナビゲーション

以下のセクションをクリックすると、該当箇所へ直接移動できます。

セクション	説明
⚡ パフォーマンスと速度	MCP Scout が超高速でトークン効率に優れている理由。
📂 対応言語	対応言語とパーサーの選択（oxc 対 tree-sitter）に関する詳細ガイド。
🏗️ アーキテクチャと構造	アーキテクチャのパイプライン、ディレクトリ構成、コードベース設計の標準を図で解説します。
📦 要件とインストール	システム要件、グローバル／ローカルインストール、すぐに実行できるコマンド。
⚙️ 設定	ローカルの .env ファイルと CLI フラグを使用した環境変数のカスタマイズ。
🖥️ クライアント連携	Claude Desktop、Cursor、Windsurf、Trae、Claude Code の簡単なセットアップ。
🛠️ 公開される MCP ツール	find_code、trace_symbol、get_file_context などのツールの完全なリファレンス。
🤖 AI エージェント向けの指示	LLM と AI エージェント向けの重要なプロトコル規則とフォールバック手順。
🧪 開発とテスト	コントリビューション、JSON-RPC スモークテスト、MCP Inspector の使用方法。
📄 ライセンス	ライセンスの詳細（MIT）。

---

⚡ パフォーマンスと高速性の理由

従来のコードベース分析ツールでは、LLM がディレクトリを探索し、生のファイルを読み込み、参照を手作業で解決する必要があります。これにより数千トークンが無駄になり、コンテキストのあふれが発生し、処理も非常に遅くなります。

MCP Scout は、よりスマートな方法でパフォーマンスを高めます。

1. デフォルトではネイティブバインディング不要：JavaScript／TypeScript 向けに Rust ベースの oxc-parser を採用しています。node-gyp や C++ コンパイラフラグを必要とせず、数ミリ秒でインストールでき、ファイルを瞬時に解析します。
2. 1 秒未満の System 1 AI トリアージ（TypeSafe Jev）：処理が遅くリソースを大量に消費するローカルチャット LLM を TypeSafe Jev に置き換えます。動的な AI 基準と仮説マトリックスを単一パスのバッチ処理で（500ms 未満に）評価し、ハルシネーションをゼロに抑えます。
3. 決定論的な文字列と AST によるフィルタリング：高速な Jaro-Winkler 編集距離とストップワードフィルタリングを用いて、AI に渡す前にプロジェクト内の数千のシンボルから、最も関連性の高い候補を瞬時に絞り込みます。
4. AST 抽出とコードの折りたたみ：AST 解析によって関数やクラスの本体を正確に抽出します。summaryOnly モードでは本体をスタブに折りたたみ、コンテキストを維持しながらトークンを最大 90% 節約します。
5. AST と正規表現による依存関係のマッピング：AST 解析で依存関係のインポートを正確に自動追跡し、フォールバック時のシンボルマッピングを高速化するため、ripgrep（rg）でワークスペースを検索します。

📂 対応ファイル形式とパーサーエンジン

MCP Scout は、速度と複数言語への柔軟な対応を最適化するために設計された、2 つの専用パーサーエンジンを提供します。

🔍 パーサー選択の詳細ガイド

パーサーモード	対象言語	主な利点	推奨されるユースケース
oxc（デフォルト）	.js、.jsx、.ts、.tsx、.json	非常に高速な Rust 製パーサーです。コンパイラーのセットアップ不要で、すぐにインストールできます。	純粋なウェブアプリ、React／Vue フロントエンド、Node.js バックエンド。
tree-sitter	.js/.ts（OXC 経由）＋ .py、.go、.rs、.rb、.java、.cpp、.cs、.php など	WASM モジュールによるマルチ言語対応です。	マルチ言語バックエンド、モノレポ、ハイブリッド環境。

1. Rust を活用した oxc パーサー（デフォルト）

• 最適な用途： 純粋な JavaScript／TypeScript コードベース、Next.js、Node.js、一般的なウェブアプリケーション。
• 内部の仕組み： 最先端の Rust でコンパイルされた oxc-parser を利用します。
• 主な利点： メモリーオーバーヘッドをほぼゼロに抑え、ファイルをマイクロ秒単位で処理します。macOS、Windows、Linux でコンパイルエラーなしにすぐインストールできます。

2. マルチ言語対応の tree-sitter パーサー（オプション）

• 最適な用途： 複数の言語にまたがるモノレポやバックエンドサービス（例：React フロントエンド＋Python FastAPI／Go バックエンド）。
• 対応言語： Python（.py）、Go（.go）、Dart（.dart）、Rust（.rs）、Ruby（.rb）、Java（.java）、C／C++（.c、.cpp、.h、.hpp）、C#（.cs）、PHP（.php）。
• ハイブリッドによる高速化： tree-sitter モードに設定しても、MCP Scout はすべての .js/.jsx/.ts/.tsx ファイルを oxc-parser に渡し、最高のパフォーマンスを確保します。WebAssembly ベースの tree-sitter は、ほかの言語にのみ使用します。

対象外： ビルド出力やノイズの多いディレクトリ（node_modules/、dist/、build/、.git/、coverage/）に加え、テストファイルも自動的に無視します（ツール引数で明示的に指定した場合を除きます）。

---

🏗️ アーキテクチャと構成

アーキテクチャは、厳格な SOLID 原則に基づいて設計された、高度にモジュール化された疎結合のマルチパイプラインエンジンへと進化しました。

graph TD
    UserQuery["User / AI Request"] --> MCPClient["AI Client (Cursor, Claude, Gemini, etc.)"]

    subgraph MCP Scout Server
        MCPClient --> Tools

        subgraph Tools ["Exposed MCP Tools Boundaries (src/tools/)"]
            Triage["triage (Dynamic AI Criteria)"]
            FindCode["find_code"]
            TraceSymbol["trace_symbol"]
            GetContext["get_file_context"]
            BlastRadius["blast_radius"]
            DeadCode["dead_code"]
            Clusters["subsystem_clusters"]
            Diagnostics["get_diagnostics"]
            FindFiles["find_files"]
            ExplainPack["explain_context_pack"]
            RefreshMap["refresh_map"]
            CleanupWorkspace["cleanup_workspace"]
        end

        Tools --> Indexer{"Map Cached?"}
        Indexer -- No --> Parser["Oxc AST Parser (TS/JS/JSON) & Tree-Sitter"]
        Parser --> WriteMap["Build .project_map.json"]
        WriteMap --> Dispatcher["Execution Dispatcher"]
        Indexer -- Yes --> Dispatcher

        Dispatcher -- triage --> JevEngine["TypeSafe Jev (System 1 Engine)"]
        subgraph JevPipeline ["Dynamic System-1 Triage (<500ms)"]
            JevEngine --> ASTSkeletons["Generate AST File Skeletons (Exports, Imports, Sigs)"]
            ASTSkeletons --> SinglePass["Batch Evaluate AI Criteria (check, classify, score)"]
            SinglePass --> CalibratedScores["Rank by Calibrated Probabilities"]
        end

        Dispatcher -- find_code --> QueryAnalysis["Step 1: Query Analysis"]
        QueryAnalysis --> DetMatch["Step 2: Deterministic Matching"]
        DetMatch --> HighConfidence{"Confidence ≥ 0.95?"}
        HighConfidence -- Yes --> Extraction["AST Extraction"]
        HighConfidence -- No --> LLMFilter["Step 3: LLM Search & Ranking"]
        LLMFilter --> Extraction

        Extraction --> Budget["Apply Context Budget"]
        Budget --> ContentVal["Step 4: Content Validation"]
        ContentVal --> Formatter["Markdown / JSON Formatter"]
        CalibratedScores --> Formatter
    end

    Formatter --> AIResponse["AI Consumes Structured, Hallucination-Free Context"]

📂 ディレクトリ構成とコード品質

コードベースは厳格な基準（20 行を超える関数なし、any の使用ゼロ、明確な SRP の境界）に準拠しています。

• src/index.ts：極めて簡潔なサーバーのブートストラッパー（50 行未満）です。設定を読み込み、サーバーをインスタンス化し、トランスポートをセットアップします。
• src/tools/：専用のツール境界レイヤーです。各ツールの登録（例：dynamicTriageTool.ts、findCodeTool.ts、traceSymbolTool.ts）は、それぞれ独立したファイルに完全に分離されています。
• src/extraction/jev/：型安全な Jev System 1 の統合機能です（バッチ処理を行う client.ts、動的な AI と AST の基準交渉を行う dynamic-triage.ts）。
• src/shared/：疎結合な共有ドメインオブジェクト、ユーティリティ、型、エラーマネージャーです（例：src/shared/fs/resolveWorkspaceRoot.ts、src/shared/errors/errorMessage.ts）。
• src/indexing/：中核となる解析エンジン（oxc-walker.ts、tree-sitter-walker.ts）と、モジュールのマッピングや TSConfig の paths を処理するパス解決機能です。
• src/pipeline/：複雑なワークフローを整った Markdown の応答にまとめるオーケストレーションレイヤーです。
• src/extraction/：クエリ分析（query-analyzer.ts）、LLM クライアント（llm.ts）、コンテンツ検証（content-validator.ts）、マッチング（matcher/filter.ts）を担います。

🔒 読み取り専用の仕様

MCP Scout はプロジェクトのソースコードに対して読み取り専用です。ユーザーファイルの変更、作成、削除は一切行いません。書き込み先は自身のキャッシュのみです。

• .project_map.json — AST のシンボルマップをキャッシュします（古くなるまでリクエスト間で再利用されます）。
• .scout-cache/ — L2 抽出キャッシュです（シンボルごとのコード抽出を保存し、ソースファイルの変更時に無効化されます）。
• どちらも cleanup_workspace を使って安全にクリーンアップするか、手動で削除できます。

---

📦 要件とインストール

要件

• Node.js >= 18
• Bun >= 1.1.0（リポジトリのテストランナー用）
• Ripgrep（rg）（シンボルの依存関係の検索用）

クイック実行（グローバル／インストール不要）

ローカルにインストールせず、MCP の設定内で npx を使ってサーバーを直接実行できます。

npx smarter-faster-better-mcp

インストール

グローバルインストール

npm install -g smarter-faster-better-mcp

依存関係としてローカルにインストール

bun add smarter-faster-better-mcp

---

⚙️ 設定

サーバーは、環境変数とローカルの .env ファイルから設定パラメーターを自動的に読み込みます。

🌟 推奨設定（.env ファイル）

バージョン 0.10.0 以降、MCP Scout は、1 秒未満で型付きコードのトリアージを行う TypeSafe Jev (System 1) を統合し、低速なローカル LLM を不要にします。また、現在の作業ディレクトリ（process.cwd()）にある .env を自動的に読み込みます。

プロジェクトのルートにある .env を設定するだけです。

# TypeSafe Jev System 1 (Recommended for sub-second dynamic triage & candidate filtering)
JEV_API_KEY=apikey_your_typesafe_key_here
# JEV_BASE_URL=https://api.typesafe.ai
# SCOUT_PARSER=auto

API キーを安全かつプライベートに保つため、.env を .gitignore に追加してください。

利用可能な変数

変数	説明	デフォルト	推奨／用途
JEV_API_KEY (または TYPESAFE_API_KEY)	TypeSafe Jev (System 1 model) の API キー	-	サブ秒でのコードと仮説のトリアージ、および候補のフィルタリングに推奨
JEV_BASE_URL	TypeSafe Jev API のカスタムエンドポイント	https://api.typesafe.ai	いいえ（デフォルトは公式 API）
SCOUT_PARSER	パーサーモード：auto（JS／TS 以外のファイルを検出）、oxc、または tree-sitter	auto	いいえ
SCOUT_WORKSPACE_ROOT	対象ワークスペースのディレクトリパスを上書き	自動検出	いいえ

CLI フラグを使って、特定のパーサーモードを指定することもできます。

npx smarter-faster-better-mcp --parser tree-sitter

---

🖥️ クライアント連携

サーバーはアクティブなプロジェクトのローカル .env ファイルを自動的に読み込むため、AI IDE での設定は非常にシンプルで軽量です。

Claude Desktop

設定ファイル（macOS では通常 ~/Library/Application Support/Claude/claude_desktop_config.json）に以下を追加します。

{
  "mcpServers": {
    "scout": {
      "command": "npx",
      "args": ["smarter-faster-better-mcp"]
    }
  }
}

Cursor / Windsurf / Trae（大幅に簡素化された設定）

IDE の設定自体で環境変数を指定する必要がないため、IDE の設定で標準の Command MCP Server として簡単に追加できます。

• 名前：scout
• 種類：command
• コマンド：npx
• 引数：smarter-faster-better-mcp

または、JSON 形式で指定します。

"scout": {
  "command": "npx",
  "args": [
    "smarter-faster-better-mcp"
  ]
}

Claude Code

1 つのコマンドでサーバーを追加できます。

claude mcp add scout npx smarter-faster-better-mcp

---

🛠️ 公開されているツール

MCP サーバーは、AI コンテキストエンジンを強化する豊富なツールを公開します。

find_code

重要：コードを検索するには、まずこのツールを使用してください。 4 段階のパイプラインです：（1）LLM によるクエリ分析で、意図、シンボル名、拡張語句、ファイルパターンを抽出します。（2）分析結果を活用して決定論的なマッチングを行います。（3）分析コンテキストを用いて、LLM の支援によるランキングを行います。（4）抽出したコードとクエリを照合し、誤検出を除外するコンテンツ検証を行います。

• パラメーター：task、summaryOnly、workspaceRoot、maxFiles、maxSymbols、maxChars、includeTests

trace_symbol

AST グラフを検索して、シンボルの定義、その依存関係、および呼び出し元／インポート元のすべてのファイルを再帰的に見つけます。

• パラメーター：symbolName、file、workspaceRoot

get_file_context

重要：コードの内容を調べる際は、デフォルトの「read_file」や「view_file」ツールではなく、必ずこのツールを使用してください。 ファイルの正確な行範囲または全内容を安全に取得し、生のダンプを自動的に遮断します。さらに、ローカル LLM を使って関連する内容を抽出し、関連性をスコアリングします。

• パラメーター：file、startLine、endLine、workspaceRoot、query（コンテンツのフィルタリングに使う AI クエリ／意図のコンテキスト）

find_files

対象ワークスペース内で、サフィックスまたはドメインパターンに基づいてファイルを検索します。

• パラメーター：pattern、workspaceRoot

cleanup_workspace

一時ディレクトリ、ビルド出力（dist、build、cache、bin）、不要なドットファイル／フォルダー（.git、.ide、.vscode、.DS_Store）を削除してワークスペースをクリーンアップします。重要なファイル（node_modules、.env、設定ファイル）は保持します。

• パラメーター：workspaceRoot、dryRun（省略可能なプレビューモード）

explain_context_pack

関連するコードファイルの、関数やクラスの本体を折りたたんだ、トークン効率の高い計画用アウトラインを返します。システムの概要計画を作成するのに最適です。

• パラメーター: task、workspaceRoot

refresh_map

プロジェクトの AST シンボルマップとインポートグラフを完全に再構築します。新しいファイルを手動で追加した場合や、キャッシュを完全に無効化する必要がある場合に使用します。

• パラメーター: workspaceRoot

blast_radius

コードシンボルを変更した場合の影響範囲を分析します。対象のシンボルを変更すると影響を受けるすべてのファイル、モジュール、実行フローを表示します。共有コードのリファクタリング、名前変更、削除の前に使用してください。

• パラメーター: symbolName、file、workspaceRoot

dead_code

プロジェクト内のデッドコード／未使用コードを検出します。プロジェクトのエントリーポイントからの完全な BFS グラフ到達可能性分析により、到達不能な孤立ファイル、ほかの場所からインポートされていないデッドエクスポート、デッドアイランドを特定します。

• パラメーター: entrypoints、includeExports、minConfidence、workspaceRoot

subsystem_clusters

プロジェクトの依存関係グラフに Louvain コミュニティ検出を適用し、凝集度と結合度の指標を用いて、アーキテクチャ上のサブシステム、モジュール、ドメイン境界を発見します。

• パラメーター: resolution、minClusterSize、workspaceRoot

get_diagnostics

ライブ LSP とコンパイラーの診断ブリッジ。 バックグラウンドで動作する TypeScript Language Service を利用して、リアルタイムの意味的診断（型エラー、構文エラー、インポートの欠落／解決不能）を取得します。

• パラメーター: file（省略可能な相対／絶対パス）、severity（'error' | 'warning' | 'all'）、limit、targetRoot

triage

ユニバーサル AI-to-Code 動的トリアージエンジン。 TypeSafe Jev（System 1） を搭載しています。外部の AI モデル（Claude、GPT、Gemini、GLM）であればどれでも、ハードコードされた分類体系やスキーマなしで、AST の候補ファイルに対する任意のドメイン固有の基準を、単一の高速処理（<500ms）で評価できます。

使用する場面：

• コードベースを調査していて、ファイル全体を読む前にアーキテクチャ上の仮説を検証したい場合。
• 独自のドメイン層（例：is_auth_entrypoint、storage_layer、pipeline_step）に基づいて候補ファイルを分類したい場合。
• LLM のコンテキストトークンを無駄にせず、無関係な候補ファイルの 90% を除外したい場合。

パラメーター:

• intent: 探しているものを自然言語で説明します。
• criteria: 呼び出し元の AI がその場で作成する動的な質問のマップです。
  • check: 二値検証（question、省略可能な yesMeans、noMeans）を行い、正確な確率（0..1）とともに yes | no | uncertain を返します。
  • classify: 呼び出し元が定義した options からカテゴリを選択し、選択結果と確率分布を返します。
  • score: 呼び出し元が定義した levels に沿った順序付き評価基準で評価し、較正済みスコアと分布を返します。
• searchHints: 初期の大まかな AST フィルタリングに使用するキーワード／シンボルの断片（例：`["ast", "parse", "extract"]）です。省略可能です。
• candidateFiles: すでに判明している場合に指定する候補ファイルのパスです。省略可能です。
• minConfidence: 応答に候補を含めるために必要な最小の総合信頼度スコア（デフォルト：0.5）です。
• limit: 評価する候補の最大数（デフォルト：8）です。

リクエストの例：

{
  "intent": "Find code related to syntax parsing or AST extraction",
  "searchHints": ["ast", "parse", "extract"],
  "criteria": {
    "is_parser": {
      "type": "check",
      "question": "Does this file perform AST parsing or extraction of source code syntax trees?"
    },
    "layer": {
      "type": "classify",
      "question": "Which architectural layer does this code belong to?",
      "options": {
        "parsing_extraction": "Direct AST parsing or syntax extraction logic",
        "config_utils": "General configuration or basic utility",
        "mcp_tool": "MCP tool interface definition"
      }
    }
  },
  "limit": 3
}

レスポンスの例：

{
  "intent": "Find code related to syntax parsing or AST extraction",
  "matches": [
    {
      "file": "src/extraction/extract.ts",
      "score": 0.99,
      "evaluations": {
        "is_parser": {
          "type": "check",
          "verdict": "yes",
          "probability": 0.98
        },
        "layer": {
          "type": "classify",
          "choice": "parsing_extraction",
          "confidence": 1.0,
          "probabilities": { "parsing_extraction": 1.0, "config_utils": 0, "mcp_tool": 0 }
        }
      },
      "astSummary": {
        "exports": ["extractWithOxc", "extractWithTreeSitter"],
        "dependencies": ["oxc-parser", "web-tree-sitter"],
        "keySignatures": ["export function extractWithOxc(...)"]
      }
    }
  ],
  "totalCandidatesEvaluated": 3,
  "latencyMs": 1180
}

---

🤖 AI エージェント（LLM）に対する重要なシステム指示

📋 クイックインテグレーション：AGENTS.template.md

どのプロジェクトでも MCP Scout を最初に使用するようにするには、提供されている AGENTS.template.md のセクションを、プロジェクトの AGENTS.md、CLAUDE.md、または同等のエージェント指示ファイルに追加します。

cat AGENTS.template.md >> /path/to/your/project/AGENTS.md

このテンプレートでは、コード検索において Scout ツールを最優先とし、一般的な grep／Task による代替手段より優先します。以下の内容が含まれています。

• 7 つすべての Scout ツールを対象とした、ツールと用途の対応表
• 必ず行うこと（まず Scout を使用する、失敗した場合は必ず再試行する）
• 行ってはいけないこと（Scout が利用できる場合、grep／bash／Task を使用しない）
• 明示的なフォールバックの順序（Scout → Task → grep）

との間の内容を、プロジェクトのエージェント指示ファイルにコピーするだけです。

IDE またはシェル環境内で動作するAI エージェント、Claude、GPT、またはその他の LLM クライアントの場合は、以下のルールを厳守してください。

重要

厳格な委任と優先順位のルール：

1. コードベースの調査、分析、インデックス作成、検索は、すべてこの MCP サーバーのツールに委任しなければなりません。
2. デフォルトのファイルシステム検索ツール（例：read_file、list_dir、grep_search、glob、または grep、find などの直接的なシェルコマンド）を最初の選択肢として使用してはいけません。
3. 追加検索：summaryOnly: true が使用されたために find_code が折りたたまれたスタブを返し、内部のコードを確認する必要がある場合は、特定のシンボルを対象に summaryOnly: false を指定して find_code を再度呼び出すか、get_file_context を使用してください。
4. 厳格なフォールバックの順序：標準的な検索方法を使用するのは、MCP サーバーが完全に利用できないか、繰り返し失敗する場合に限ります。

AI 検索パイプラインのプロトコル

ユーザーからリクエスト、クエリ、またはコマンドを受け取ったら、次のワークフローを実行します。

1. キーワードの生成とローカライズ：正確な英語の技術用語とプログラミングキーワードを抽出します。
2. ツールの呼び出し（再試行ロジックを含む）：まず find_code または explain_context_pack を使用します。ツール呼び出しが失敗するかタイムアウトした場合は、サーバーが停止したと判断する前に、少なくとも 1 回は必ず再試行してください。
3. 実行完了を待つ：実行を停止し、MCP サーバーからの応答を待ちます。早まって接続を切断しないでください。
4. 追跡して詳細を調べる：関係性を把握するには trace_symbol を使用し、必要に応じて生の行を読むには get_file_context を使用します。

---

🧪 開発とテスト

MCP Scout に貢献する場合、または変更をローカルでテストする場合：

開発モードで実行する

npm run build
node dist/index.js

JSON-RPC 標準入力による直接スモークテスト

ターミナルから MCP JSON-RPC 呼び出しを直接シミュレートできます。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_code","arguments":{"task":"database connection"}}}' \
  | node dist/index.js

インタラクティブな MCP インスペクター

公式のブラウザーベースの MCP インスペクターを使用してデバッグするには：

npx @modelcontextprotocol/inspector node dist/index.js

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については LICENSE ファイルを参照してください。