🚀 本地版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["更改检测器
(Merkle DAG)"]
C --> E["多语言分块器"]
E --> F["代码块"]
C --> G["代码嵌入器
(EmbeddingGemma)"]
G --> H["嵌入向量"]
C --> I["代码索引管理器
(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上，下载可能需要接受条款和/或进行认证。
- 访问模型页面并接受任何条款：
- https://huggingface.co/google/embeddinggemma - 300m
- 通过以下方式之一进行认证：
- CLI（推荐）：
uv run huggingface - cli login # 粘贴您从https://huggingface.co/settings/tokens获取的令牌 - 环境变量：
export HUGGING_FACE_HUB_TOKEN = hf_XXXXXXXXXXXXXXXXXXXXXXXX
- CLI（推荐）：
首次成功下载后，我们将模型缓存在~/.claude_code_search/models下，并优先进行离线加载以提高速度和可靠性。
支持的语言和文件扩展名
完全支持（15种文件扩展名，9种以上编程语言）：
| 语言 | 文件扩展名 |
|---|---|
| Python | .py |
| JavaScript | .js, .jsx |
| TypeScript | .ts, .tsx |
| Java | .java |
| Go | .go |
| Rust | .rs |
| C | .c |
| C++ | .cpp, .cc, .cxx, .c++ |
| C# | .cs |
| Svelte | .svelte |
总计：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）。
故障排除
常见问题
- 导入错误：确保使用
uv sync安装了所有依赖项。 - 模型下载失败：检查网络连接和磁盘空间。
- 内存问题：在索引脚本中减小批量大小。
- 没有搜索结果：验证代码库是否已成功索引。
- 未使用FAISS GPU：确保
nvidia - smi可用且CUDA驱动已安装；重新运行安装程序以选择faiss - gpu - cu12/cu11。 - 强制离线：我们会自动检测本地缓存并优先进行离线加载；您也可以设置
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上测试安装。
- 基准测试即将推出。
- 请报告问题！