嵌入查询服务器
MCP（模型上下文协议）服务器，用于查询由 喷枪嵌入器 项目。
特性
- 矢量搜索：使用语义搜索查询LanceDB矢量存储
- 图形搜索：使用GraphRAG构建的查询知识图，用于关系感知检索
- 自动模式：在可用时自动使用图形搜索，回退到矢量搜索
- 标准运输：与Claude Desktop、Cursor和Windsurf等MCP客户端兼容
安装
npm install
npm run build用法
必需参数
- `--index-path
` -embedder创建的embeddings目录的路径
--base-url-用于生成查询嵌入的LM Studio基本URL--model-嵌入模型名称（必须与用于索引的名称匹配）
可选参数
索引设置：
--table-name-LanceDB表名（默认：“嵌入”）--dimensions-嵌入尺寸（默认值：1024）
查询设置：
--top-k-要返回的结果数（默认值：10）
图形设置：
--enable-graph-启用图形搜索模式（默认：禁用以快速启动）--graph-threshold-图查询的相似性阈值（默认值：0.7）--random-walk-steps-图遍历步骤（默认值：100）--restart-prob-随机游走的重启概率（默认值：0.15）--preload-graph-启动时在后台开始构建图形（允许通过矢量搜索进行即时查询）
性能设置：
--verbose-启用详细日志记录以进行调试和性能监控
例子
基本矢量搜索（快速启动）：
node dist/index.js \
--index-path ./embeddings \
--base-url http://localhost:1234/v1 \
--model text-embedding-model \
--top-k 5使用图搜索（延迟加载-基于第一个查询构建）：
node dist/index.js \
--index-path ./embeddings \
--base-url http://localhost:1234/v1 \
--model text-embedding-model \
--enable-graph \
--top-k 5预加载背景图（最适合生产）：
node dist/index.js \
--index-path ./embeddings \
--base-url http://localhost:1234/v1 \
--model text-embedding-model \
--enable-graph \
--preload-graph \
--verbose对于大型索引（10K+文件），建议设置：
node dist/index.js \
--index-path ./embeddings \
--base-url http://localhost:1234/v1 \
--model text-embedding-model \
--enable-graph \
--preload-graph \
--top-k 10 \
--verboseMCP工具：查询索引
服务器公开了一个名为 query_index.
输入参数
query（字符串，必填）-搜索查询文本mode（枚举：“auto”|“vector”|“graph”，默认值：“自动”）-搜索模式
- auto：如果存在图形数据，则使用图形搜索，否则使用矢量搜索 - vector：仅通过LanceDB进行力矢量搜索 - graph：强制图形搜索（如果没有图形数据则出错）
输出
返回一个按分数排序的结果数组（最高者优先），每个结果包含：
text-块内容source-块来源的文件路径score-相似性得分（嵌入相似性）chunkIndex-块在源文件中的位置
项目结构
query-tool-server/
├── src/
│ ├── index.ts # Main entry point and MCP server setup
│ ├── lib/
│ │ └── graph-store.ts # GraphRAG data loading
│ └── types/
│ └── index.ts # TypeScript type definitions
├── dist/ # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md性能优化
服务器为处理大型索引（10K+文件）实现了多项优化：
1. 延迟加载（默认）
- 图构造被推迟到第一个查询
- 即使索引很大，服务器也会立即启动
- 第一个查询触发图形构建（10K文件可能需要30秒2分钟）
- 后续查询使用缓存的图
2. 并行批量加载
- 使用以下命令并行加载所有批处理文件
Promise.all() - 显著减少大型数据集的I/O时间
- 进度日志显示大型索引的加载状态
3. 自动回退
- 若查询在构建图时到达，它会自动回退到向量搜索
- 没有因图构建时间而导致的查询失败
- 警告已记录到控制台进行调试
4. 持久图形缓存
- 图形元数据在首次构建后缓存到磁盘
- 未来的优化可以序列化整个图结构
- 目前受限于Mastra GraphRAG系列化API
5. 背景预加载（可选）
- 使用
--preload-graph在启动时开始构建图形 - 服务器在构建过程中通过矢量搜索保持响应
- 图形准备就绪后可用，无阻塞
6. 工作线程支持
- 图形构建可以卸载到工作线程
- 使主线程对查询保持响应
- 目前处于实验阶段（见
graph-worker.ts)
运作原理
- 初创公司:
- 验证配置并加载LanceDB索引 - 加载图形元数据（但不是完整的图形-延迟加载） - 如果满足以下条件，则可选择启动背景图构建 --preload-graph 已设置 - 服务器立即就绪
- 查询处理：收到查询时：
- 使用指定的模型生成查询嵌入 - 根据以下内容选择搜索模式（矢量或图形） mode 参数 - 对于矢量搜索：直接查询LanceDB（总是很快） - 对于图形搜索： - 检查图形构建状态 - 如果正在构建，则返回到带有警告的矢量搜索 - 如果准备就绪，则使用图形进行关系感知搜索 - 如果空闲，则触发延迟构建，然后使用图 - 按分数对结果排序并返回前K
与嵌入器集成
此服务器旨在使用由创建的索引 嵌入器 项目：
- 使用embedder创建索引：
embedder -d ./my-repo -o ./embeddings --enable-graph- 启动指向该索引的查询服务器：
node dist/index.js \
--index-path ./embeddings \
--base-url http://localhost:1234/v1 \
--model text-embedding-model \
--enable-graph迁移指南：优化前后
之前（大索引启动缓慢）
- 服务器将在启动时构建整个图形
- 对于10K文件：服务器准备就绪可能需要2-5分钟
- 在此期间无法处理任何查询
- 即使不使用，也始终加载图形
之后（快速启动+延迟加载）
- 服务器立即启动（\<1秒）
- Graph基于第一个查询构建（或在后台使用
--preload-graph) - 矢量搜索始终可用
- 构建完成后，图形搜索变得可用
- 并行加载可将构建时间缩短约50-70%
行为变化
没有 --enable-graph:
- 无变化-仅矢量搜索，即时启动
随着 --enable-graph （默认-延迟加载）：
- 服务器立即启动
- 第一个图查询触发构建（大型索引为30s-2min）
- 构建过程中的查询会自动回退到向量搜索
- 后续查询使用缓存图
随着 --enable-graph --preload-graph （推荐用于生产）：
- 服务器立即启动
- 图形构建立即在后台开始
- 所有查询都使用向量搜索，直到图形准备就绪
- 没有用户面临的延迟，图表准备就绪后可用
错误处理
服务器在启动时进行验证：
- 索引路径存在
- LanceDB表存在
- 如果请求图形搜索，则图形数据必须可用
所有错误均以MCP错误响应的形式返回，并带有描述性消息。
发展
# Run in development mode
npm run dev -- --index-path ./embeddings --base-url http://localhost:1234/v1 --model text-embedding-model
# Build for production
npm run build
# Run built version
npm start -- --index-path ./embeddings --base-url http://localhost:1234/v1 --model text-embedding-model许可证
国际学生委员会