内容
# 语义搜索 MCP
> 面向 AI 编程代理的语义代码搜索 MCP 服务器。本地嵌入，无需 API 密钥。
[](https://www.npmjs.com/package/semantic-search-mcp)
[](https://nodejs.org)
AI 编程代理（例如 opencode、Claude、Cursor）可以进行精确的单词搜索，但 `semantic-search-mcp` 允许它们**按含义查找代码**。询问“我们在哪里处理身份验证？”并获得 `config/auth.php`、`AuthController.php`、`login.blade.php` 的返回结果 - 即使单词“处理”未出现。
**技术支持：** [`bge-small-en-v1.5`](https://huggingface.co/Xenova/bge-small-en-v1.5) 通过 ONNX 运行时。所有操作**本地运行**，数据不会离开您的机器。80MB，384 维，针对检索进行了优化。
## 快速入门
### 1. 安装
```bash
npm install -g semantic-search-mcp
```
或在不安装的情况下运行：
```bash
npx semantic-search-mcp
```
### 2. 连接到您的 AI 代理
**opencode** - 添加到 `opencode.jsonc`：
```jsonc
{
"mcp": {
"semantic-search": {
"type": "local",
"command": ["npx", "-y", "semantic-search-mcp"],
"enabled": true
}
}
}
```
**Claude Desktop** - 添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"semantic-search": {
"command": "npx",
"args": ["-y", "semantic-search-mcp"]
}
}
}
```
### 3. 完成！
重启您的 AI 代理。第一次搜索将索引您的代码库（约 5-15 分钟，具体取决于大小）。后续搜索立即完成（已缓存）。
## 配置
⚡ **交互式设置：** `semantic-search-mcp config` - 用于扩展、模型、阈值的 TUI 向导。
或手动在项目根目录中创建 `.semantic-search.json`：
```json
{
"extensions": [".php", ".js", ".jsx", ".ts", ".tsx"],
"skipDirs": ["node_modules", "vendor", ".git", "dist"],
"model": "Xenova/bge-small-en-v1.5",
"chunkThreshold": 300,
"maxChunksPerFile": 4
}
```
或使用环境变量：
```bash
export SEMANTIC_SEARCH_EXTENSIONS=".php,.js,.jsx,.ts,.tsx"
export SEMANTIC_SEARCH_SKIPDIRS="node_modules,vendor"
export SEMANTIC_SEARCH_MODEL="Xenova/bge-small-en-v1.5"
```
### 所有配置选项
| 键 | 默认值 | 描述 |
| --- | --- | --- |
| `extensions` | `[".php", ".js", ".jsx", ".ts", ".tsx", ".vue", ".py", ".rb", ".go", ".rs", ".java", ".cs", ...]` | 要索引的文件扩展名 |
| `skipDirs` | `["node_modules", "vendor", ".git", "dist", "build", ...]` | 要跳过的文件夹 |
| `model` | `"Xenova/bge-small-en-v1.5"` | HuggingFace 模型（较小=更快，较大=更准确） |
| `cacheDir` | `".opencode/mcp-cache/semantic-search"` | 存储索引的位置（相对于工作区） |
| `chunkThreshold` | `300` | 文件被分成块的行数阈值 |
| `maxChunksPerFile` | `4` | 大文件最大块数 |
| `maxResults` | `50` | 最大搜索结果数 |
| `defaultLimit` | `10` | 默认结果数 |
### 替代模型
| 模型 | 大小 | 维度 | 速度 | 质量 |
| --- | --- | --- | --- | --- |
| `Xenova/bge-small-en-v1.5` | 80MB | 384 | 快 | 最佳检索 |
| `Xenova/all-MiniLM-L6-v2` | 80MB | 384 | 快 | 良好 |
| `Xenova/all-mpnet-base-v2` | 420MB | 768 | 中等 | 更好 |
| `Xenova/multi-qa-MiniLM-L6-cos-v1` | 80MB | 384 | 快 | 更适合问答 |
## CLI 命令
```bash
# 启动 MCP 服务器（默认 - 供 AI 代理连接）
semantic-search-mcp
# 交互式 TUI 配置向导
semantic-search-mcp config
# 打印 AI 代理的配置片段
semantic-search-mcp init
# 预建索引（可选，首次使用时自动进行）
semantic-search-mcp index
# 清除索引缓存
semantic-search-mcp clean
# 帮助
semantic-search-mcp --help
```
## 工作原理
1. **遍历工作区** - 查找与配置的扩展名匹配的所有代码文件
2. **分割文件** - 将大文件分成可管理的块（默认：每块 300 行，最多 4 块/文件）
3. **使用 ONNX 嵌入** - 在本地运行每个块通过 [`bge-small-en-v1.5`](https://huggingface.co/Xenova/bge-small-en-v1.5)（384 维向量）
4. **缓存** - 将索引保存到磁盘以实现即时重启
5. **搜索** - 嵌入查询，计算与所有块的余弦相似度，返回最佳匹配
所有操作都在您的机器上运行。无需 API 调用，无需遥测，无数据离开您的计算机。
## 评分解释
| 分数 | 含义 |
| --- | --- |
| 0.7+ | 非常强的匹配 - 几乎可以肯定是您要找的 |
| 0.5-0.7 | 强匹配 - 可能相关 |
| 0.3-0.5 | 中度匹配 - 间接相关 |
| <0.3 | 弱匹配 - 可能是噪音 |
## 支持的语言
默认配置索引具有以下扩展名的文件：
`.php`, `.js`, `.jsx`, `.ts`, `.tsx`, `.vue`, `.py`, `.rb`, `.go`, `.rs`, `.java`, `.cs`, `.swift`, `.kt`, `.css`, `.scss`, `.less`, `.blade.php`, `.mjs`, `.cjs`
通过 `.semantic-search.json` 或 `SEMANTIC_SEARCH_EXTENSIONS` 环境变量自定义。
## 要求
- Node.js >= 18.0.0
- ~80MB 磁盘用于嵌入模型（首次运行）
- ~50-100MB 磁盘用于索引缓存（取决于项目大小）
## 许可证
MIT
## 相关
- [Cursor 的语义搜索博客](https://cursor.com/blog/semsearch) - 语义搜索准确率提高 12.5%
- [sturdy-dev/semantic-code-search](https://github.com/sturdy-dev/semantic-code-search) - Python CLI，每个函数嵌入
- [@xenova/transformers](https://github.com/xenova/transformers) - JavaScript 中的 ONNX 模型
