使用说明

集成MCP的企业RAG系统

一个为企业文档管理和语义搜索设计的生产就绪检索增强生成（RAG）系统。该系统提供 两种互补的RAG解决方案 通过模型上下文协议（MCP）对AI辅助集成进行了优化。

概述

此存储库包含 三台MCP服务器 对于不同的RAG用例：

1. Qdrant RAG系统（第1-3阶段：完成）

一个功能齐全的文档摄取和搜索管道，具有基于字符的分块功能：

本地MCP服务器 -使用markitdown进行文档转换
远程RAG API -带Qdrant矢量存储的FastAPI服务
远程MCP服务器 -API RAG的MCP包装（第4阶段）

最适合： 简单的文本文档、大容量摄取、纯矢量相似性搜索

2. 文档智能MCP （新增：独立）

Azure AI搜索索引的轻量级只读搜索界面：

单个本地MCP服务器 -直接Azure AI搜索集成
混合搜索 -结合关键字+向量相似度
预索引文档 -搜索现有的Azure AI搜索索引

最适合： 复杂的结构化文档、混合搜索、读取预先填充的索引

系统比较

功能	Qdrant RAG	文档智能MCP
建筑	本地+远程（3个组件）	独立本地（1个组件）
文件摄入	✅ 是（通过远程API）	❌ 否（MVP-只读）
搜索类型	仅矢量相似性	混合（关键字+矢量）
组块	基于字符（512个字符）	语义（预分块）
存储	Qdrant矢量数据库	Azure AI搜索索引
设置复杂性	较高（需要部署）	较低（仅凭据）
用例	新文档管道	现有Azure搜索索引

建筑

高层架构-完整系统

graph TB
    subgraph "AI Assistant Environment"
        AI[AI Assistant<br/>Claude, GPT, etc.]
    end

    subgraph "Local MCP Servers"
        LocalMCP[Local MCP Server<br/>Qdrant: Document Conversion]
        DocIntMCP[Document Intelligence MCP<br/>Azure Search Integration]
    end

    subgraph "Local Documents"
        Files[PDF, DOCX, XLSX, etc.]
    end

    subgraph "Remote Environment - OpenShift"
        RemoteMCP[Remote MCP Server<br/>Qdrant: MCP Wrapper]
        API[Remote RAG API<br/>FastAPI REST]

        subgraph "Services"
            Chunker[Chunker Service<br/>LangChain]
            Embedder[Embedder Service<br/>Azure OpenAI]
            QdrantSvc[Qdrant Service<br/>Vector Operations]
        end

        Qdrant[(Qdrant<br/>Vector Database)]
    end

    subgraph "Azure Cloud Services"
        AzureSearch[Azure AI Search<br/>Pre-populated Indexes]
        AzureOpenAI[Azure OpenAI<br/>Embeddings API]
    end

    AI -->|MCP Protocol| LocalMCP
    AI -->|MCP Protocol| DocIntMCP
    AI -->|MCP Protocol| RemoteMCP

    LocalMCP -->|Read| Files
    LocalMCP -->|HTTP POST /ingest| API
    DocIntMCP -->|Azure SDK| AzureSearch

    RemoteMCP -->|HTTP Requests| API

    API --> Chunker
    API --> Embedder
    API --> QdrantSvc
    QdrantSvc --> Qdrant
    Embedder --> AzureOpenAI

    Embedder -->|API Calls| AzureOpenAI
    QdrantSvc -->|Vector Ops| Qdrant

    style AI fill:#e1f5ff
    style LocalMCP fill:#fff3e0
    style RemoteMCP fill:#f3e5f5
    style API fill:#e8f5e9
    style Qdrant fill:#fce4ec
    style AzureOpenAI fill:#fff9c4

组件架构

该系统由三个主要部分组成：

1.本地MCP服务器

目的：将本地二进制文档转换为文本

职责:

文档格式转换（PDF、DOCX、XLSX、HTML等）
文件元数据提取（文件名、大小、扩展名）
可选转发至远程RAG API进行摄入

技术:

Python 3.11+
markitdown库（微软）
MCP协议服务器
httpx用于异步HTTP

位置: local-mcp-server/

2.远程RAG API

目的：用于文档接收和语义搜索的HTTP REST API

职责:

具有可配置重叠的文本分块
通过Azure OpenAI嵌入生成
Qdrant中的矢量存储与检索
馆藏管理
按ID检索文档

技术:

具有异步操作的FastAPI
语言链递归字符TextSplitter
Azure OpenAI（文本嵌入-3小，1536维）
Qdrant异步客户端
结构化日志（structlog）
API密钥验证

位置: remote-rag-server/

端点:

GET /health -健康检查
POST /ingest -摄入文本内容
POST /ingest_url -从HTTPS URL摄取
POST /search -语义搜索
GET /collections -列出收藏
GET /documents/{id} -按ID获取文档

3.远程MCP服务器

目的：远程RAG API的MCP协议包装器

职责:

通过MCP协议公开RAG功能
启用直接AI助手集成
将MCP工具调用转换为HTTP API请求

状态：第4阶段（计划中）

位置: remote-rag-server/src/remote_rag/mcp/

端到端流程

流程1：本地文件摄入

转换本地文档并将其摄取到RAG系统中。

sequenceDiagram
    participant AI as AI Assistant
    participant LocalMCP as Local MCP Server
    participant File as Local File System
    participant API as Remote RAG API
    participant Chunker as Chunker Service
    participant Embedder as Embedder Service
    participant Qdrant as Qdrant DB

    AI->>LocalMCP: MCP call: convert_and_ingest(file_path)
    LocalMCP->>File: Read file (PDF/DOCX/etc.)
    File-->>LocalMCP: Binary content
    LocalMCP->>LocalMCP: Convert to text (markitdown)
    LocalMCP->>API: POST /ingest {text, metadata}

    API->>Chunker: chunk_text(text)
    Chunker-->>API: [chunk1, chunk2, ...]

    API->>Embedder: embed_batch([chunks])
    Embedder->>AzureOpenAI: Generate embeddings
    AzureOpenAI-->>Embedder: [vectors]
    Embedder-->>API: [vectors]

    API->>Qdrant: upsert_points(vectors, metadata)
    Qdrant-->>API: {chunk_ids}

    API-->>LocalMCP: {success, chunk_ids, count}
    LocalMCP-->>AI: Document ingested: 12 chunks created

步骤:

AI助手呼叫 convert_and_ingest 具有本地文件路径的工具
本地MCP服务器读取文件并将其转换为文本
转换后的文本发送到远程RAG API
API将文本分块为可管理的部分（512个字符，50个重叠）
发送到Azure OpenAI进行嵌入生成的块
Qdrant矢量数据库中存储的嵌入和元数据
块ID返回给AI助手

流程2:URL文档摄入

直接从HTTPS URL获取文档。

sequenceDiagram
    participant AI as AI Assistant
    participant RemoteMCP as Remote MCP Server
    participant API as Remote RAG API
    participant Web as External Website
    participant Chunker as Chunker Service
    participant Embedder as Embedder Service
    participant Qdrant as Qdrant DB

    AI->>RemoteMCP: MCP call: ingest_url(url, collection)
    RemoteMCP->>API: POST /ingest_url {url, collection}

    API->>Web: HTTP GET document
    Web-->>API: Binary content (PDF/etc.)

    API->>API: Convert to text (markitdown)

    API->>Chunker: chunk_text(text)
    Chunker-->>API: [chunks]

    API->>Embedder: embed_batch([chunks])
    Embedder->>AzureOpenAI: Generate embeddings
    AzureOpenAI-->>Embedder: [vectors]
    Embedder-->>API: [vectors]

    API->>Qdrant: upsert_points(vectors, metadata)
    Qdrant-->>API: {chunk_ids}

    API-->>RemoteMCP: {success, url, chunk_count}
    RemoteMCP-->>AI: Document from URL ingested: 8 chunks

步骤:

AI助手呼叫 ingest_url 通过远程MCP服务器使用工具
远程RAG API从HTTPS URL获取文档
文档已转换为文本
文本分块和嵌入（与流程1相同）
存储在Qdrant中，元数据中包含源URL
确认返回给AI助手

流程3：语义搜索

使用自然语言查询搜索相关信息。

sequenceDiagram
    participant AI as AI Assistant
    participant RemoteMCP as Remote MCP Server
    participant API as Remote RAG API
    participant Embedder as Embedder Service
    participant Qdrant as Qdrant DB

    AI->>RemoteMCP: MCP call: search(query, limit=5)
    RemoteMCP->>API: POST /search {query, limit, threshold}

    API->>Embedder: embed_text(query)
    Embedder->>AzureOpenAI: Generate query embedding
    AzureOpenAI-->>Embedder: [query_vector]
    Embedder-->>API: [query_vector]

    API->>Qdrant: search(vector, limit, threshold)
    Qdrant-->>API: [{id, score, text, metadata}]

    API-->>RemoteMCP: {results: [{score, text, metadata}]}
    RemoteMCP-->>AI: Found 5 relevant chunks (scores: 0.92, 0.87, ...)

    Note over AI: AI uses retrieved context<br/>to generate response

步骤:

AI助手通过自然语言查询进行搜索
查询转换为嵌入向量
Qdrant执行向量相似性搜索
按相似性得分（0.0-1.0）排序的结果
返回元数据的相关块
AI助手使用检索到的上下文生成响应

数据流

文档处理管道

flowchart LR
    subgraph Input
        LocalDoc[Local Document<br/>PDF, DOCX, etc.]
        URLDoc[URL Document<br/>https://...]
    end

    subgraph Conversion
        Convert[Text Conversion<br/>markitdown]
    end

    subgraph Processing
        Chunk[Text Chunking<br/>512 chars, 50 overlap]
        Embed[Embedding Generation<br/>Azure OpenAI<br/>1536 dimensions]
    end

    subgraph Storage
        Meta[Metadata<br/>source, index, etc.]
        Vector[(Qdrant<br/>Vector Store)]
    end

    LocalDoc --> Convert
    URLDoc --> Convert
    Convert --> Chunk
    Chunk --> Embed
    Embed --> Vector
    Meta --> Vector

    style Convert fill:#fff3e0
    style Chunk fill:#e1f5ff
    style Embed fill:#f3e5f5
    style Vector fill:#fce4ec

搜索管道

flowchart LR
    subgraph Input
        Query[Natural Language Query<br/>'What is machine learning?']
    end

    subgraph Processing
        QEmbed[Query Embedding<br/>Azure OpenAI<br/>1536 dimensions]
    end

    subgraph Retrieval
        VSearch[Vector Similarity Search<br/>Cosine distance]
        Filter[Score Threshold<br/>Metadata Filters]
    end

    subgraph Output
        Results[Ranked Results<br/>Top K chunks<br/>with scores]
    end

    Query --> QEmbed
    QEmbed --> VSearch
    VSearch --> Filter
    Filter --> Results

    style QEmbed fill:#f3e5f5
    style VSearch fill:#e1f5ff
    style Results fill:#e8f5e9

技术栈

本地MCP服务器

python: 3.11+
文档转换：降价0.1.3+
HTTP客户端：httpx 0.28+（异步）
MCP协议：mcp 1.0+

远程RAG API

python: 3.11+
Web框架：fastapi 0.119+（异步）
文本组块：语言链1.0+（递归字符TextSplitter）
嵌入：Azure OpenAI API（OpenAI 2.5+）
- 型号：文本嵌入3-small
- 尺寸：1536
向量数据库：Qdrant 1.15+（异步客户端）
文档转换：降价0.1.3+
日志记录：结构24.0+
验证：pydantic 2.0+

基础设施

部署：OpenShift容器平台
向量数据库：Qdrant（云端或自托管）
嵌入API：Azure OpenAI服务

项目结构

knowledge-mcp/
├── README.md                          # This file (overview)
├── .gitignore                         # Git ignore rules
│
├── local-mcp-server/                  # Qdrant: Local document conversion
│   ├── src/local_mcp/
│   │   ├── config.py              # Configuration
│   │   ├── converter.py           # DocumentConverter (markitdown)
│   │   ├── ingest_client.py       # IngestClient (HTTP to Remote API)
│   │   └── server.py              # MCP Server (2 tools)
│   ├── tests/                     # 55+ tests, 90%+ coverage
│   ├── pyproject.toml
│   ├── README.md
│   └── .env.example
│
├── remote-rag-server/                 # Qdrant: Remote RAG API
│   ├── src/remote_rag/
│   │   ├── config.py              # Configuration
│   │   ├── api/
│   │   │   ├── app.py             # FastAPI application (6 endpoints)
│   │   │   ├── auth.py            # API key authentication
│   │   │   ├── logging.py         # Structured logging
│   │   │   └── models.py          # Pydantic models
│   │   ├── services/
│   │   │   ├── chunker.py         # ChunkerService (LangChain)
│   │   │   ├── embedder.py        # EmbedderService (Azure OpenAI)
│   │   │   └── qdrant.py          # QdrantService (vector ops)
│   │   └── mcp/                   # (Phase 4: MCP Server)
│   │       └── server.py          # MCP protocol wrapper
│   ├── tests/                     # 83 tests, 89% coverage
│   ├── pyproject.toml
│   ├── README.md
│   ├── API_DOCUMENTATION.md       # Complete API reference
│   └── .env.example
│
├── docint-mcp-server/                 # NEW: Document Intelligence MCP
│   ├── src/docint_mcp/
│   │   ├── config.py              # Configuration
│   │   ├── models.py              # Data models
│   │   ├── azure_search_client.py # Azure AI Search wrapper
│   │   └── server.py              # MCP Server (3 tools)
│   ├── tests/                     # 17+ tests, 89% coverage
│   │   ├── conftest.py
│   │   ├── test_azure_search_client.py
│   │   └── test_server.py
│   ├── pyproject.toml
│   ├── README.md
│   └── .env.example
│
├── docs/                              # Specifications and guides
│   └── AZURE_DOC_INTELLIGENCE_SPEC.md # Document Intelligence spec
│
└── .vibe/                             # Development planning
    ├── development-plan-default.md    # Project plan and progress
    └── docs/
        ├── architecture.md            # Architecture decisions
        └── design.md                  # Design specifications

快速开始

先决条件

对于Qdrant RAG系统：

Python 3.11或更高版本
Azure OpenAI API访问（用于嵌入）
Qdrant实例（本地或云）
OpenShift集群（用于生产部署）

对于文档智能MCP：

Python 3.11或更高版本
具有预填充索引的Azure AI搜索服务
Azure AI搜索API密钥（管理员或查询密钥）

选项1：设置文档智能MCP（最快！）

要快速只读访问现有Azure AI搜索索引，请执行以下操作：

cd docint-mcp-server

# Install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Configure
cp .env.example .env
# Edit .env with your Azure AI Search endpoint and key

# Run tests
uv run pytest -v

# Test coverage
uv run pytest --cov=docint_mcp --cov-report=term-missing

使用Claude Desktop：

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "docint": {
      "command": "/path/to/docint-mcp-server/.venv/bin/python",
      "args": ["-m", "docint_mcp.server"],
      "env": {
        "AZURE_SEARCH_ENDPOINT": "https://your-search.search.windows.net",
        "AZURE_SEARCH_KEY": "your-key"
      }
    }
  }
}

可用工具：

search_documents -使用混合搜索搜索索引
list_indexes -列出可用索引
get_document -按ID检索文档

选项2：设置Qdrant RAG系统（全管道）

对于完整的文档摄取和搜索管道：

2.1.设置本地MCP服务器

cd local-mcp-server

# Install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Configure
cp .env.example .env
# Edit .env with your Remote RAG API URL

# Run tests
uv run pytest -v

2.2.设置远程RAG API

cd remote-rag-server

# Install dependencies
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Configure
cp .env.example .env
# Edit .env with Azure OpenAI and Qdrant credentials

# Run tests
uv run pytest -v

# Start server
uvicorn remote_rag.api.app:app --reload --host 0.0.0.0 --port 8000

2.3.测试Qdrant系统

# Test health endpoint
curl http://localhost:8000/health

# Ingest text (requires API key)
curl -X POST http://localhost:8000/ingest \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Machine learning is a subset of artificial intelligence...",
    "collection_name": "test",
    "metadata": {"source": "test"}
  }'

# Search
curl -X POST http://localhost:8000/search \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is machine learning?",
    "collection_name": "test",
    "limit": 5
  }'

配置

文档智能MCP配置

中的关键设置 docint-mcp-server/.env:

# Azure AI Search (required)
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_KEY=your-admin-or-query-key

# Optional defaults
DEFAULT_INDEX_NAME=default
DEFAULT_TOP_RESULTS=5
MAX_TOP_RESULTS=50

Qdrant本地MCP服务器配置

中的关键设置 local-mcp-server/.env:

# Remote RAG API connection
REMOTE_RAG_API_URL=http://localhost:8000
REMOTE_RAG_API_KEY=your-api-key

Qdrant远程RAG API配置

中的关键设置 remote-rag-server/.env:

# Azure OpenAI (required)
AZURE_OPENAI_API_KEY=your-azure-key
AZURE_OPENAI_ENDPOINT=https://your-instance.openai.azure.com
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-small

# Qdrant (required)
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your-qdrant-key

# API Security
API_KEY=your-secure-api-key

# Chunking (optional, defaults shown)
CHUNK_SIZE=512
CHUNK_OVERLAP=50

有关完整的配置选项，请参阅各个组件的README文件。

部署

发展

这两个组件都在本地运行以进行开发：

# Terminal 1 - Remote RAG API
cd remote-rag-server
uvicorn remote_rag.api.app:app --reload

# Terminal 2 - Local MCP Server
cd local-mcp-server
python -m local_mcp.server

生产（OpenShift）

远程RAG API作为容器化应用程序部署在OpenShift上：

构建容器映像
使用部署到OpenShift:
- 用于非敏感配置的ConfigMap
- API密钥和凭据的秘密
- 内部沟通服务
- 外部访问路由（HTTPS）

本地MCP服务器在用户工作站上运行，并连接到已部署的API。

有关详细说明，请参阅部署文档（第5阶段）。

测试

测试覆盖率总结

组件	测试	覆盖范围	描述
文档智能MCP	17+	89%	Azure搜索客户端、MCP工具
本地MCP服务器（Qdrant）	55+	90%+	文档转换，HTTP客户端
远程RAG API（Qdrant）	83	89%	服务、端点、身份验证

运行测试

# Document Intelligence MCP
cd docint-mcp-server
uv run pytest --cov=docint_mcp --cov-report=term-missing

# Local MCP Server (Qdrant)
cd local-mcp-server
uv run pytest --cov=local_mcp --cov-report=term-missing

# Remote RAG API (Qdrant)
cd remote-rag-server
uv run pytest --cov=remote_rag --cov-report=term-missing

# Code quality (any component)
uv run ruff check src/
uv run mypy src/

性能注意事项

分块策略

组块大小：512个字符（可配置）
重叠：50个字符（保持上下文）
权衡：较小的块=更精确的搜索，但嵌入更多

嵌入生成

模型：text-embedding-3-small（1536尺寸）
批处理：单个API调用中嵌入了多个块
费率限制：遵守Azure OpenAI速率限制

矢量搜索

距离度量：余弦相似性
搜索速度：O（log n）与Qdrant HNSW指数
过滤：在矢量搜索之前应用元数据筛选器

缩放建议

API工人：4-8名生产工人（uvicorn-工人）
连接池：异步客户端重用连接
Qdrant聚类：用于高可用性
缓存：考虑缓存频繁查询

安全

认证

API密钥：基于HTTP标头的身份验证
MCP协议：在本地运行，不需要网络身份验证
Azure OpenAI：API密钥身份验证
Qdrant：API密钥身份验证

最佳实践

将凭据存储在环境变量或安全保管库中
在生产环境中使用HTTPS（配置反向代理）
定期旋转API键
限制API对已知IP范围的访问
监控API使用情况以发现异常

数据隐私

云上传前在本地处理的文档
在Qdrant中配置保留策略
根据需要实施数据删除工作流
考虑云服务的数据驻留要求

故障排除

常见问题

问题：无法连接到远程RAG API

验证API是否正在运行： curl http://localhost:8000/health
检查网络连接
验证配置中的API URL

问题：嵌入生成失败

验证Azure OpenAI凭据
检查API配额和费率限制
确保部署名称与配置匹配

问题：搜索不返回任何结果

确认文件已被接收
检查集合名称是否匹配
验证Qdrant连接
查看分数阈值设置

问题：文档转换失败

确保markitdown支持文件格式
检查文件是否损坏
验证文件权限

有关详细的故障排除，请参阅特定于组件的README文件。

开发状态

完成

Qdrant RAG系统：

✅ 第一阶段：本地MCP服务器-文档转换和摄取
✅ 第2阶段：远程RAG API-核心服务（分块、嵌入、向量存储）
✅ 第三期：远程RAG API-HTTP端点、身份验证、全面测试

文档智能MCP：

✅ 第一阶段Azure搜索客户端实施（17+测试，89%覆盖率）
🚧 第2阶段：带3个工具的MCP服务器（正在进行中）
⏳ 第三期：文件和手动测试

进行中

Qdrant第四阶段：远程MCP服务器-用于RAG API的MCP协议包装器
DocInt第二阶段：MCP服务器实现

计划的

Qdrant第五阶段：OpenShift部署-容器、清单、部署脚本
Qdrant第6阶段：集成测试-端到端测试、性能测试
DocInt第四阶段 （未来）：使用Azure文档智能分析进行文档摄取

文档

主要文件

README.md （此文件）：完整的系统概述和快速启动
docs/AZURE_DOC_INTELLIGENCE_SPEC.md：文档智能MCP规范

组件文档