使用说明
用于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/节点/升级
- POST/节点/搜索
- 删除/节点
- GET/健康
fastmcp_server.py
- FastMCP实施包括：
- MCP协议合规性
- 身份验证支持
- 标准化响应格式
- 与FastAPI相同的端点，但具有MCP信封
main.py
- CLI入口点：
- 服务器类型选择（--服务器类型）
- 统一日志记录
- 端口配置
- 运行FastAPI或FastMCP服务器
安装
- 安装诗歌（如果未安装）：
curl -sSL https://install.python-poetry.org | python3 -
- 克隆存储库：
git clone https://github.com/your-repo/qdrant-mcpserver.git
cd qdrant-mcpserver
- 安装依赖项：
poetry install
- 配置环境：
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密钥 |
| 集合名称 | 否 | 默认值：“知识图” |
| 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 .
正确组织导入（将标准库、第三方库、本地库分组）
诗歌运行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
主要特点：
-
灵活的服务器选择:
- CLI参数在FastAPI和FastMCP之间进行选择
- 共享配置和Qdrant客户端
- 两者端点一致
-
综合文档:
- 清晰的文件结构说明
- 安装和使用说明
- 环境变量引用
- 开发工作流程
-
生产准备就绪:
- 依赖管理诗
- 通过环境变量进行配置
- 构建和部署说明
-
可维护结构:
- 关注点分离
- 共享核心功能
- 明确的开发实践
该实现允许您在服务器协议之间切换，同时保持相同的底层Qdrant操作。
