AI导哈

代码库索引服务

基于向量相似度的代码库索引MCP服务，支持OpenAI兼容的embeddings和Torch本地向量存储，适用于代码搜索和索引管理。

  • by yuemingruoan
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 yuemingruoan/codebase-index-mcp

使用说明

代码库索引mcp

英语 | 中文

英语

基于向量相似性的代码库索引MCP服务器。使用OpenAI兼容的嵌入和基于Torch的本地向量存储，并具有CUDA/MPS加速功能。

特性

  • MCP工具： init, search, status, update
  • 与OpenAI API兼容的嵌入(base_url, api_key, model)
  • 基于Torch的本地存储（CUDA/MPS可用时，CPU回退）
  • Git只跟踪文件；已筛选二进制文件
  • 基于行的重叠组块
  • 增量刷新打开 search （可选）
  • 可配置的设备、搜索模式和最大VRAM预算

需求

  • Python>=3.12
  • Git
  • OpenAI兼容的嵌入端点
  • Torch（CPU或GPU构建）

安装

python3 -m pip install -e .

CLI使用情况

初始化回购索引：

code-index init /abs/path/to/repo \
  --persist-dir /abs/path/to/persist \
  --base-url https://api.openai.com \
  --api-key $OPENAI_API_KEY \
  --model text-embedding-3-small \
  --device auto \
  --search-mode exact \
  --metric ip \
  --approx-sample-rate 0.2 \
  --max-vram-mb 2048

搜索（默认增量刷新）：

code-index search /abs/path/to/repo "query text" --persist-dir /abs/path/to/persist

跳过刷新：

code-index search /abs/path/to/repo "query text" --persist-dir /abs/path/to/persist --no-refresh

覆盖一个查询的设备/搜索设置：

code-index search /abs/path/to/repo "query text" \
  --persist-dir /abs/path/to/persist \
  --device mps \
  --search-mode approx \
  --approx-sample-rate 0.3 \
  --max-vram-mb 1024

状态：

code-index status /abs/path/to/repo --persist-dir /abs/path/to/persist

更新嵌入配置（完全重建）：

code-index update /abs/path/to/repo \
  --persist-dir /abs/path/to/persist \
  --base-url https://api.openai.com \
  --api-key $OPENAI_API_KEY \
  --model text-embedding-3-small \
  --device auto \
  --search-mode exact \
  --metric ip \
  --approx-sample-rate 0.2 \
  --max-vram-mb 2048

您还可以设置 CODE_INDEX_PERSIST_DIR 避免超车 --persist-dir 每次。 集 CODE_INDEX_MAX_VRAM_MB 定义搜索/索引的默认VRAM预算。

笔记：

  • --device auto 首先选择CUDA，然后选择MPS，然后选择CPU；如果不可用，显式CUDA/MPS将回退到CPU。
  • --search-mode approx 基于以下内容对候选对象进行采样 --approx-sample-rate （越低越快，召回率越低）。
  • --metric 支持 ip （默认）或 l2.

MCP服务器

启动MCP服务器：

code-index serve --persist-dir /abs/path/to/persist

工具：

  • init：创建新索引
  • search：语义搜索（返回相对路径+行范围）
  • status：当前索引信息
  • update：更新配置并重建索引

持久性布局

/persist
  server.json
  <repo_hash>/
    config.json
    vectors/
      embeddings.pt
      meta.json

测试

python3 -m pytest -q

故障排除

  • NOT_GIT_REPO：确保 repo_path 位于git存储库中
  • NOT_INITIALIZED：run code-index init 第一
  • EMBEDDING_ERROR：检查 base_url, api_key，以及网络访问
  • STORAGE_ERROR：确保 torch 已安装，矢量目录可写

中文

使用向量相似度驱动的代码库索引 MCP 服务，基于 OpenAI 兼容的 embedding，并提供支持 CUDA/MPS 加速的 Torch 本地向量存储。

功能

  • MCP 工具：init、search、status、update
  • OpenAI API兼容 嵌入(base_url、api_key、model）
  • Torch 本地存储（可用时启用 CUDA/MPS，加速不可用时回退到 CPU）
  • 仅索引 Git 跟踪文件，过滤二进制
  • 按行切分并支持重叠
  • search 可选增量刷新
  • 支持设备、检索模式与显存预算配置

环境要求

  • Python>=3.12
  • Git
  • OpenAI 兼容的 embedding 接口
  • Torch（CPU 或 GPU 版本）

安装

python3 -m pip install -e .

CLI 用法

初始化仓库索引：

code-index init /abs/path/to/repo \
  --persist-dir /abs/path/to/persist \
  --base-url https://api.openai.com \
  --api-key $OPENAI_API_KEY \
  --model text-embedding-3-small \
  --device auto \
  --search-mode exact \
  --metric ip \
  --approx-sample-rate 0.2 \
  --max-vram-mb 2048

搜索（默认会做增量刷新）：

code-index search /abs/path/to/repo "query text" --persist-dir /abs/path/to/persist

跳过刷新：

code-index search /abs/path/to/repo "query text" --persist-dir /abs/path/to/persist --no-refresh

单次查询覆盖设备/检索参数：

code-index search /abs/path/to/repo "query text" \
  --persist-dir /abs/path/to/persist \
  --device mps \
  --search-mode approx \
  --approx-sample-rate 0.3 \
  --max-vram-mb 1024

状态查看：

code-index status /abs/path/to/repo --persist-dir /abs/path/to/persist

更新 embedding 配置（全量重建）：

code-index update /abs/path/to/repo \
  --persist-dir /abs/path/to/persist \
  --base-url https://api.openai.com \
  --api-key $OPENAI_API_KEY \
  --model text-embedding-3-small \
  --device auto \
  --search-mode exact \
  --metric ip \
  --approx-sample-rate 0.2 \
  --max-vram-mb 2048

可通过 CODE_INDEX_PERSIST_DIR 避免每次传入 --persist-dir。 通过 CODE_INDEX_MAX_VRAM_MB 设置默认显存预算。

说明：

  • --device auto 优先选 CUDA，其次 MPS，再回退 CPU；显式 CUDA/MPS 不可用时会回退 CPU。
  • --search-mode approx 通过 --approx-sample-rate 采样候选（值越小越快但召回更低）。
  • --metric 支持 ip（默认）或 l2。

MCP服务器

启动 MCP 服务：

code-index serve --persist-dir /abs/path/to/persist

工具：

  • init：创建新索引
  • search：语义检索（返回相对路径与行号范围）
  • status：索引状态
  • update：更新配置并重建索引

持久化目录结构

/persist
  server.json
  <repo_hash>/
    config.json
    vectors/
      embeddings.pt
      meta.json

测试

python3 -m pytest -q

故障排查

  • NOT_GIT_REPO：确保 repo_path 在 git 仓库内
  • NOT_INITIALIZED：先执行 code-index init
  • EMBEDDING_ERROR：检查 base_url、api_key 与网络访问
  • STORAGE_ERROR：确认已安装 torch 且向量目录可写

相关 MCP