Claude Context Local

🚀 本地版Claude代碼上下文搜索工具

Claude代碼上下文搜索工具的本地版本，藉助EmbeddingGemma模型實現100%本地運行的語義代碼搜索。無需API密鑰，零成本使用，您的代碼不會離開本地設備。

🚀 快速開始

1) 註冊MCP服務器（標準輸入輸出模式）

claude mcp add code-search --scope user -- uv run --directory ~/.local/share/claude-context-local python mcp_server/server.py

然後打開Claude Code，服務器將在uv環境中以標準輸入輸出模式運行。

2) 索引您的代碼庫

打開Claude Code並輸入：index this codebase，無需手動輸入命令。

3) 在Claude Code中使用

在Claude Code的聊天界面中進行交互，無需調用函數或輸入命令。

✨ 主要特性

• 多語言支持：支持9種以上編程語言，涵蓋15種文件擴展名。
• 智能分塊：基於AST的Python解析 + 基於tree - sitter的JS/TS/Go/Java/Rust/C/C++/C#解析。
• 語義搜索：通過自然語言查詢，在所有支持的語言中查找代碼。
• 豐富的元數據：包含文件路徑、文件夾結構、語義標籤、特定語言信息等。
• MCP集成：與Claude Code直接集成。
• 本地處理：所有嵌入向量都存儲在本地，無需調用API。
• 快速搜索：使用FAISS進行高效的相似度搜索。

📦 安裝指南

安裝（單行命令）

curl -fsSL https://raw.githubusercontent.com/FarhanAliRaza/claude-context-local/main/scripts/install.sh | bash

如果您的系統沒有安裝curl，可以使用wget：

wget -qO- https://raw.githubusercontent.com/FarhanAliRaza/claude-context-local/main/scripts/install.sh | bash

更新現有安裝

運行相同的安裝命令進行更新：

curl -fsSL https://raw.githubusercontent.com/FarhanAliRaza/claude-context-local/main/scripts/install.sh | bash

安裝程序將執行以下操作：

• 檢測您現有的安裝。
• 保留您在~/.claude_code_search中的嵌入向量和已索引的項目。
• 自動保存本地更改（如果通過curl運行）。
• 更新代碼和依賴項。

安裝程序的具體操作

• 如果缺少uv，則安裝uv並創建項目虛擬環境。
• 在~/.local/share/claude-context-local中克隆/更新claude-context-local。
• 使用uv sync安裝Python依賴項。
• 如果尚未緩存，下載EmbeddingGemma模型（約1.2 - 1.3 GB）。
• 如果檢測到NVIDIA GPU，嘗試安裝faiss-gpu（僅在交互模式下）。
• 在更新過程中保留您所有已索引的項目和嵌入向量。

💻 使用示例

基礎用法

本項目主要通過命令行和Claude Code進行交互，以下是註冊MCP服務器的基礎命令：

claude mcp add code-search --scope user -- uv run --directory ~/.local/share/claude-context-local python mcp_server/server.py

高級用法

在Claude Code中進行代碼搜索時，您可以使用自然語言進行查詢，例如：“查找所有處理用戶登錄的代碼”。

📚 詳細文檔

為什麼選擇本項目

Claude的代碼上下文功能很強大，但將代碼發送到雲端會消耗令牌並引發隱私問題。本項目將語義代碼搜索完全放在本地設備上進行。它通過MCP與Claude Code集成，讓您保持相同的工作流程，同時更快、更便宜且更安全。

要求

• Python 3.12及以上版本。
• 磁盤：1 - 2 GB可用空間（模型 + 緩存 + 索引）。
• 可選：NVIDIA GPU（CUDA 11/12）用於FAISS加速；Apple Silicon（MPS）用於嵌入加速。這些也可以加快使用SentenceTransformer運行嵌入模型的速度，但所有功能在CPU上仍然可以正常工作。

架構

claude-context-local/
├── chunking/                         # 多語言分塊（15種文件擴展名）
│   ├── multi_language_chunker.py     # 統一編排器（Python AST + tree-sitter）
│   ├── python_ast_chunker.py         # 特定於Python的分塊（豐富的元數據）
│   └── tree_sitter.py                # Tree-sitter：JS/TS/JSX/TSX/Svelte/Go/Java/Rust/C/C++/C#
├── embeddings/
│   └── embedder.py                   # EmbeddingGemma；設備自動選擇（CUDA→MPS→CPU）；離線緩存
├── search/
│   ├── indexer.py                    # FAISS索引（默認CPU；可用時GPU）
│   ├── searcher.py                   # 智能排序和過濾
│   └── incremental_indexer.py        # 基於Merkle的增量索引
├── merkle/
│   ├── merkle_dag.py                 # 工作區的內容哈希有向無環圖
│   ├── change_detector.py            # 比較快照以查找更改的文件
│   └── snapshot_manager.py           # 快照持久化和統計信息
├── mcp_server/
│   └── server.py                     # 用於Claude Code的MCP工具（標準輸入輸出/HTTP）
└── scripts/
    ├── install.sh                    # 單行遠程安裝程序（uv + 模型 + faiss）
    ├── download_model_standalone.py  # 預下載嵌入模型
    └── index_codebase.py             # 獨立的索引工具

數據流

graph TD
    A["Claude Code (MCP客戶端)"] -->|index_directory| B["MCP服務器"]
    B --> C{增量索引器}
    C --> D["更改檢測器<br/>(Merkle DAG)"]
    C --> E["多語言分塊器"]
    E --> F["代碼塊"]
    C --> G["代碼嵌入器<br/>(EmbeddingGemma)"]
    G --> H["嵌入向量"]
    C --> I["代碼索引管理器<br/>(FAISS CPU/GPU)"]
    H --> I
    D --> J["快照管理器"]
    C --> J
    B -->|search_code| K["搜索器"]
    K --> I

智能分塊

系統使用高級解析技術，為所有支持的語言創建語義上有意義的代碼塊：

分塊策略

• Python：基於AST的解析，用於提取豐富的元數據。
• 其他所有語言：基於Tree - sitter的解析，識別特定語言的節點類型。

提取的代碼塊類型

• 函數/方法：包含完整的簽名、文檔字符串、裝飾器。
• 類/結構體：完整的定義，成員函數作為單獨的代碼塊。
• 接口/特性：類型定義和契約。
• 枚舉/常量：值定義和模塊級聲明。
• 命名空間/模塊：組織結構。
• 模板/泛型：參數化類型定義。

所有語言的豐富元數據

• 文件路徑和文件夾結構。
• 函數/類/類型名稱及其關係。
• 特定語言的特性（異步、泛型、修飾符等）。
• 父子關係（類中的方法）。
• 精確的代碼位置行號。
• 語義標籤（組件、導出、異步等）。

配置

環境變量

• CODE_SEARCH_STORAGE：自定義存儲目錄（默認：~/.claude_code_search）

模型配置

系統默認使用google/embeddinggemma - 300m。 注意事項：

• 下載大小：根據變體和緩存，磁盤上約1.2 - 2 GB。
• 設備選擇：自動（NVIDIA上的CUDA，Apple Silicon上的MPS，否則為CPU）。
• 您可以通過安裝程序預下載或在首次使用時下載。
• FAISS後端：默認CPU。如果檢測到NVIDIA GPU，安裝程序將嘗試安裝faiss - gpu - cu12（或faiss - gpu - cu11），並且索引將在運行時自動在GPU上運行，同時保存為CPU版本以確保可移植性。

Hugging Face認證（如果提示）

google/embeddinggemma - 300m模型託管在Hugging Face上，下載可能需要接受條款和/或進行認證。

1. 訪問模型頁面並接受任何條款：
   • https://huggingface.co/google/embeddinggemma - 300m
2. 通過以下方式之一進行認證：
   • CLI（推薦）：

     uv run huggingface - cli login
     # 粘貼您從https://huggingface.co/settings/tokens獲取的令牌
     

   • 環境變量：

     export HUGGING_FACE_HUB_TOKEN = hf_XXXXXXXXXXXXXXXXXXXXXXXX
     

首次成功下載後，我們將模型緩存在~/.claude_code_search/models下，並優先進行離線加載以提高速度和可靠性。

支持的語言和文件擴展名

完全支持（15種文件擴展名，9種以上編程語言）：

總計：15種文件擴展名，涵蓋9種以上編程語言

存儲

數據存儲在配置的存儲目錄中：

~/.claude_code_search/
├── models/          # 下載的模型
├── index/           # FAISS索引和元數據
│   ├── code.index   # 向量索引
│   ├── metadata.db  # 代碼塊元數據（SQLite）
│   └── stats.json   # 索引統計信息

性能

• 模型大小：約1.2GB（EmbeddingGemma - 300m和緩存）
• 嵌入維度：768（可以為了速度進行縮減）
• 索引類型：根據數據集大小選擇Flat（精確）或IVF（近似）
• 批量處理：可配置的批量大小用於生成嵌入向量

提示：

• 在大型倉庫上首次進行索引會花費一些時間（模型加載 + 分塊 + 嵌入）。後續運行是增量式的。
• 使用GPU FAISS時，在大型索引上的搜索速度會顯著提高。
• 如果可用，嵌入向量將自動使用CUDA（NVIDIA）或MPS（Apple）。

故障排除

常見問題

1. 導入錯誤：確保使用uv sync安裝了所有依賴項。
2. 模型下載失敗：檢查網絡連接和磁盤空間。
3. 內存問題：在索引腳本中減小批量大小。
4. 沒有搜索結果：驗證代碼庫是否已成功索引。
5. 未使用FAISS GPU：確保nvidia - smi可用且CUDA驅動已安裝；重新運行安裝程序以選擇faiss - gpu - cu12/cu11。
6. 強制離線：我們會自動檢測本地緩存並優先進行離線加載；您也可以設置HF_HUB_OFFLINE = 1。

忽略的目錄（為了提高速度和減少干擾）

node_modules, .venv, venv, env, .env, .direnv, __pycache__, .pytest_cache, .mypy_cache, .ruff_cache, .pytype, .ipynb_checkpoints, build, dist, out, public, .next, .nuxt, .svelte - kit, .angular, .astro, .vite, .cache, .parcel - cache, .turbo, coverage, .coverage, .nyc_output, .gradle, .idea, .vscode, .docusaurus, .vercel, .serverless, .terraform, .mvn, .tox, target, bin, obj

貢獻

這是一個專注於智能代碼分塊和搜索的研究項目。歡迎您嘗試以下方面：

• 不同的分塊策略。
• 替代的嵌入模型。
• 增強的元數據提取。
• 性能優化。

🔧 技術細節

本系統使用Google的EmbeddingGemma模型和先進的多語言分塊技術，通過MCP（模型上下文協議）與Claude Code集成，為15種文件擴展名和9種以上編程語言提供語義搜索功能。在分塊過程中，針對不同的編程語言採用了不同的解析策略，如Python使用AST解析，其他語言使用Tree - sitter解析，以提取更有語義信息的代碼塊。在搜索過程中，使用FAISS進行高效的相似度搜索，同時支持增量索引，提高了索引和搜索的效率。

📄 許可證

本項目採用GNU通用公共許可證v3.0（GPL - 3.0）。詳情請參閱LICENSE文件。

靈感來源

本項目受到[zilliztech/claude - context](https://github.com/zilliztech/claude - context)的啟發。我將相關概念改編為Python實現，並將所有嵌入操作放在本地進行。

🚧 測試版發佈

• 核心功能已正常工作。
• 已在Mac/Linux上測試安裝。
• 基準測試即將推出。
• 請報告問題！