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上测试安装。
• 基准测试即将推出。
• 请报告问题！