AI导哈

语义搜索服务

基于Qdrant和OpenAI嵌入的语义搜索服务，提供长期记忆和混合搜索功能。

  • by jtsang4
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 jtsang4/qdrant-mcp

使用说明

更好的qdrant mcp

MCP服务器用 fastmcp、OpenAI嵌入，以及 qdrant-client，在Qdrant之上提供长期记忆和语义搜索。

用户指南

特性

  • MCP服务器 建于 fastmcp
  • 混合搜索 在Qdrant中（密集的OpenAI嵌入+稀疏的BM25）
  • 中文支持 经街坝
  • 知识库工具 （从内存工具重命名以避免冲突）：
    • store-knowledge
    • store-knowledge-bulk
    • search-knowledge
    • get-knowledge-by-id
    • inspect-knowledge-base
    • delete-knowledge
  • 多个传输：stdio、SSE、可流式传输HTTP

需求

  • Python 3.12+
  • Qdrant可通过HTTP访问

快速入门（已发布的软件包）

该项目发布为 better-qdrant-mcp 包，因此您可以直接使用 uvx 无需克隆此仓库。

1.环境变量（所有运输都需要）

典型使用的最小环境值：

  • QDRANT_URL –默认为 http://localhost:6333
  • QDRANT_API_KEY –可选
  • COLLECTION_NAME –可选默认集合
  • OPENAI_API_KEY （或 OPENAPI_API_KEY)–必填
  • OPENAI_BASE_URL –可选
  • OPENAI_EMBEDDING_MODEL –默认为 text-embedding-3-small

高级/运输相关环境：

  • MCP_TRANSPORT – stdio | sse | streamable-http （默认值： stdio)
  • MCP_HOST –用于基于HTTP的传输的主机（默认值： 0.0.0.0)
  • MCP_PORT –用于基于HTTP的传输的端口（默认值： 8000)
  • MCP_PATH –HTTP传输路径（默认值： /mcp)

2.可用的MCP工具

服务器运行后，MCP客户端将看到以下工具：

  • store-knowledge(content: str, title?: str, tags?: list[str], metadata?: dict, collection_name?: str) -> str
  • store-knowledge-bulk(items: list[KnowledgeItem], collection_name?: str) -> str
  • search-knowledge(query: str, limit?: int=5, collection_name?: str) -> str
  • get-knowledge-by-id(ids: list[str] | str, collection_name?: str) -> str
  • inspect-knowledge-base(collection_name?: str) -> str
  • delete-knowledge(ids: list[str] | str, collection_name?: str) -> str

store-knowledge 使用OpenAI自动嵌入文本并将其存储在Qdrant（知识库）中，返回存储的点ID title 和 tags 字段有助于改善搜索上下文和分类。

store-knowledge-bulk 使用批嵌入一次有效地存储多个知识项。清单中的每一项都应包括 content （必填），可选 title, tags，以及 metadata 领域。这比打电话更有效率 store-knowledge 多次。

search-knowledge 在Qdrant中使用混合搜索（密集+稀疏）。如果集合配置了命名向量 dense 和 sparse，通过融合密集的OpenAI嵌入和稀疏的BM25分数对查询进行排名；否则，它将退回到仅密集搜索。

get-knowledge-by-id 通过一个或多个知识项的点ID检索其完整的有效载荷信息。使用此功能检查存储项目的全部详细信息（包括 content, title, tags, metadata，以及 stored_at 时间戳）。您可以传递单个ID或ID列表（通常使用 id 字段返回 search-knowledge).

inspect-knowledge-base 显示了收集配置和示例数据点，可用于调试和验证。

delete-knowledge 按点ID从Qdrant中删除一个或多个存储的知识项。您可以传递单个ID或ID列表（通常使用 id 字段返回 search-knowledge).

3.启动服务器

您可以通过CLI标志（建议快速启动）或通过env指定传输(MCP_TRANSPORT).

标准IO（stdio）-默认
uvx better-qdrant-mcp

在此模式下，您可以将MCP客户端配置为使用 标准 传输并仅调用二进制文件；不需要HTTP URL。

服务器发送事件（SSE）
# Default host 0.0.0.0 and port 8000
uvx better-qdrant-mcp --transport sse

# Custom host and port
uvx better-qdrant-mcp --transport sse --host 0.0.0.0 --port 3000

MCP客户端的连接详细信息：

  • 运输: sse
  • 统一资源定位符: http://<host>:<port>/sse （例如： http://localhost:8000/sse)
流式HTTP（推荐用于web应用程序）
# Default host 0.0.0.0, port 8000 and path /mcp
uvx better-qdrant-mcp --transport streamable-http

# Custom host, port, and path
uvx better-qdrant-mcp --transport streamable-http --host 0.0.0.0 --port 3000 --path /api/mcp

MCP客户端的连接详细信息：

  • 运输: streamable-http
  • 统一资源定位符: http://<host>:<port><path> （例如： http://localhost:8000/mcp)

开发指南

本地安装（用于开发）

如果你想在本地处理此仓库，而不是使用已发布的包：

# using uv (recommended)
uv sync

# or with pip (editable install)
pip install -e .

本地建设

对于本地开发，您可以使用提供的 Makefile:

make build

此命令将首先清理 dist 目录，然后运行 uv build 生产新鲜的手工艺品。

Docker部署

Docker Compose将Qdrant+此MCP服务器作为单一服务提供。运输(stdio, sse, streamable-http)通过以下方式选择 MCP_TRANSPORT.

Docker镜像会自动构建并发布到GitHub容器注册表，如下所示：

  • ghcr.io/jtsang4/better-qdrant-mcp:latest
  • 分支、标签和提交SHA的附加标签

提供的 docker-compose.yml 直接使用此已发布的图像，因此您 不需要在本地构建映像.

# Start Qdrant + MCP using the published image
docker compose up -d

# Pull the latest published image and restart services
docker compose pull mcp && docker compose up -d

# Stop services
docker compose down

许可证

麻省理工学院

相关 MCP