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