AI导哈

代码库语义搜索工具

一款无需API密钥、完全本地运行的代码库索引与语义搜索工具，支持关键词搜索、语义搜索和混合搜索，适用于开发者快速查询和理解代码库。

  • by joinQuantish
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 joinQuantish/codebase-rag

使用说明

代码库碎片

索引任何GitHub存储库并立即搜索。不需要API密钥。在CPU上100%本地运行。

公开MCP服务器，以便Claude Code、Cursor或任何LLM客户端可以在语义上搜索您的代码库。

GitHub Repo → Clone → Chunk → Embed (local) → SQLite Index → MCP Server → LLM

快速开始

# Install
git clone https://github.com/joinQuantish/codebase-rag
cd codebase-rag
bun install

# Index any repo (auto-embeds, no API key needed!)
bun run src/cli.ts index https://github.com/your-org/your-repo

# Search
bun run src/cli.ts search "place order"                         # keyword (~2ms)
bun run src/cli.ts vsearch "how does authentication work"       # semantic (~28ms)
bun run src/cli.ts query "wallet encryption and key management" # hybrid (best)

# Start MCP server for Claude Code / Cursor
bun run src/cli.ts serve

就这样 没有OpenAI密钥，没有GPU，没有外部服务。

运作原理

索引管道

  1. Git同步 --克隆或提取仓库，通过SHA256哈希检测更改的文件
  2. 文件过滤器 --选择代码文件（TS、Python、Rust、Go等），跳过node_modules/dist/binaries
  3. 代码分块器 --在函数/类边界上拆分文件，回退到具有重叠的60行窗口
  4. FTS5指数 --每个块都进入SQLite全文搜索，波特词干+BM25排名
  5. 矢量嵌入 --通过全MiniLM-L6-v2在本地嵌入块（22MB ONNX型号，在CPU上运行）

搜索模式

模式 命令 速度 最适合
关键字 search ~2ms 函数名称，精确术语
语义 vsearch ~28ms 概念性问题（“X是如何工作的”）
混合动力 query ~30ms 最佳整体精度

这三个都是开箱即用的，不需要API密钥。

嵌入

违约： 全迷你LM-L6-v2 通过 @huggingface/transformers （CPU上的ONNX运行时）

  • 384维向量
  • ~22MB量化模型（首次运行时自动下载）
  • 每个块嵌入约4ms
  • 缓存在 ~/.cache/huggingface/

可选地切换到OpenAI以获得更高的质量：set OPENAI_API_KEY 有人是。

MCP服务器

两种模式： 标准 （当地）和 超文本传输协议 （远程/共享）。

选项A：本地（stdio）

用于个人使用Claude Code或Cursor。增添 ~/.claude.json:

{
  "mcpServers": {
    "codebase": {
      "command": "bun",
      "args": ["run", "/path/to/codebase-rag/src/server.ts"],
      "env": {
        "CODEBASE_RAG_DATA": "/path/to/codebase-rag/data"
      }
    }
  }
}

选项B:HTTP（远程）

与团队分享。启动服务器，任何人都可以连接：

# Start HTTP server
bun run src/cli.ts serve --http --port=3100

从克劳德代码连接：

{
  "mcpServers": {
    "codebase": {
      "type": "streamable-http",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

终点：

路径 方法 描述
/mcp POST/GET/DELETE MCP协议（流式HTTP）
/health GET 健康检查+索引统计数据（JSON）
/ GET 服务器信息+连接说明

暴露的工具

工具 说明
search 快速关键字搜索（FTS5+BM25）
semantic_search 向量相似性搜索
query 混合搜索（关键字+语义，RRF融合）-- 推荐
stats 指数统计

建筑

src/
  cli.ts       — CLI entry point
  sync.ts      — Git clone/pull + change detection
  chunker.ts   — Code-aware file splitting
  indexer.ts    — SQLite FTS5 + vector storage
  embedder.ts  — Local embeddings (HuggingFace) or OpenAI
  search.ts    — Search engine (keyword, semantic, hybrid)
  server.ts    — MCP server (stdio + HTTP transport)

支持的语言

TypeScript、JavaScript、Python、Rust、Go、Java、Kotlin、C/C++、Ruby、PHP、Swift、C#、Solidity、SQL、Markdown、YAML、TOML、Shell、GraphQL、Protobuf、Terraform

重新索引

跑 index 同样，它只对内容哈希值发生变化的文件重新索引：

bun run src/cli.ts index https://github.com/your-org/your-repo
# ✅ Indexed 3 files, skipped 97 unchanged

环境变量

变量 必填 描述
OPENAI_API_KEY 否 可选：使用OpenAI嵌入而不是本地嵌入
EMBEDDING_MODEL 否 自定义HuggingFace模型（默认值： Xenova/all-MiniLM-L6-v2)
EMBEDDING_BASE_URL 否 自定义OpenAI兼容端点（Ollama，vLLM）
CODEBASE_RAG_DATA 否 数据目录（默认： ./data)

自动同步（可选）

设置cron以按计划重新索引：

# Re-index every 15 minutes
*/15 * * * * cd /path/to/codebase-rag && bun run src/cli.ts index https://github.com/your-org/your-repo

或者使用GitHub webhook在推送时触发。

堆栈

  • 运行时：Bun
  • 数据库：带FTS5的SQLite（bun:SQLite）
  • 嵌入：HuggingFace Transformers.js（ONNX、CPU、本地）
  • 主控程序：@modelcontextprotocol/sdk（stdio传输）
  • 零外部基础设施 -单个SQLite文件，没有API密钥，没有GPU，没有Postgres/Pinecone

相关 MCP