Qdrant MCP 服务器

一个支持 Qdrant 和 Chroma 向量数据库的服务器实现，用于存储和检索领域知识。

特性

• 支持 Qdrant 和 Chroma 向量数据库
• 可通过环境变量配置数据库选择
• 使用 Qdrant 内置的 FastEmbed 实现高效的嵌入生成
• 领域知识存储和检索
• 支持带元数据的文档文件存储
• 支持 PDF 和 TXT 文件格式

前提条件

• Node.js 20.x 或更高版本（推荐 LTS）
• npm 10.x 或更高版本
• Qdrant 或 Chroma 向量数据库

安装

1. 克隆仓库：

git clone <repository-url>
cd qdrant-mcp-server

2. 安装依赖：

npm install

3. 基于 .env.example 模板在根目录下创建一个 .env 文件：

cp .env.example .env

4. 使用您自己的设置更新 .env 文件：

DATABASE_TYPE=qdrant
QDRANT_URL=https://your-qdrant-instance.example.com:6333
QDRANT_API_KEY=your_api_key
COLLECTION_NAME=your_collection_name

5. 构建项目：

npm run build

AI IDE 集成

Cursor AI IDE

在项目根目录下创建脚本 run-cursor-mcp.sh：

#!/bin/zsh
cd /path/to/your/project
source ~/.zshrc
nvm use --lts

# 让应用程序从 .env 文件加载环境变量
node dist/index.js

使脚本可执行：

chmod +x run-cursor-mcp.sh

将此配置添加到您的 ~/.cursor/mcp.json 或 .cursor/mcp.json 文件中：

{
  "mcpServers": {
    "qdrant-retrieval": {
      "command": "/path/to/your/project/run-cursor-mcp.sh",
      "args": []
    }
  }
}

Claude Desktop

在 Claude 的设置中添加此配置：

{
  "processes": {
    "knowledge_server": {
      "command": "/path/to/your/project/run-cursor-mcp.sh",
      "args": []
    }
  },
  "tools": [
    {
      "name": "store_knowledge",
      "description": "将特定领域的知识存储在向量数据库中",
      "provider": "process",
      "process": "knowledge_server"
    },
    {
      "name": "retrieve_knowledge_context",
      "description": "从向量数据库中检索相关的领域知识",
      "provider": "process",
      "process": "knowledge_server"
    }
  ]
}

使用方法

启动服务器

npm start

用于开发，具有自动重新加载功能：

npm run dev

存储文档

服务器包含一个脚本，用于存储带有元数据的文档文件（PDF 和 TXT）：

npm run store-doc <path-to-your-file>

示例：

# 存储一个 PDF 文件
npm run store-doc docs/manual.pdf

# 存储一个文本文件
npm run store-doc docs/readme.txt

该脚本将：

• 从文件中提取内容（PDF 中的文本或纯文本）
• 存储带有元数据的内容，包括：
  • Source: "documentation"
  • 文件名和扩展名
  • 文件大小
  • 上次修改日期
  • 创建日期
  • 内容类型

API 接口

存储领域知识

POST /api/store
Content-Type: application/json

{
  "content": "您的领域知识内容",
  "source": "您的来源",
  "metadata": {
    "key": "value"
  }
}

查询领域知识

POST /api/query
Content-Type: application/json

{
  "query": "您的搜索查询",
  "limit": 5
}

开发

运行测试

npm test

构建项目

npm run build

代码检查

npm run lint

项目结构

src/
├── core/
│   ├── db-service.ts      # 数据库服务实现
│   └── embedding-utils.ts # 嵌入实用程序
├── scripts/
│   └── store-documentation.ts  # 文档存储脚本
└── index.ts              # 主服务器文件

与远程 Qdrant 一起使用

当与远程 Qdrant 实例（如 Qdrant Cloud）一起使用时：

1. 确保您的 .env 具有正确的 URL 和端口号：

QDRANT_URL=https://your-instance-id.region.gcp.cloud.qdrant.io:6333

2. 设置您的 API 密钥：

QDRANT_API_KEY=your_qdrant_api_key

FastEmbed 集成

本项目使用 Qdrant 内置的 FastEmbed 实现高效的嵌入生成：

优点

• 轻量级且快速的嵌入生成
• 使用量化的模型权重和 ONNX Runtime 进行推理
• 根据 Qdrant 的说法，比 OpenAI Ada-002 具有更好的准确性
• 无需外部嵌入 API 密钥

工作原理

1. 系统连接到您的 Qdrant 实例
2. 生成嵌入时，它使用 Qdrant 的服务器端嵌入端点
3. 这消除了对外部嵌入 API 的需求并简化了架构

配置

无需额外配置，因为 FastEmbed 已内置于 Qdrant 中。 只需确保您的 Qdrant URL 和 API 密钥在您的 .env 文件中正确设置即可。

故障排除

如果您遇到问题：

1. 确保您使用的是 Node.js LTS 版本 (nvm use --lts)
2. 验证您的环境变量是否正确
3. 检查 Qdrant/Chroma 连接
4. 确保您的 Qdrant 实例已正确配置

许可证

MIT