Code Sage

代码圣人

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

特性

• 混合搜索：将BM25（基于关键字）+向量嵌入（语义）与RRF重新排序相结合
• 基于AST的分块：使用树状图将代码智能地拆分为语义单元（函数、类、方法）

- 基于角色的回退：对于AST解析失败或不可用的文件 - 全面的语言支持：开箱即用支持60多个文件扩展名

• 智能文件筛选:

- 自动.gitignore支持（尊重.gitignores、.ignore、.git/info/exclude） - 支持项目特定文件类型的自定义文件扩展名 - 无需配置-开箱即用

• 嵌入式存储：零外部依赖关系-所有数据都存储在本地

- USearch用于向量相似性搜索 - Tantivy for BM25全文搜索 - 用于元数据存储的雪橇

• 多个嵌入提供程序:

- 内置（默认） -集成了llama.cpp和nomic-embed-ext-v1.5，零外部依赖 - OpenAI（文本嵌入-3小，文本嵌入-3大） - Ollama（当地嵌入）

• 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、.screator、.plist（通过XML解析器）、.xcconfig（通过TOML解析器） - 安卓/Java：.xml（布局、清单）、.gradle、.properties - 构建系统：.cmake、.sbt、.make、Makefile、CMakeLists.txt - SHELL脚本：.sh、.bash、.zsh、.fish - 基于角色的回退：.ini、.txt、.rst以及通过添加的任何扩展名 custom_extensions

建筑

看 建筑.md 获取详细的架构文档。

关键设计决策：

1. 纯语义混合搜索：结合关键字和语义搜索以获得更好的结果
2. 嵌入式客户端服务器：一切都在本地运行，不需要矢量数据库服务器
3. AST先退：可能时进行语义组块，需要时基于字符
4. 性能生锈：高效的内存使用和快速的处理

安装

先决条件

• Rust 1.70+（2021年版）
• 内置提供程序不需要外部依赖

从源代码构建

git clone https://github.com/faxioman/code-sage.git
cd code-sage
cargo build --release

二进制文件将在 target/release/code-sage

平台特定构建

Code Sage会自动检测您平台的最佳GPU加速：

macOS（苹果硅）：

cargo build --release --features metal

配备NVIDIA GPU的Linux/Windows：

cargo build --release --features cuda

仅CPU（通用兼容性）：

cargo build --release --no-default-features

默认版本： 默认值 gpu-acceleration 该功能支持平台检测，但不包括任何特定的GPU后端。使用上述平台特定功能以获得最佳性能。

用法

零设置配置

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "code-sage": {
      "command": "/path/to/code-sage"
    }
  }
}

就是这样！Code Sage将：

• 自动使用内置的nomic-embed-ext-v1.5型号
• 存储数据于 ~/.code-sage/ （自动创建）
• 首次使用时下载模型（79MB）
• 在GPU加速可用时立即工作

高级配置

自定义数据目录

覆盖默认值 ~/.code-sage/ 位置：

{
  "mcpServers": {
    "code-sage": {
      "command": "/path/to/code-sage",
      "env": {
        "DATA_DIR": "/custom/path/to/data"
      }
    }
  }
}

OpenAI（基于云）

如果你更喜欢云嵌入而不是内置的本地模型：

{
  "mcpServers": {
    "code-sage": {
      "command": "/path/to/code-sage",
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "your-openai-api-key",
        "EMBEDDING_MODEL": "text-embedding-3-small"
      }
    }
  }
}

Ollama（当地）

如果你已经让Ollama跑步了：

{
  "mcpServers": {
    "code-sage": {
      "command": "/path/to/code-sage",
      "env": {
        "EMBEDDING_PROVIDER": "ollama",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "EMBEDDING_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

高级参数

可选参数可以添加到 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、.scale
• JS/TS变体：.mjs、.cjs
• 配置格式：.json、.yaml、.yml、.toml、.xml、.ini
• iOS/macOS：.xib、故事板、.plist、.xcconfig
• 安卓/Java：.gradle、.properties
• 构建系统：.cmake、.sbt、.make
• 网页/造型：.html、.htm、.css、scss、sass、.less
• SHELL脚本：.sh、.bash、.zsh、.fish
• .NET：.csproj、.sln、.config、.props、.targets
• 红宝石：.gemspec，.rake
• 灵药：.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（已分析、用%分析、失败或未找到）

运作原理

1.索引管道

Code Files
    ↓
AST Parsing (tree-sitter)
    ↓
Semantic Chunks (functions, classes)
    ↓
Embeddings (Builtin/OpenAI/Ollama)
    ↓
Storage (USearch + Tantivy + Sled)

2.混合搜索

Query
    ↓
    ├─→ Vector Search (USearch) → Top 50 results
    │
    └─→ BM25 Search (Tantivy) → Top 50 results
    
    ↓
RRF Reranking (merge with k=100)
    ↓
Final Results (Top K)

RRF（互惠等级融合）: 混合搜索使用RRF重新排序，根据向量和BM25搜索的排名位置而不是原始分数来平衡结果。这创建了一个公平平衡的最终排名，将语义相关性与关键字匹配相结合。 了解有关RRF的更多信息

RRF公式使用以下公式组合排名： score = 1/(k + rank) 哪里 k 是一个平滑参数（默认值：100，可通过以下方式配置 RRF_K 环境变量）。

开发设置

# Install dependencies
cargo build

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run

# Format code
cargo fmt

# Lint
cargo clippy

灵感与信用

该项目的灵感来源于：

• 克劳德语境 -原始TypeScript实现
• 围绕混合搜索和AST分块的设计决策
• MCP协议实现模式

主要区别：

• 用Rust编写以提高性能
• 嵌入式存储（无需Milvus/Qdrant服务器）
• 简化的架构
• 原生二进制文件（更易于部署）
• 更简单的处理程序响应（JSON字符串）

许可证

MIT许可证-请参阅 许可证

已知问题和限制

• 文件大小限制：每个文件1MB
• 扩展过滤：文件必须具有受支持的扩展名或通过添加 custom_extensions 待分析
• 存储：尚未压缩（正在处理中）
• 切换提供商：当改变具有不同维度的嵌入提供者时（例如从OpenAI 1536到LM Studio 768）， 删除 data/ 文件夹 在重新索引以避免维度不匹配错误之前

支持

• 问题：
• 讨论：

______________________________________________________________________

内置于❤️ 在Rust 🦀