代码圣人
高性能 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 获取详细的架构文档。
关键设计决策：
- 纯语义混合搜索：结合关键字和语义搜索以获得更好的结果
- 嵌入式客户端服务器：一切都在本地运行，不需要矢量数据库服务器
- AST先退：可能时进行语义组块，需要时基于字符
- 性能生锈：高效的内存使用和快速的处理
安装
先决条件
- 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）
文件选择的工作原理:
- 扩展过滤：仅分析具有支持扩展名的文件（默认60多个）
- Gitignore尊重：自动尊重
.gitignore,.ignore，以及.git/info/exclude - 自定义扩展：使用
custom_extensions添加默认值之外的特定于项目的文件类型 - 隐藏文件：默认情况下跳过
默认支持的扩展 （总计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 🦀