Code Sage

🚀 Code Sage

高性能なMCP（Model Context Protocol）サーバーで、Rustで書かれたセマンティックコード検索ツールです。コードの機能や意味を理解し、効率的な検索を可能にします。

✨ 主な機能

• ハイブリッド検索：BM25（キーワードベース）とベクトル埋め込み（セマンティック）をRRF再ランキングで組み合わせます。
• ASTベースのチャンキング：tree - sitterを使用して、コードをセマンティックユニット（関数、クラス、メソッド）に賢く分割します。
  • 文字ベースのフォールバック：AST解析が失敗したり利用できないファイルに対応します。
  • 包括的な言語サポート：60以上のファイル拡張子がデフォルトでサポートされています。
• スマートなファイルフィルタリング：
  • 自動的な.gitignoreサポート（.gitignore、.ignore、.git/info/excludeを尊重します）。
  • プロジェクト固有のファイルタイプに対するカスタムファイル拡張子のサポート。
  • 設定不要 - すぐに使えます。
• 組み込みストレージ：外部依存関係がゼロ - すべてのデータがローカルに保存されます。
  • ベクトル類似性検索にUSearchを使用。
  • BM25全文検索にTantivyを使用。
  • メタデータ保存にSledを使用。
• 複数の埋め込みプロバイダー：
  • OpenAI（text - embedding - 3 - small、text - embedding - 3 - large）。
  • LM Studio（推奨） - OpenAI互換のローカル埋め込みで、より安定しています。
  • Ollama（ローカル埋め込み） - 注意：一部のモデルでmacOS M1で不安定な場合があります。
• MCP互換：Claude Desktop、Cursor、その他のMCPクライアントと互換性があります。
• 多言語サポート：
  • プログラミング言語（AST）：Rust、Python、JavaScript/TypeScript、Java、C/C++、Go、C#、Swift、Kotlin、Ruby、Elixir、Objective - C、PHP、Scala。
  • 設定/マークアップ（AST）：JSON、YAML、XML、HTML、CSS、SCSS、TOML、Markdown。
  • iOS/macOS：.xib、.storyboard、.plist（XMLパーサー経由）、.xcconfig（TOMLパーサー経由）。
  • Android/Java：.xml（レイアウト、マニフェスト）、.gradle、.properties。
  • ビルドシステム：.cmake、.sbt、.make、Makefile、CMakeLists.txt。
  • シェルスクリプト：.sh、.bash、.zsh、.fish。
  • 文字ベースのフォールバック：.ini、.txt、.rst、およびcustom_extensionsで追加された任意の拡張子。

🔧 技術詳細

詳細なアーキテクチャドキュメントについては、ARCHITECTURE.mdを参照してください。

主要な設計決定：

1. 純粋なセマンティック検索ではなくハイブリッド検索：キーワード検索とセマンティック検索を組み合わせて、より良い結果を得ます。
2. クライアント - サーバーではなく組み込み型：すべてがローカルで実行され、ベクトルDBサーバーは必要ありません。
3. フォールバック付きのAST優先：可能な場合はセマンティックチャンキング、必要な場合は文字ベースのチャンキングを行います。
4. パフォーマンスのためにRustを使用：効率的なメモリ使用と高速な処理が可能です。

📦 インストール

前提条件

• Rust 1.70以上（エディション2021）
• OpenAI APIキー（またはローカルで実行されているOllama）

ソースからビルド

git clone https://github.com/faxioman/code-sage.git
cd code-sage
cargo build --release

バイナリはtarget/release/code-sageに配置されます。

💻 使用例

MCPサーバーの設定

MCPクライアントの設定（例：Claude Desktop）に追加します。

LM Studio（推奨）

{
  "mcpServers": {
    "code-sage": {
      "command": "/path/to/code-sage",
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "lm-studio",
        "EMBEDDING_BASE_URL": "http://localhost:1234/v1",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "DATA_DIR": "./data"
      }
    }
  }
}

OpenAI（クラウド）

{
  "mcpServers": {
    "code-sage": {
      "command": "/path/to/code-sage",
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-your-key-here",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "DATA_DIR": "./data"
      }
    }
  }
}

Ollama（実験的）

{
  "mcpServers": {
    "code-sage": {
      "command": "/path/to/code-sage",
      "env": {
        "EMBEDDING_PROVIDER": "ollama",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "DATA_DIR": "./data"
      }
    }
  }
}

プロバイダーのセットアップ

LM Studio（推奨）

1. LM Studioをダウンロードします。
2. nomic-embed-textモデルを検索してダウンロードします。
3. "Local Server"タブに移動します。
4. "Start Server"をクリックします（デフォルトポート：1234）。
5. 上記の設定を使用します。

Ollama

1. Ollamaをインストールします。
2. ollama pull nomic-embed-textを実行します。
3. Ollamaサービスを起動します。
4. 上記の設定を使用します。

高度な設定

envセクションにオプションのパラメーターを追加できます。

{
  "mcpServers": {
    "code-sage": {
      "command": "/path/to/code-sage",
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-your-key-here",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "DATA_DIR": "./data",
        "DEFAULT_TOP_K": "10",
        "MIN_SCORE": "0.3",
        "RRF_K": "100",
        "CHUNK_SIZE": "2500",
        "CHUNK_OVERLAP": "300",
        "BATCH_SIZE": "100",
        "MAX_CHUNKS": "450000"
      }
    }
  }
}

利用可能なMCPツール

1. analyze_code

関数、クラス、メソッドを分析して、コードの検索可能なインデックスを作成します。

{
  "path": "/absolute/path/to/codebase",
  "force": false,
  "splitter": "ast",
  "custom_extensions": [".proto", ".sql"],
  "ignore_patterns": ["*.test.ts", "tmp/*"]
}

パラメーター：

• path（必須）：コードベースディレクトリの絶対パス
• force（オプション）：すでに分析されている場合でも再分析を強制する（デフォルト：false）
• splitter（オプション）：チャンキング戦略 - "ast"または"langchain"（デフォルト："ast"）
• custom_extensions（オプション）：デフォルトの60以上の拡張子以外に分析する追加のファイル拡張子（例：[".proto", ".graphql"]）
• ignore_patterns（オプション）：無視する追加のパターン（.gitignoreを補完します）

ファイル選択の仕組み：

1. 拡張子フィルタリング：サポートされている拡張子のファイルのみが分析されます（デフォルトで60以上）。
2. Gitignoreの尊重：自動的に.gitignore、.ignore、.git/info/excludeを尊重します。
3. カスタム拡張子：custom_extensionsを使用して、デフォルトに含まれないプロジェクト固有のファイルタイプを追加できます。
4. 隠しファイル：デフォルトではスキップされます。

デフォルトでサポートされている拡張子（合計60以上）：

• 主要な言語：.rs、.py、.js、.jsx、.ts、.tsx、.java、.c、.h、.cpp、.hpp、.go、.cs、.swift、.kt、.rb、.ex、.exs、.m、.mm、.php、.scala
• JS/TSバリアント：.mjs、.cjs
• 設定形式：.json、.yaml、.yml、.toml、.xml、.ini
• iOS/macOS：.xib、.storyboard、.plist、.xcconfig
• Android/Java：.xml（レイアウト、マニフェスト）、.gradle、.properties
• ビルドシステム：.cmake、.sbt、.make
• Web/スタイリング：.html、.htm、.css、.scss、.sass、.less
• シェルスクリプト：.sh、.bash、.zsh、.fish
• .NET：.csproj、.sln、.config、.props、.targets
• Ruby：.gemspec、.rake
• Elixir：.ex、.exs
• ドキュメント：.md、.markdown、.txt、.rst
• ノートブック：.ipynb

カスタム拡張子の追加例：

{
  "path": "/path/to/project",
  "custom_extensions": [".proto", ".graphql", ".vue", ".svelte"]
}

返り値：成功/エラーメッセージを含むJSON

2. find_code

自然言語の質問を使用してコードを検索します。

{
  "path": "/absolute/path/to/codebase",
  "query": "authentication logic",
  "limit": 10,
  "extension_filter": [".ts", ".js"]
}

返り値：検索結果と整形されたコードスニペットを含むJSON

3. delete_index

コードベースの検索インデックスを削除します。

{
  "path": "/absolute/path/to/codebase"
}

返り値：確認メッセージを含むJSON

4. check_status

コード分析が完了したか、進行中か、失敗したかを確認します。

{
  "path": "/absolute/path/to/codebase"
}

返り値：ステータス（分析済み、分析中（%）、失敗、または未検出）を含むJSON

進捗トラッキング（2025 - 11 - 10更新）： 分析の進捗は、正確なフィードバックを提供するために細かいフェーズに分割されています。

• 0 - 30%：ファイル処理（スキャンとチャンキング）
• 30 - 60%：埋め込み生成（バッチごとに更新）
• 60 - 85%：ベクトルデータベースの保存
• 85 - 95%：BM25全文インデックス作成
• 95 - 100%：メタデータの保存 これにより、急激なジャンプがなく、分析プロセスの可視性が向上します。

仕組み

1. インデックス作成パイプライン

Code Files
    ↓
AST Parsing (tree-sitter)
    ↓
Semantic Chunks (functions, classes)
    ↓
Embeddings (OpenAI/Ollama)
    ↓
Storage (USearch + Tantivy + Sled)

2. ハイブリッド検索

Query
    ↓
    ├─→ Vector Search (USearch) → Top 50 results
    │
    └─→ BM25 Search (Tantivy) → Top 50 results
    
    ↓
RRF Reranking (merge with k=100)
    ↓
Final Results (Top K)

RRF（Reciprocal Rank Fusion）： ハイブリッド検索では、RRF再ランキングを使用して、ベクトル検索とBM25検索の結果を、生のスコアではなくランキング位置に基づいてバランスさせます。これにより、セマンティックな関連性とキーワードマッチングを組み合わせた公平でバランスの取れた最終ランキングが作成されます。RRFについて詳しく学ぶ

RRFの式は、score = 1/(k + rank)を使用してランキングを組み合わせます。ここで、kは平滑化パラメーター（デフォルト：100、RRF_K環境変数で設定可能）です。

開発環境のセットアップ

# 依存関係のインストール
cargo build

# テストの実行
cargo test

# ロギング付きで実行
RUST_LOG=debug cargo run

# コードのフォーマット
cargo fmt

# リント
cargo clippy

📄 ライセンス

MITライセンス - LICENSEを参照してください。

既知の問題と制限事項

• ファイルサイズ制限：ファイルごとに1MBまで
• 拡張子フィルタリング：分析するファイルは、サポートされている拡張子を持つか、custom_extensionsで追加する必要があります。
• ストレージ：まだ圧縮がサポートされていません（開発中）
• プロバイダーの切り替え：異なる次元の埋め込みプロバイダーを切り替える場合（例：OpenAI 1536からLM Studio 768）、再インデックス作成の前にdata/フォルダを削除して、次元の不一致エラーを回避してください。

サポート

• 問題報告：GitHub Issues
• ディスカッション：GitHub Discussions

Rustで愛情を込めて作られました 🦀