Code Sage

一款高性能的MCP（模型上下文协议）服务器，用于语义代码搜索，采用Rust编写。

特性

• 混合搜索：结合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提升性能：高效内存使用和快速处理

安装

预备条件

• 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（云）

{
  以下省略...
}

Ollama（实验性）

{
  以下省略...
}

提供商设置

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部分添加可选参数：

{
  以下省略...
}

可用的MCP工具

1. analyze_code

通过分析函数、类和方法创建可搜索的索引：

{
  以下省略...
}

参数：

• 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

示例 - 添加自定义扩展名：

{
  以下省略...
}

返回值：带有成功/错误消息的JSON

2. find_code

使用自然语言问题查找代码：

{
  以下省略...
}

返回值：带有搜索结果和格式化代码片段的JSON

3. delete_index

删除代码库的搜索索引：

{
  以下省略...
}

返回值：带有确认消息的JSON

4. check_status

检查代码分析是否完成、正在进行或失败：

{
  以下省略...
}

返回值：带有状态（已分析、正在分析百分比、失败或未找到）的JSON

进度跟踪（更新于2025-11-10）： 分析进度分为细粒度阶段，以便准确反馈：

• 0-30%：文件处理（扫描和分块）
• 30-60%：嵌入生成（按批次更新）
• 60-85%：向量数据库存储
• 85-95%：BM25全文索引
• 95-100%：元数据存储

这确保了平滑的进度更新，没有突然跳跃，提供了对分析过程更好的可见性。

工作原理

1. 索引流水线

代码文件
    ↓
AST解析（tree-sitter）
    ↓
语义块（函数、类）
    ↓
嵌入（OpenAI/Ollama）
    ↓
存储（USearch + Tantivy + Sled）

2. 混合搜索

查询
    ↓
    ├─→ 向量搜索（USearch）→ 前50个结果
    │
    └─→ BM25搜索（Tantivy）→ 前50个结果
    
    ↓
RRF重排序（合并，k=100）
    ↓
最终结果（前K个）

RRF（倒数排名融合）： 混合搜索使用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

启发与致谢

该项目受到启发于：

• 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构建 🦀