codesearch (Flupkede)

代码搜索

   ](https://github.com/flupkede/codesearch/releases) ](https://github.com/flupkede/codesearch/stargazers)

AI代理的多仓库语义代码搜索——一个具有向量+BM25混合检索、符号导航和跨仓库编排的Rust MCP服务器。完全本地，完全离线，没有GPU，没有Docker。

codesearch通过5个统一的MCP工具为AI代理（OpenCode、Claude Code、Cursor和任何MCP客户端）提供了深入的代码库理解。索引一次，同时在多个存储库中进行语义搜索。

为什么要进行代码搜索？

• 多回购服务模式：使用跨回购RRF排名在存储库组之间展开查询
• 混合检索：向量嵌入+BM25全文搜索与互序融合
• 符号导航：跳转到定义、查找用法、跟踪导入和依赖项——在同一个工具中
• AST感知分块：9种语言的树型解析——块与函数/类对齐，而不是任意的行范围
• 代币高效：默认情况下返回元数据；代理仅在需要时通过以下方式获取完整代码 get_chunk
• 占地面积轻：磁盘上有数百MB，仅在CPU上运行，没有运行时模型下载（在企业代理后面工作）
• 单仓库零配置: codesearch index && codesearch mcp --完成了

与此相比如何？

MCP代码搜索生态系统在2025年底/2026年初迅速发展，许多项目共享相同的基线堆栈（Rust+树保姆+BM25+嵌入+MCP）。codesearch的重点是：

同一利基市场中的其他项目可能会在调用图遍历、抛光的独立CLI或内存/知识图功能方面做得更深入。codesearch有意地缩小了范围——它选择了“轻量级、多仓库、MCP原生、完全离线”，并保持在那个通道上。

建筑

graph TB
    Agent[AI Agent / MCP Client] -->|MCP stdio or HTTP| Router{MCP Router}

    Router --> Search[search tool]
    Router --> Find[find tool]
    Router --> Explore[explore tool]
    Router --> GetChunk[get_chunk tool]
    Router --> FindImpact[find_impact tool]
    Router --> Status[status tool]

    Search -->|mode=semantic| Semantic[Vector ANN + BM25 + RRF Fusion]
    Search -->|mode=literal| Literal[Tantivy FTS / Regex]

    Find -->|definition/usages| SymbolIndex[Symbol Index]
    Find -->|imports/dependents| DepGraph[Dependency Graph]

    Explore -->|outline| TreeSitter[Tree-sitter AST]
    Explore -->|similar| Semantic

    Semantic --> Arroy[arroy ANN vectors]
    Semantic --> Tantivy[Tantivy BM25]
    Arroy --> LMDB[(LMDB)]
    Tantivy --> TantivyIdx[(Tantivy Index)]

    GetChunk --> LMDB

    FindImpact -->|C# symbols| CSharpHelper[scip-csharp helper]
    CSharpHelper -->|SCIP index| ScipLMDB[(LMDB scip_symbols)]

    subgraph "Serve Mode (multi-repo)"
        ServeRouter[HTTP Router] -->|project/group routing| Repo1[Repo A]
        ServeRouter --> Repo2[Repo B]
        ServeRouter --> RepoN[Repo N]
    end

    Router -->|client mode| ServeRouter

快速开始

安装

从下载预构建的二进制文件 发布:

或者从源代码构建：

git clone https://github.com/flupkede/codesearch.git
cd codesearch
cargo build --release

为存储库建立索引

# Register and index the current repo (adds to ~/.codesearch/repos.json)
codesearch index add

# Register and index a repo from outside the repo folder
codesearch index add /path/to/my-project

# Incremental update (only changed files)
codesearch index /path/to/my-project

# Full rebuild
codesearch index /path/to/my-project --force

# Remove a repo
codesearch index rm /path/to/my-project

# List registered repos
codesearch index list

codesearch index add 旨在从您要注册的仓库内部运行。 如果你从其他地方启动它，请明确传递repo路径。

首次索引需要2-5分钟。后续运行是递增的（10-30秒）。分支开关触发自动重新索引。

MCP配置

codesearch通过MCP连接到AI代理。两种模式：

本地/单一代表

代理人产卵 codesearch mcp 作为一个子流程。它会自动检测最近的索引并启动文件监视器。

OpenCode — ~/.config/opencode/config.json:

{
  "mcp": {
    "codesearch": {
      "type": "local",
      "command": ["codesearch", "mcp"],
      "enabled": true
    }
  }
}

克劳德代码 — ~/.config/claude-code/config.json:

{
  "mcpServers": {
    "codesearch": {
      "command": "codesearch",
      "args": ["mcp"]
    }
  }
}

克劳德桌面版 — claude_desktop_config.json:

{
  "mcpServers": {
    "codesearch": {
      "command": "codesearch",
      "args": ["mcp"]
    }
  }
}

服务/多重回购

先启动服务器，然后连接您的代理。服务器使用TUI仪表板、懒惰的文件系统监视器和空闲驱逐来管理所有注册的存储库。

# Start the server (default port 39725)
codesearch serve

OpenCode --通过HTTP连接：

{
  "mcp": {
    "codesearch": {
      "type": "remote",
      "url": "http://127.0.0.1:39725/mcp",
      "enabled": true
    }
  }
}

克劳德代码/克劳德桌面 --通过强制服务连接 --mode client:

{
  "mcpServers": {
    "codesearch": {
      "command": "codesearch",
      "args": ["mcp", "--mode", "client"]
    }
  }
}

注： 在多回购模式下，代理必须指定 project 或 group 在工具调用中。 status 总是在没有范围的情况下工作。 get_chunk 当chunk_id在存储库中唯一时自动路由；如果不明确，则返回候选者并要求 project.

MCP工具参考

search --代码搜索

语义模式 结合向量相似度（fastembed）+BM25词汇评分+精确标识符增强，与RRF融合。最适合概念查询和混合自然语言+符号搜索。

文字模式 使用Tantivy FTS。使用 regex=true 用于带标点符号的图案(foo::bar, Vec).使用 phrase=true 用于多词精确匹配。

find --符号导航

explore --文件探索

大纲 返回文件中的所有顶级符号（种类、签名、行范围）。 相似 查找与给定chunk_id语义相关的块。

get_chunk --读取代码

在多仓库模式下：当chunk_id唯一时自动路由；当不明确时返回候选人列表。

find_impact --符号参考影响

通过每种语言的语义分析，以文件/行精度查找所有调用点和对符号的引用。目前支持 C （通过捆绑 scip-csharp 助手）。

返回引用列表 file, start_line, end_line，以及 kind （例如。 "call", "definition").暴露 index_age_seconds 因此，代理人可以推断出陈旧性。

注： 需要 -with-csharp 发布变体或单独安装 scip-csharp 帮手。看 C#语义搜索.

status --索引信息

服务模式（多代表）

对于同时跨多个存储库工作：

codesearch serve

这将启动一个后台HTTP服务器：

• TUI仪表板 （ratatui）显示仓库状态、CPU使用率、活动会话
• 懒惰的文件系统观察者 --在每个仓库的第一次查询时激活
• 闲置驱逐 （30分钟）--从内存中卸载未使用的存储库
• 会话跟踪 通过MCP保持活力

存储库注册

repo通过以下方式注册 codesearch index add:

# Register a repo (creates index + adds to ~/.codesearch/repos.json)
codesearch index add /path/to/my-project --alias my-project

# Remove a repo
codesearch index rm /path/to/my-project

# List registered repos
codesearch index list

服务阅读 ~/.codesearch/repos.json 启动时，管理所有已注册的存储库。

群组

组允许您在相关存储库中搜索：

codesearch groups add my-group repo1 repo2 repo3
codesearch groups list

然后在MCP工具中： group="my-group" 将查询扇出到组中的所有repo。

MCP连接模式

这 codesearch mcp 命令支持三种模式：

codesearch mcp --mode client  # force serve connection

服务端点位于 /mcp （流式HTTP传输）。

CLI参考

配置

环境变量

.codesearchignore

放在repo根目录中。Gitignore语法。从索引中排除路径：

# Vendored code
vendor/
node_modules/
# Generated files
*.generated.cs
**/migrations/**

repos.json

位于 ~/.codesearch/repos.json.由管理 codesearch index add/rm。包含回购别名→ 路径和组定义。看 服务模式.

C#语义搜索

所有C#特定的设置、操作、安装和测试都存在于 README_CSharp.md.

如果你不使用C#repos，你可以完全跳过它。

支持的语言

树保姆AST感知组块：

所有其他文本文件都使用基于行的分块作为回退。

核心技术

发展

# Build
cargo build

# Run tests
cargo test

# Check + lint
cargo clippy --all-targets -- -D warnings

# Format
cargo fmt --all

许可证

阿帕奇-2.0

致谢