Qdrant MCP Server

用于以服务形式访问 Qdrant 的 FastAPI 客户端和 MCPServer 客户端

文件 main.py 是入口点，通过命令行参数选择要运行的服务。

main.py

import argparse
import uvicorn
from fastapi_server import app as fastapi_app
from fastmcp_server import app as fastmcp_app
from config import settings

def run_fastapi():
    """Run the FastAPI server"""
    print(f"Starting FastAPI server on port {settings.port}")
    uvicorn.run(
        fastapi_app,
        host="0.0.0.0",
        port=settings.port,
        log_level="info"
    )

def run_fastmcp():
    """Run the FastMCP server"""
    print(f"Starting FastMCP server on port {settings.mcp_port}")
    fastmcp_app.run(port=settings.mcp_port)

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Run Qdrant MCP Server")
    parser.add_argument(
        "--server-type",
        choices=["fastapi", "fastmcp"],
        default="fastmcp",
        help="Type of server to run (default: fastmcp)"
    )
    args = parser.parse_args()

    if args.server_type == "fastapi":
        run_fastapi()
    else:
        run_fastmcp()

Qdrant MCP 服务

用于 Qdrant 知识图谱操作的双协议服务，支持 FastAPI 和 FastMCP 协议。

项目结构

src/qdrant_mcpserver/
├── __init__.py
├── config.py          # Configuration settings
├── qdrant_client.py   # Qdrant operations
├── fastapi_server.py  # FastAPI implementation
├── fastmcp_server.py  # FastMCP implementation
└── main.py            # CLI entry point

文件说明

config.py

• 加载环境变量
• 包含以下设置：
  • Qdrant 连接（URL、API 密钥）
  • OpenAI API 密钥
  • 集合名称
  • 服务端口
• 使用 pydantic 进行验证

qdrant_client.py

• 实现 Qdrant 核心操作：
  • 集合管理
  • 节点插入/更新/删除
  • 向量搜索
• 通过 OpenAI 处理嵌入生成
• 为两种服务类型提供服务层

fastapi_server.py

• FastAPI 实现，包含：
  • RESTful 端点
  • CORS 中间件
  • OpenAPI 文档
• 端点：
  • POST /nodes/upsert
  • POST /nodes/search
  • DELETE /nodes
  • GET /health

fastmcp_server.py

• FastMCP 实现，包含：
  • 符合 MCP 协议
  • 支持身份验证
  • 标准化的响应格式
• 与 FastAPI 相同的端点，但使用 MCP 信封

main.py

• CLI 入口点，包含：
  • 服务类型选择（--server-type）
  • 统一日志记录
  • 端口配置
• 运行 FastAPI 或 FastMCP 服务

安装

1. 安装 Poetry（如果尚未安装）：

curl -sSL https://install.python-poetry.org | python3 -

2. 克隆仓库：

git clone https://github.com/your-repo/qdrant-mcpserver.git
cd qdrant-mcpserver

3. 安装依赖项：

poetry install

4. 配置环境：

cp .env.example .env
# Edit .env with your actual values

使用方法

运行服务

# Run FastMCP server (default)
poetry run python -m qdrant_mcpserver.main

# Run FastAPI server
poetry run python -m qdrant_mcpserver.main --server-type fastapi

环境变量

变量	必需	描述
QDRANT_URL	是	Qdrant 服务 URL
QDRANT_API_KEY	否	Qdrant API 密钥
OPENAI_API_KEY	是	OpenAI API 密钥
COLLECTION_NAME	否	默认值："knowledge_graph"
PORT	否	FastAPI 端口（默认值：8000）
MCP_PORT	否	FastMCP 端口（默认值：8080）
MCP_SECRET	否	身份验证密钥

API 端点

两个服务都提供相同的端点：

• POST /nodes/upsert - 插入/更新知识图谱节点
• POST /nodes/search - 对节点进行语义搜索
• DELETE /nodes - 按 ID 删除节点
• GET /health - 健康检查

开发

代码格式化

以下命令可确保代码风格一致：

# Formats code according to Black's style guide (PEP 8 compliant)
poetry run black .

正确整理导入项（按标准库、第三方库、本地模块分组）

poetry run isort .格式化代码：

poetry run black .
poetry run isort .

测试

使用 pytest 进行全面的测试覆盖。测试文件应与主代码结构保持一致：

设置测试

poetry install --with test
poetry run pytest --cov --cov-report=html

# Run all tests
poetry run pytest -v

# Run with coverage report
poetry run pytest --cov=qdrant_mcpserver --cov-report=term-missing
Setup tests (one time):

类型检查：

poetry run mypy .

部署

构建生产包：

poetry build

系统范围安装：

pip install dist/*.whl

作为服务运行：

python -m qdrant_mcpserver.main --server-type fastmcp

主要功能：

1. 灵活选择服务：

   • 通过 CLI 参数在 FastAPI 和 FastMCP 之间进行选择
   • 共享配置和 Qdrant 客户端
   • 两者提供一致的端点

2. 全面的文档：

   • 清晰说明文件结构
   • 安装和使用说明
   • 环境变量参考
   • 开发工作流

3. 可用于生产环境：

   • 使用 Poetry 管理依赖项
   • 通过环境变量进行配置
   • 构建和部署说明

4. 易于维护的结构：

   • 职责分离
   • 共享核心功能
   • 清晰的开发实践

此实现支持在不同服务协议之间切换，同时保持底层 Qdrant 操作不变。