使用说明
Qdrant Gemini MCP服务器
MCP（模型上下文协议）服务器，用于使用Gemini嵌入搜索Qdrant中索引的文档。非常适合将技术文档搜索集成到AI助手中。
特性
- 🔍 语义搜索：使用Gemini强大的嵌入功能搜索索引文档
- 📚 多格式支持：索引PDF、Word（.docx）、Markdown、HTML和TXT文档
- 🚀 MCP集成：通过模型上下文协议公开搜索功能
- 🔄 增量索引：跳过已处理文档的智能索引
- 🎯 技术文档：针对技术文档进行了优化（适用于任何文档）
- 🏠 本地处理：文档文本提取在本地进行（只有嵌入需要互联网）
建筑
该项目由三个主要部分组成：
- 索引文档 (
index_pdfs.py)：从多种文档格式中提取文本，生成嵌入，并将其存储在Qdrant中 - 搜索 (
search_qdrant.py)：用于搜索索引文档的CLI工具 - MCP服务器 (
server.py)：通过MCP为AI助手提供搜索和索引功能
支持的文档格式
- PDF （.pdf）-可移植文档格式
- 字 （.docx）-微软Word文档
- 标记语言 （.md，.markdown）-markdown文件
- 超文本标记语言 （.html、.htm）-网页
- 文本 （.txt）-纯文本文件
先决条件
- Python 3.10或更高版本
- Qdrant实例（本地或云）
- Gemini API密钥
安装
1.克隆存储库
git clone https://github.com/EugenioSerrano/qdrant-gemini-mcp.git
cd qdrant-gemini-mcp
2.创建虚拟环境
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
3.安装依赖项
pip install -e .
使用测试工具进行开发：
pip install -e ".[dev]"
4.配置环境变量
复制示例环境文件并对其进行编辑：
cp .env.example .env
编辑 .env 并添加您的Gemini API密钥：
GEMINI_API_KEY=your_actual_api_key_here
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=proyecto-stm32
从以下位置获取Gemini API密钥：https://makersuite.google.com/app/apikey
5.启动Qdrant（如果在本地运行）
使用Docker：
docker run -p 6333:6333 qdrant/qdrant
用法
索引文档
索引目录中所有支持的文档（PDF、Word、Markdown、HTML、TXT）：
qdrant-gemini-index /path/to/documents/directory
强制重新索引（如果要更新现有文档，则很有用）：
qdrant-gemini-index /path/to/documents/directory --force
索引器将自动检测并处理目录中所有支持的文件格式。
从CLI搜索
qdrant-gemini-search "your search query here"
例子：
qdrant-gemini-search "STM32 clock configuration"
作为MCP服务器运行
MCP服务器可以在您的MCP客户端中配置（如Claude Desktop或VS Code）：
{
"mcpServers": {
"qdrant-gemini": {
"command": "python",
"args": [
"/home/eugenio/GitHubRepos/qdrant-gemini-mcp/src/qdrant_gemini_mcp/server.py"
],
"env": {
"GEMINI_API_KEY": "your_api_key",
"QDRANT_URL": "http://localhost:6333",
"QDRANT_COLLECTION": "proyecto-stm32"
}
}
}
}
或者使用已安装的脚本：
qdrant-gemini-server
VS代码MCP配置
添加到您的 ~/.config/Code/User/mcp.json:
{
"servers": {
"qdrant-gemini": {
"command": "python",
"args": [
"-m",
"qdrant_gemini_mcp.server"
],
"env": {
"GEMINI_API_KEY": "your_api_key_here",
"QDRANT_URL": "http://localhost:6333",
"QDRANT_COLLECTION": "proyecto-stm32"
},
"type": "stdio"
}
}
}
MCP工具
服务器公开以下MCP工具：
search-stm32-docs
使用语义搜索在索引文档中搜索。
参数：
query（字符串，必填）：搜索查询limit（整数，可选）：最大结果数（默认值：5）
退货：
- 相关文档块列表，包括：
- 得分（相关性）
- 文件名
- 块索引
- 文本内容
发展
项目结构
qdrant-gemini-mcp/
├── src/
│ └── qdrant_gemini_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server
│ ├── index_pdfs.py # PDF indexing
│ └── search_qdrant.py # Search CLI
├── tests/
│ └── test_server.py
├── .env # Your environment variables (not in git)
├── .env.example # Template for environment variables
├── pyproject.toml # Project configuration
├── requirements.txt # Dependencies
└── README.md
运行测试
pytest
覆盖范围：
pytest --cov=qdrant_gemini_mcp
运作原理
-
索引阶段:
- 阅读PDF并提取文本
- 文本被分割成重叠的块（1000个字符，200个重叠）
- 每个块都使用Gemini嵌入
text-embedding-004模型 - 嵌入内容与元数据（文件名、块索引、文本）一起存储在Qdrant中
-
搜索阶段:
- 使用相同的Gemini模型嵌入查询
- Qdrant执行余弦相似性搜索
- 返回前K个最相关的块
-
MCP集成:
- 服务器通过模型上下文协议公开搜索功能
- AI助手可以调用搜索工具
- 结果的格式便于使用
配置
环境变量
GEMINI_API_KEY：您的Google Gemini API密钥（必需）QDRANT_URL：Qdrant服务器URL（默认值：http://localhost:6333)QDRANT_COLLECTION：Qdrant中的集合名称（默认值：proyecto-stm32)
嵌入模型
该项目使用Gemini的 text-embedding-004 生成768维嵌入的模型。
分块策略
- 块大小：1000个字符
- 重叠：200个字符
- 这可确保跨块边界保留上下文
故障排除
“GEMINI_API_KEY未配置”
确保您已创建 .env 使用API密钥文件：
cp .env.example .env
# Edit .env and add your key
“集合为空”
先索引一些PDF：
qdrant-gemini-index /path/to/pdfs/
Qdrant连接错误
确保Qdrant正在运行：
docker ps | grep qdrant
如果没有运行，请启动它：
docker run -p 6333:6333 qdrant/qdrant
许可证
MIT许可证-有关详细信息，请参阅许可证文件
贡献
欢迎投稿！请随时提交拉取请求。
