Skip to content

user_guide.md

Latest commit

 

History

History
224 lines (148 loc) · 6.08 KB

user_guide.md

File metadata and controls

224 lines (148 loc) · 6.08 KB
Raw

MCP服务器使用指南

简介

MCP（多功能计算平台）服务器是一个功能强大的后端服务，支持文件访问、数据库连接、API集成和向量数据库访问等多种功能。本服务器设计用于与大型语言模型（如通义千问Qwen）集成，为AI应用提供强大的后端支持。

目录

  1. 安装指南
  2. 功能概述
  3. API文档
  4. 通义千问(Qwen)集成
  5. 示例说明
  6. 常见问题

安装指南

前提条件

  • Docker 和 Docker Compose
  • 互联网连接（用于拉取Docker镜像）

安装步骤

  1. 克隆项目代码：
git clone <项目仓库URL>
cd mcp_server
  1. 使用Docker Compose启动服务：
docker-compose -f docker/docker-compose.yml up -d
  1. 验证服务是否正常运行：
curl http://localhost:8000/health

如果返回 {"status":"healthy"}，则表示服务已成功启动。

配置选项

MCP服务器支持通过环境变量进行配置。主要配置选项包括：

环境变量 描述 默认值
MCP_HOST 服务器监听地址 0.0.0.0
MCP_PORT 服务器监听端口 8000
MCP_DEBUG 是否启用调试模式 false
MCP_FILE_STORAGE_PATH 文件存储路径 /app/storage
MCP_VECTOR_DB_PATH 向量数据库路径 /app/vector_db
MCP_MONGODB_URI MongoDB连接URI mongodb://mongodb:27017
MCP_MONGODB_DB_NAME MongoDB数据库名称 mcp_server_db
MCP_API_KEY_REQUIRED 是否启用API密钥验证 false

可以在docker-compose.yml文件中的environment部分修改这些配置。

功能概述

MCP服务器提供以下核心功能：

1. 文件访问

  • 文件上传：支持上传各种类型的文件
  • 文件下载：通过文件ID下载文件
  • 文件列表：获取所有已上传文件的列表
  • 文件删除：删除指定的文件

2. 数据库连接

  • 文档存储：将数据存储到MongoDB数据库
  • 文档查询：根据条件查询文档
  • 文档更新：更新现有文档
  • 文档删除：删除指定文档

3. API集成

  • API请求代理：通过MCP服务器发送HTTP请求到外部API
  • 支持各种HTTP方法（GET、POST、PUT、DELETE等）
  • 支持请求参数、请求体和自定义头部

4. 向量数据库访问

  • 向量存储：存储高维向量数据和相关元数据
  • 向量搜索：基于相似度搜索向量
  • 向量删除：删除指定的向量记录

API文档

启动服务后，可以通过访问 http://localhost:8000/docs 查看完整的API文档（Swagger UI）。

主要API端点

文件访问

  • POST /files/upload：上传文件
  • GET /files/list：获取文件列表
  • GET /files/download/{file_id}：下载文件
  • DELETE /files/{file_id}：删除文件

数据库连接

  • POST /database/insert：插入文档
  • GET /database/find/{collection}：查询文档
  • PUT /database/update/{collection}/{record_id}：更新文档
  • DELETE /database/delete/{collection}/{record_id}：删除文档
  • GET /database/collections：获取集合列表

API集成

  • POST /api/request：发送API请求

向量数据库访问

  • POST /vector/insert：插入向量
  • POST /vector/search：搜索向量
  • DELETE /vector/{collection}/{vector_id}：删除向量
  • GET /vector/collections：获取向量集合列表

通义千问集成

MCP服务器专为与通义千问(Qwen)等大型语言模型集成而设计。我们提供了一个Python客户端库，简化了通义千问与MCP服务器的交互。

客户端安装

# 将客户端文件复制到您的项目中
cp examples/qwen_client.py /path/to/your/project/

基本用法

from qwen_client import QwenMCPClient

# 初始化客户端
client = QwenMCPClient("http://localhost:8000")

# 上传文件
file_info = client.upload_file("example.txt")

# 存储向量
vector = [0.1, 0.2, 0.3] * 512  # 1536维向量
metadata = {"text": "这是一个示例文本", "source": "通义千问"}
vector_info = client.store_vector("qwen_embeddings", vector, metadata)

# 搜索向量
query_vector = [0.15, 0.25, 0.35] * 512  # 1536维向量
search_results = client.search_vector("qwen_embeddings", query_vector, top_k=3)

# 存储文档
document = {
    "title": "通义千问示例",
    "content": "这是通义千问生成的示例内容",
    "tags": ["AI", "NLP", "大模型"]
}
doc_info = client.store_document("qwen_documents", document)

# 调用外部API
api_response = client.call_api(
    url="https://api.example.com/data",
    method="GET",
    params={"query": "通义千问"}
)

示例说明

项目包含以下示例代码：

1. 基本使用示例

examples/qwen_example.py 展示了如何使用QwenMCPClient与MCP服务器交互，包括文件上传、向量操作、数据库操作和API调用等示例。

运行示例：

python examples/qwen_example.py

2. 测试脚本

test_server.py 是一个全面的测试脚本，用于测试MCP服务器的所有功能模块。

运行测试：

python test_server.py

test_qwen_client.py 用于测试通义千问客户端与MCP服务器的集成。

运行测试：

python test_qwen_client.py

常见问题

Q: 如何更改服务器端口？

A: 在docker-compose.yml文件中修改ports部分和MCP_PORT环境变量。

Q: 如何启用API密钥验证？

A: 在docker-compose.yml文件中将MCP_API_KEY_REQUIRED设置为true，并添加MCP_API_KEYS环境变量，格式为"service1:key1,service2:key2"。

Q: 数据存储在哪里？

A: 文件存储在Docker卷mcp_storage中，向量数据库存储在mcp_vector_db中，MongoDB数据存储在mongodb_data中。这些卷确保数据在容器重启后仍然保留。

Q: 如何备份数据？

A: 可以使用Docker卷备份命令备份数据卷，或者使用MongoDB的备份工具备份数据库。

Q: 如何扩展MCP服务器的功能？

A: 可以通过添加新的模块到src/modules/目录，并在src/modules/__init__.py中注册新模块来扩展功能。