语义代码搜索服务器

语义搜索MCP服务器

使用本地嵌入提供语义代码搜索的MCP服务器。使用“身份验证中间件”或“数据库连接池”等自然语言查询搜索您的代码库。

特性

• 混合搜索：使用往复式秩融合将向量相似性（Jina代码嵌入）与FTS5关键字匹配相结合
• 165+种语言：Python、TypeScript、JavaScript、Go、Rust、Java、C/C++、Ruby、PHP等的树型解析
• 增量索引：文件监视器自动检测添加、修改和删除
• 尊敬的吉吉尼奥尔：尊重您的项目 .gitignore 文件（包括嵌套文件）
• 自动初始化：服务器启动时后台的模型加载和代码库索引
• 零外部API：使用FastEmbed在本地生成的所有嵌入

安装

uv tool install semantic-search-mcp

或者使用pip：

pip install semantic-search-mcp

或者直接运行而不安装：

uvx semantic-search-mcp

快速开始

添加到克劳德代码

选项A：项目级配置（推荐）

安装后 uv tool install 或 pip install，创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "semantic-search": {
      "command": "semantic-search-mcp"
    }
  }
}

选项B:CLI

claude mcp add semantic-search -- semantic-search-mcp

选项C：不安装（临时）

如果您不想安装，请使用 uvx 在短暂的环境中运行：

{
  "mcpServers": {
    "semantic-search": {
      "command": "uvx",
      "args": ["semantic-search-mcp"]
    }
  }
}

使用

服务器在启动时自动初始化。

可用工具

运作原理

索引

启动时，服务器：

1. 扫描代码库以查找支持的文件类型
2. 使用Tree sitter将代码解析为语义块（函数、类、方法）
3. 使用Jina的代码嵌入模型为每个块生成嵌入
4. 将所有内容存储在具有矢量搜索支持的本地SQLite数据库中

文件监视

服务器实时监控您的代码库是否有更改：

更改被取消（默认为1秒）以批量快速修改。

什么被索引

包括：

• 具有代码扩展名的文件： .py, .js, .ts, .tsx, .jsx, .go, .rs, .java, .c, .cpp, .h, .rb, .php, .swift, .kt, .scala，以及更多

排除：

• 文件匹配 .gitignore 图案（全部 .gitignore 项目中的文件受到尊重）
• 常见的非代码目录： node_modules, __pycache__, .venv, build, dist, .git, vendor等等。
• 二进制文件和非代码文件类型

配置

环境变量：

演出

GPU加速

GPU加速会自动检测并在可用时使用：

模型

为了更快地索引（在质量权衡的情况下），您可以使用更轻的型号：

要使用替代模型，请执行以下操作：

export SEMANTIC_SEARCH_EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2"

注意：更改型号需要完全重新索引（删除 .semantic-search/ 目录）。

UniXcoder（实验）

微软UniXcoder 是一个在代码+AST+注释上预先训练的代码特定模型。它可以更好地理解代码结构的语义，但 明显较慢 （比Jina慢约20倍）。

安装 （需要额外的依赖关系）：

pip install semantic-search-mcp[unixcoder]

用途：

export SEMANTIC_SEARCH_EMBEDDING_MODEL="microsoft/unixcoder-base-nine"

何时使用UniXcoder：

• 您将搜索质量置于索引速度之上
• 你的代码库是中小型的
• 你有GPU加速（CUDA或苹果Silicon MPS）

何时避免使用UniXcoder：

• 大型代码库（10000+个文件）-索引需要几个小时
• 您需要快速的初始索引
• 在CPU上运行，无需GPU加速

Claude代码集成

技能和命令是 自动安装 当MCP服务器首次启动时：

• 技能 → ~/.claude/skills/ （AI自动发现）
• 命令 → ~/.claude/commands/ （用户可调用斜线命令）

要手动重新安装或更新，请执行以下操作：

semantic-search-mcp-install-skills

可用的Slash命令

需求

• Python 3.11+
• 约700MB磁盘用于嵌入模型（首次运行时下载，约150MB，采用INT8量化）
• ~ 1GB RAM用于嵌入模型

许可证

麻省理工学院