关键词

向量搜索知识图谱网页智能AI上下文服务RAG应用

项目简介

'qdrant-neo4j-crawl4ai-mcp' 是一个功能强大的统一智能服务器，它将 Qdrant 向量数据库、Neo4j 知识图谱和 Crawl4AI 网页智能服务整合在一起，并通过 Model Context Protocol (MCP) 标准协议对外提供服务。它旨在为 AI 助手和大型语言模型（LLM）客户端提供丰富的、可扩展的上下文信息、外部功能调用以及定制化的交互模式，是构建高级 AI 应用的关键后端。

主要功能点

  • 多源智能集成: 无缝整合向量搜索（Qdrant）、知识图谱（Neo4j）和网页智能（Crawl4AI），提供多模态数据处理能力。
  • 上下文服务: 通过标准化的 MCP 协议，向 LLM 客户端提供托管资源、调用工具和获取 Prompt 模板的能力。
  • 高级搜索: 支持语义向量搜索和基于知识图谱的结构化查询，实现更精准的数据检索。
  • 知识提取: 利用 AI 能力从文本和网页内容中自动提取实体、关系和概念，构建和丰富知识图谱。
  • 网页智能: 提供网站爬取、内容提取、屏幕截图以及网页变化监控功能。
  • 安全与监控: 内置 JWT 认证、API 密钥管理、速率限制、安全头策略及 Prometheus 指标收集，确保生产环境的稳定和安全。
  • 可扩展架构: 采用 FastAPI 框架和异步设计，支持 Docker 和 Kubernetes 部署，易于扩展和维护。

安装步骤

  1. 克隆仓库:

    git clone https://github.com/Hyperkorn/qdrant-neo4j-crawl4ai-mcp.git
cd qdrant-neo4j-crawl4ai-mcp

  2. 创建并激活虚拟环境:

    python3 -m venv venv
source venv/bin/activate  # 适用于 macOS/Linux
# 或 .venv\Scripts\activate # 适用于 Windows

  3. 安装依赖:

    pip install -r requirements.txt

  4. 配置环境变量:

    • 复制 '.env.example' 文件为 '.env'： 
      cp .env.example .env
    • 编辑 '.env' 文件，根据您的实际部署环境配置以下关键信息：
      • 'QDRANT_URL': Qdrant 向量数据库的服务地址 (例如: 'http://localhost:6333')
      • 'NEO4J_URI': Neo4j 图数据库的服务 URI (例如: 'bolt://localhost:7687')
      • 'NEO4J_USER': Neo4j 用户名
      • 'NEO4J_PASSWORD': Neo4j 密码
      • 'OPENAI_API_KEY': 如果启用 GraphRAG（知识图谱增强生成）功能，需要配置 OpenAI API 密钥。
      • 'JWT_SECRET_KEY': 用于 JWT 认证的密钥，请设置为一个强随机字符串。
      • 'ADMIN_API_KEY': 用于管理员 API 访问的密钥，请设置为一个强随机字符串。
      • 其他如 'HOST', 'PORT', 'LOG_LEVEL' 等可根据需要调整。

  5. 启动外部服务:

    • 确保 Qdrant 和 Neo4j 服务正在运行。如果您使用 Docker，可以使用以下命令启动： 
      # 启动 Qdrant 向量数据库
docker run -p 6333:6333 qdrant/qdrant

# 启动 Neo4j 图数据库 (首次运行需要设置密码)
docker run -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/<您的密码> neo4j
    • Crawl4AI 网页智能服务是集成在服务器内部的，不需要单独启动。

  6. 启动服务器:

    python src/qdrant_neo4j_crawl4ai_mcp/main.py

    服务器将在配置的端口（默认为 'http://0.0.0.0:8000'）启动。

MCP服务器配置

当 MCP 客户端需要连接此服务器时，需要提供以下 JSON 格式的配置信息。这些信息将指导客户端如何通过 JSON-RPC 与服务器通信。

{
  "server_name": "Unified MCP Intelligence Server",
  "command": ["python"],
  "args": ["src/qdrant_neo4j_crawl4ai_mcp/main.py"],
  "description": "提供向量搜索、知识图谱和网页智能的统一MCP服务，支持AI应用获取上下文和调用外部功能。",
  "protocol_version": "2024-11-05",
  "rpc_endpoint": "/mcp",
  "authentication": {
    "type": "bearer",
    "get_token_endpoint": "/auth/token",
    "token_request_body": {
      "username": "client_user",
      "scopes": ["read", "write"]
    },
    "token_response_field": "access_token"
  },
  "capabilities": {
    "initialize": true,
    "initialized": true,
    "ping": true,
    "tools/list": true,
    "tools/call": true,
    "resources/list": true,
    "resources/read": true,
    "prompts/list": true,
    "prompts/get": true,
    "completion/complete": true,
    "roots/list": true,
    "sampling/createMessage": true,
    "logging/setLevel": true
  },
  "health_check_endpoint": "/health"
}

配置说明:

  • 'server_name': 服务器的名称，用于客户端识别。
  • 'command': 启动 MCP 服务器所使用的命令。
  • 'args': 启动命令的参数列表。
  • 'description': 服务器功能的简要描述。
  • 'protocol_version': 服务器支持的 MCP 协议版本。
  • 'rpc_endpoint': MCP 客户端应向此路径发送 JSON-RPC 请求。
  • 'authentication': 描述客户端如何进行身份验证。
    • 'type': 认证类型，此处为 'bearer' (JWT)。
    • 'get_token_endpoint': 客户端获取 JWT 令牌的 API 端点。
    • 'token_request_body': 客户端请求令牌时需要发送的 JSON 请求体示例。
    • 'token_response_field': 令牌在 API 响应中所在的字段名。
  • 'capabilities': 服务器支持的 MCP 核心功能列表，此处列出了所有已知的 MCP 方法，表明服务器提供了全面的 MCP 功能。
  • 'health_check_endpoint': 用于检查服务器健康状态的 API 端点。

基本使用方法

  1. 获取访问令牌: 客户端首先需要通过 'POST /auth/token' 端点获取 JWT 访问令牌。
    • 请求示例: 
      {
    "username": "your_user",
    "scopes": ["read", "write"]
}
    • 响应将包含 'access_token'，客户端在后续请求中需将其放入 'Authorization: Bearer <token>' 请求头。
  2. 调用 MCP 工具:
    • 服务器提供了多种 MCP 工具（例如，'store_vector_document' 用于存储向量文档、'semantic_vector_search' 用于向量搜索、'create_graph_node' 用于创建图节点、'crawl_web_page' 用于网页爬取等）。
    • 客户端可以通过 'POST /mcp' 端点发送 JSON-RPC 请求，其中 'method' 字段为工具名称，'params' 字段为工具所需的参数。
    • 例如，调用 'semantic_vector_search' 工具进行向量搜索： 
      {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "semantic_vector_search",
    "params": {
        "query": "What is machine learning?",
        "collection_name": "demo_collection",
        "limit": 5
    }
}
    • 客户端还可以调用 'tools/list' 方法获取所有可用工具的列表及其详细描述。
  3. 探索 API: 访问服务器的 '/docs' (Swagger UI) 或 '/redoc' (ReDoc) 地址，可以查看所有可用的 REST API 端点和 MCP 工具的详细文档。

信息

分类

AI与计算

访问项目