内容
# MCP 服务器
### 🧩 主要模块
1. **主 MCP 服务器** - 系统的核心，执行以下功能：
- 连接服务器的注册
- 服务器之间的请求路由
- 服务器状态监控
- 关于可用工具的信息聚合
2. **专用服务器**（连接到主服务器）：
- **嵌入服务器** - 处理文本的向量表示
- **PDF 提取服务器** - 从 PDF 到 Markdown 的转换和提取
- **重排服务器** - 文本数据排名
- **Qdrant 服务器** - 管理向量集合
- **PostgreSQL 服务器** - 执行 SQL 查询和模式检查
- **LLM 服务器** - 生成和流式传输 LLM 响应，模型列表
- **标记服务器** - 使用标记服务方法进行文本/文件标记
- **转录服务器** - 音频加载、状态和转录结果
### ⚙️ 可用工具
| 服务器 | 方法 |
|---|---|
| **嵌入服务器** | `embedding_generate`, `embedding_batch_generate`, `embedding_get_models`, `health_check` |
| **PDF 提取服务器** | `document_convert_to_markdown`, `document_get_supported_formats`, `health_check` |
| **重排服务器** | `rerank_documents`, `health_check` |
| **Qdrant 服务器** | `vector_create_collection`, `vector_get_collection_info`, `vector_upsert_points`, `vector_search`, `vector_delete_points`, `health_check` |
| **PostgreSQL 服务器** | `postgres_execute_query`, `postgres_get_schema`, `postgres_create_table`, `postgres_insert_data`, `health_check` |
| **LLM 服务器** | `llm_chat_completion`, `llm_get_models`, `llm_stream_completion`, `health_check` |
| **标记服务器** | `markup_get_methods`, `markup_process_text`, `markup_process_file`, `health_check` |
| **转录服务器** | `transcribe_audio`, `transcribe_get_status`, `transcribe_get_result`, `health_check` |
##### 注意：
要添加新的 FastMCP 服务器，需要在 `main_server.py` 文件中导入它并将其放在 `MCP_SERVERS` 数组中，之后 `main_server.py` 的主要方法将可以访问它。
同时，FastMCP 服务器的必要条件是存在 `health_check` 方法来检查状态。
### 📡 主服务器方法
```python
get_server_and_tools() # 获取所有服务器和工具的列表
router(server_name, tool_name, params) # 请求路由
health_check_servers() # 检查所有服务器的健康状况
```
### 环境设置
在项目根目录下创建一个 `.env` 文件，并将以下环境变量放入其中（列表对应代码中的使用）：
```
# 主服务器
MAIN_SERVER_API_KEY=...
# 嵌入服务器
EMBEDDING_API_KEY=...
EMBEDDING_URL=...
EMBEDDING_MODEL_NAME=...
EMBEDDING_URL_MODELS=...
EMBEDDING_HEALTH_URL=...
# PDF 提取服务器
PDF_EXTRACTOR_URL=...
PDF_HEALTH_URL=...
# 重排服务器
RERANK_URL=...
RERANK_MODEL=...
RERANK_HEALTH_URL=...
# Qdrant 服务器
QDRANT_URL=...
QDRANT_API_KEY=...
QDRANT_HEALTH_CHECK_URL=...
# PostgreSQL 服务器
POSTGRES_USER=...
POSTGRES_PASSWORD=...
POSTGRES_HOST=...
POSTGRES_DB=...
#LLM 服务器
LLM_SERVICE_API_KEY=...
LLM_SERVICE_MODEL=...
LLM_SERVICE_CHAT_COMPLETIONS_URL=...
LLM_SERVICE_MODELS_URL=...
LLM_SERVICE_COMPLETIONS_URL=...
LLM_SERVICE_HEALTH_URL=...
# 标记服务器
MARKUP_API_KEY=...
MARKUP_GET_METHODS_URL=...
MARKUP_PROCESS_TEXT_URL=...
MARKUP_PROCESS_FILE_URL=...
MARKUP_HEALTH_CHECK_URL=...
# 转录服务器
TRANSCRIBE_API_KEY=...
TRANSCRIBE_UPLOAD_AUDIO=...
TRANSCRIBE_HEALTH_URL=...
```
# 启动主服务器
### 安装依赖和创建虚拟环境
在启动服务器之前，建议创建虚拟环境并从 `requirements.txt` 安装所有依赖。 在终端中运行以下命令：
1. 创建虚拟环境
```bash
python -m venv venv
```
2. 激活环境
```bash
./venv/Scripts/activate
```
3. 安装依赖
```bash
pip install -r requirements.txt
```
设置环境后，使用以下命令启动服务器
```bash
fastmcp run ./main_server.py:main_mcp_server --transport http
```
### 在 Docker 中运行
1. 构建镜像：
```bash
docker build -t mcp-main-server .
```
2. 运行容器，传递 `.env` 作为环境变量：
```bash
docker run --rm -p 8000:8000 --env-file .env mcp-main-server
```
### 在 Cursor 中配置服务器连接
0. 使用上述命令运行服务器
1. 打开设置
2. 添加 MCP 服务器配置：
```json
{
"mcpServers": {
"main-registry": {
"url": "http://localhost:8000/mcp/"
}}}
```
# 本地 MCP 服务器：`proxy_mcp_server`
- **是什么**：连接到主注册表（`main_server`）并转发其方法的代理 MCP 服务器，并为 RAG 提供数据预准备的高级管道。
- **在哪里**：`proxy_mcp_server/proxy_mcp_server.py`
- **可用工具**：
- `get_server_and_tools()` — 从注册表获取服务器和工具的列表
- `router(server_name: str, tool_name: str, params: dict)` — 通用调用路由器
- `preprocessing_data_for_rag(file_paths: List[str]) -> str` — 准备 PDF/文本并在 Qdrant 中创建集合；返回集合名称
- `health_check_servers()` — 检查所有服务是否可用
要求：
- `main_server` 正在运行，并且可以通过 URL 访问（例如 `http://localhost:8000/mcp/`）。
- 有效的 API 密钥 `MAIN_SERVER_API_KEY`（必须与 `proxy_mcp_server.py` 中的 `Authorization` 头匹配）。
- 根据需要更新 `proxy_mcp_server/proxy_mcp_server.py` 中的 `config` 对象内的 `url` 和 `headers.Authorization`。
在 Cursor 中连接（示例）：
```json
{
"mcpServers": {
"proxy-server": {
"command": "uv",
"args": [
"run",
"fastmcp",
"run",
"YOUR_PATH_TO/proxy_mcp_server/proxy_mcp_server.py:proxy_mcp_server"]
}}}
```
从终端启动：
```
fastmcp run ./proxy_mcp_server/proxy_mcp_server.py:proxy_mcp_server
```
# RAG 推理：交互式启动
- **是什么**：用于向 Qdrant 中的文档集合提问的控制台助手，并具有额外的排名和 LLM 响应生成。
- **位置**：`rag_inference/RAG workflow.py`
- **初步环境变量**：使用 `QDRANT_URL`, `QDRANT_API_KEY`, `RERANK_URL`, `RERANK_MODEL`, `LLM_SERVICE_CHAT_COMPLETIONS_URL`, `LLM_SERVICE_API_KEY`, `LLM_SERVICE_MODEL`, `EMBEDDING_URL`, `EMBEDDING_MODEL`（上述在设置部分描述）。
运行（Windows PowerShell）：
```
python ".\rag_inference\RAG workflow.py" <collection_name>
```
其中 `<collection_name>` 是 Qdrant 中的集合名称。 提前通过 `proxy_mcp_server` 中的 `preprocessing_data_for_rag` 工具并传递要索引的文件列表来获取它很方便；该方法将返回创建的集合名称。
示例：
```
python ".\rag_inference\RAG workflow.py" collection_for_rag_1
```
