Code Sage

🚀 Code Sage

Code Sage 是一個用 Rust 編寫的高性能 MCP（模型上下文協議）服務器，用於語義代碼搜索。它結合了多種先進技術，能高效地對代碼進行索引和搜索，為開發者提供強大的代碼搜索功能。

✨ 主要特性

• 混合搜索：將 BM25（基於關鍵詞）和向量嵌入（語義）搜索相結合，並使用 RRF 重排序，以提供更精準的搜索結果。
• 基於 AST 的代碼分塊：利用 tree-sitter 智能地將代碼分割成語義單元（函數、類、方法）。
  • 基於字符的回退機制：對於 AST 解析失敗或不可用的文件，採用字符分塊方式。
  • 廣泛的語言支持：開箱即用，支持 60 多種文件擴展名。
• 智能文件過濾：
  • 自動支持 .gitignore（遵循 .gitignore、.ignore、.git/info/exclude）。
  • 支持自定義文件擴展名，以適應特定項目的文件類型。
  • 無需配置，即開即用。
• 嵌入式存儲：零外部依賴，所有數據本地存儲。
  • 使用 USearch 進行向量相似度搜索。
  • 使用 Tantivy 進行 BM25 全文搜索。
  • 使用 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。
  • ** shell 腳本**：.sh、.bash、.zsh、.fish。
  • 基於字符的回退機制：.ini、.txt、.rst 以及通過 custom_extensions 添加的任何擴展名。

🔧 技術細節

架構設計

詳細的架構文檔請參考 ARCHITECTURE.md。

關鍵設計決策：

1. 混合搜索優於純語義搜索：結合關鍵詞和語義搜索，以獲得更好的結果。
2. 嵌入式架構優於客戶端 - 服務器架構：所有操作本地運行，無需向量數據庫服務器。
3. 優先使用 AST 分塊並提供回退機制：儘可能進行語義分塊，必要時採用基於字符的分塊。
4. 使用 Rust 保證性能：高效的內存使用和快速處理。

索引流程

代碼文件
    ↓
AST 解析（tree-sitter）
    ↓
語義塊（函數、類）
    ↓
嵌入（OpenAI/Ollama）
    ↓
存儲（USearch + Tantivy + Sled）

混合搜索

查詢
    ↓
    ├─→ 向量搜索（USearch） → 前 50 個結果
    │
    └─→ BM25 搜索（Tantivy） → 前 50 個結果
    
    ↓
RRF 重排序（k=100 合併）
    ↓
最終結果（前 K 個）

RRF（互反排名融合）： 混合搜索使用 RRF 重排序，根據向量和 BM25 搜索結果的排名位置而非原始分數進行平衡。這創建了一個公平且平衡的最終排名，結合了語義相關性和關鍵詞匹配。瞭解更多關於 RRF

RRF 公式使用 score = 1/(k + rank) 結合排名，其中 k 是平滑參數（默認值：100，可通過 RRF_K 環境變量配置）。

📦 安裝指南

前提條件

• 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. 轉到“本地服務器”選項卡。
4. 點擊“啟動服務器”（默認端口：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：.gradle、.properties。
• 構建系統：.cmake、.sbt、.make。
• Web/樣式：.html、.htm、.css、.scss、.sass、.less。
• ** shell 腳本**：.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%：元數據存儲。

這確保了平穩的進度更新，沒有突然的跳躍，提供了對分析過程的更好可見性。

開發設置

# 安裝依賴
cargo build

# 運行測試
cargo test

# 帶日誌運行
RUST_LOG=debug cargo run

# 格式化代碼
cargo fmt

# 代碼檢查
cargo clippy

📚 詳細文檔

靈感與致謝

本項目的靈感來源於：

• claude-context - 原始 TypeScript 實現。
• 圍繞混合搜索和 AST 分塊的設計決策。
• MCP 協議實現模式。

主要區別：

• 使用 Rust 編寫以提高性能。
• 嵌入式存儲（無需 Milvus/Qdrant 服務器）。
• 簡化的架構。
• 原生二進制文件（更易於部署）。
• 更簡單的處理程序響應（JSON 字符串）。

許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE。

已知問題與限制

• 文件大小限制：每個文件最大為 1MB。
• 擴展名過濾：文件必須具有支持的擴展名或通過 custom_extensions 添加才能進行分析。
• 存儲：目前不支持壓縮（正在努力改進）。
• 切換提供方：當更改具有不同維度的嵌入提供方時（例如，從 OpenAI 1536 到 LM Studio 768），在重新索引之前刪除 data/ 文件夾，以避免維度不匹配錯誤。

支持

• 問題反饋：GitHub Issues
• 討論交流：GitHub Discussions

用 ❤️ 和 Rust 構建 🦀