一个用于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():
    """运行 FastAPI 服务器"""
    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():
    """运行 FastMCP 服务器"""
    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          # 配置设置
├── qdrant_client.py   # Qdrant 操作
├── fastapi_server.py  # FastAPI 实现
├── fastmcp_server.py  # FastMCP 实现
└── main.py            # CLI 入口点

文件描述

config.py

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

qdrant_client.py

• 实现核心 Qdrant 操作：
  • 集合管理
  • 节点 upsert/delete
  • 向量搜索
• 通过 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
# 使用您的实际值编辑 .env

用法

运行服务器

# 运行 FastMCP 服务器（默认）
poetry run python -m qdrant_mcpserver.main

# 运行 FastAPI 服务器
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 - Upsert 知识图谱节点
• POST /nodes/search - 跨节点的语义搜索
• DELETE /nodes - 按 ID 删除节点
• GET /health - 健康检查

开发

代码格式化

这些命令确保一致的代码风格：

# 根据 Black 的风格指南（符合 PEP 8）格式化代码
poetry run black .

正确组织导入（分组标准库、第三方、本地）

poetry run isort .Format code:

poetry run black .
poetry run isort .

测试

使用 pytest 进行全面的测试覆盖。 测试文件应镜像主代码结构：

设置测试

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

# 运行所有测试
poetry run pytest -v

# 运行带有覆盖率报告的测试
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 操作。