阿里云盘 MCP 服务 (AliDrive MCP Server) - 架构与功能设计

俯首为牛 2026-05-22 Hoeking 手机阅读

阿里云盘 MCP 服务 (AliDrive MCP Server) - 架构与功能设计

image-20260522111459504

1. 项目概述

1.1 项目目的

开发一个基于 FastMCP 框架的 Model Context Protocol (MCP) 服务器。该服务器作为桥梁，允许大模型应用（如 Hermes）通过标准协议对用户的阿里云盘进行远程文件管理（查询、上传、下载）。

1.2 核心技术栈

  • 语言: Python 3.12
  • 通信框架: FastMCP (基于 Starlette/ASGI 的高性能 MCP 实现)
  • 云盘驱动: aligo (阿里云盘非官方 API 库)
  • 配置管理: Pydantic Settings (环境变量注入)
  • 部署方式: Docker + Docker Compose

1.3 系统架构流

[Hermes / AI Agent] <---> [FastMCP Server] <---> [阿里云盘API]
        |                       |                       |
    JSON-RPC Call        1. 鉴权与实例管理        1. 扫码/Token刷新
    (Tool Invocation)    2. 路由业务请求          2. 文件CRUD操作
                         3. 异常处理与告警        3. 发送邮件通知
                         4. 本地文件中转

2. 功能模块设计 (MCP Tools)

服务器需对外暴露 3 个标准 MCP Tool。所有请求均基于 aligo 库实现。

2.1 工具一：查询文件列表 (list_files)

  • 功能描述: 获取阿里云盘指定路径下的文件与文件夹列表。
  • 输入参数 (JSON):
    • path (string, required): 云盘绝对路径，例如 /backup/logs。根目录用 /。
  • 输出返回 (JSON Array):
    • 成功: 返回文件对象列表，包含 name, file_id, type (file/folder), size, updated_at。
    • 失败: 抛出 MCP 标准错误异常。

2.2 工具二：上传文件 (upload_file)

  • 功能描述: 将本地文件或二进制流上传至阿里云盘指定目录。
  • 输入参数 (JSON):
    • local_path (string, required): 待上传文件在 MCP 服务器容器内的绝对路径。
    • remote_folder_path (string, required): 云盘目标文件夹路径，例如 /backups。
  • 输出返回 (JSON Object):
    • success (boolean): 是否成功。
    • file_id (string): 上传成功后的文件 ID。
    • message (string): 状态描述。

2.3 工具三：下载文件 (download_file)

  • 功能描述: 从阿里云盘下载指定文件到本地（容器内环境）。
  • 输入参数 (JSON):
    • remote_path (string, required): 云盘文件的绝对路径，例如 /docs/report.pdf。
    • local_path (string, required): 下载到容器内的目标绝对路径。
  • 输出返回 (JSON Object):
    • success (boolean): 是否成功。
    • local_path (string): 实际保存的本地路径。
    • message (string): 状态描述。

3. 核心业务流程与异常处理 (Agent 重点实现区)

3.1 阿里云盘鉴权与生命周期管理

  • 单例模式: aligo.AliPCS 实例化对象必须作为全局单例在 FastMCP 服务启动时初始化。严禁在每次 Tool 被调用时重新实例化，以防触发阿里云盘风控。
  • 配置文件持久化: aligo 默认会在 ~/.aligo 目录下生成 JSON 配置文件保存 RefreshToken。在 Docker 环境中，必须将该目录挂载到宿主机卷（Volume），确保容器重启后 Token 不丢失。

3.2 RefreshToken 过期应对策略 (关键逻辑)

由于阿里云盘的 RefreshToken 可能会被动失效，aligo 库内置了邮件通知机制。Agent 需要实现以下协同逻辑： 1. 邮件告警配置: 在实例化 aligo.AliPCS 时，必须通过环境变量动态构建 EMailConfig 对象（使用 ALIGO_NOTIFY_EMAIL）。 2. MCP 层超时与指引机制: 当 AI 调用任意 Tool 时，若底层 aligo 触发了重新登录流程（等待扫码状态），MCP 服务绝不能无限阻塞或报错。需捕获底层特定的等待异常（或利用 asyncio 的 wait_for 超时机制）。一旦判定为“等待扫码”，立即向调用方（Hermes）抛出一个特定的 MCP Error（例如 ErrorCode 1001: AUTH_REQUIRED），错误消息中明确提示用户："阿里云盘登录已过期，请检查管理员邮箱获取新的登录二维码"。

3.3 大文件最优处理策略（指挥官模式）

为防止大文件传输导致 JSON-RPC 协议阻塞、内存溢出或服务崩溃，MCP 服务只做“指挥官”，不做“苦力搬运工”： * 大文件上传: AI 需先将大文件上传至 Hermes 临时文件存储区，调用 MCP 工具时仅传递临时文件路径。MCP 服务将该本地文件交由 aligo 进行分片上传，完成后立即删除本地临时文件释放空间。 * 大文件下载: AI 发起下载请求，MCP 服务调用 aligo.download_file 将文件拉取至容器内部固定文件夹（如 /app/downloads）。下载完成后，绝不返回文件内容，仅返回文件在容器内的绝对路径供 AI 通过自身文件系统读取工具获取。

3.4 磁盘空间哨兵机制

鉴于“指挥官模式”会产生本地文件中转，为避免频繁下载大文件撑满 Docker 容器磁盘，需在每次下载/上传工具执行开头加入“磁盘空间哨兵”逻辑： 1. 获取当前容器剩余磁盘空间。 2. 若剩余空间低于阈值（如 1GB），强制清理 /app/downloads 目录下最早访问/修改的几个文件。 3. 空间释放完毕后，再继续执行当前的文件 I/O 任务，确保服务长期无人值守稳定运行。

4. 配置管理 (Pydantic Settings)

为方便 Docker 部署和环境切换，需使用 pydantic_settings.BaseSettings 进行配置管理。该模块会自动从系统环境变量或同级目录的 .env 文件中读取配置，实现代码与配置的完全解耦。

定义的配置项包含： * ALIGO_NOTIFY_EMAIL: 阿里云盘登录过期通知邮箱。 * MCP_SERVER_PORT: MCP 服务运行端口（默认 11099）。 * DOWNLOAD_PATH: 容器内部下载文件存放目录（默认 /app/downloads）。 * DISK_SPACE_THRESHOLD: 磁盘空间告警阈值（默认 1GB）。

5. 部署规范 (Docker)

Agent 需要编写 Dockerfile 和 docker-compose.yml 来实现一键部署。

5.1 环境变量配置 (.env)

# 服务运行端口
MCP_SERVER_PORT=11099

# 阿里云盘登录过期通知邮箱
ALIGO_NOTIFY_EMAIL=53258372@qq.com

# 挂载目录映射 (宿主机目录:容器内目录)
# 用于存放 aligo 配置和下载/上传的临时文件
APP_DATA_DIR=/home/app/data

5.2 Dockerfile 要求

  • 基于 python:3.12-slim。
  • 安装依赖: fastapi, uvicorn, mcp[server], aligo, python-dotenv, pydantic, psutil (用于磁盘哨兵)。
  • 暴露端口 11099。
  • 启动命令: python main.py (假设主入口文件为 main.py)。

5.3 docker-compose.yml 结构示例

version: '3.8'
services:
  aliyundrive-mcp:
    build: .
    ports:
      - "${MCP_SERVER_PORT}:11099"
    volumes:
      - ${APP_DATA_DIR}/config:/root/.aligo
      - ${APP_DATA_DIR}/storage:/app/storage
    environment:
      - ALIGO_NOTIFY_EMAIL=${ALIGO_NOTIFY_EMAIL}
    restart: unless-stopped

6. 开发交付物清单 (Agent 需生成的文件)

Agent 在完成本说明书的要求时，必须输出以下文件结构：

/aliyundrive-mcp
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example           # 务必包含 MCP_API_KEY 的示例
└── src/
    └── main.py           # 包含: 
                         # 1. FastMCP 实例与 API Key 鉴权中间件
                         # 2. 3个核心 Tools 逻辑 (list, upload, download)
                         # 3. 阿里云盘单例管理与邮件通知异常捕获

(注：本说明书为架构与功能设计，Agent 在编写 main.py 时，需自行处理具体的异常捕获代码及 FastMCP 的装饰器语法)。

这三点补充得非常棒！加入 API Key 鉴权是防君子亦防小人的安全必备手段；而明确的 Hermes 集成与触发说明，则是把一个“代码玩具”变成“真正生产力工具”的最后一公里。

我把这三点完美融合进了我们的顶层设计里。以下是为你量身定制的《附录与补充设计规范》，你可以直接将其追加到之前的说明书尾部。搞定这一套，你的 MCP 服务就可以正式“上岗”了！

附录：安全、部署与 Hermes 集成指南

7. 安全认证设计 (API Key 鉴权)

作为一个独立部署的 MCP 服务，为了防止未经授权的请求调用你的阿里云盘（比如别人扫到了你的服务端口），必须在 FastMCP 层面临加一道 API Key 鉴权防线。

7.1 鉴权逻辑实现方案

Agent 需要在 main.py中实现自定义的认证中间件（Dependency Injection）：

  1. 拦截请求：对所有传入的 MCP 请求（特别是 tools/call等写操作，或全盘拦截）进行拦截。
  2. 校验 Header：提取 HTTP 请求头中的 Authorization字段，或自定义的 X-API-Key字段。
  3. 比对常量：将提取的值与系统环境变量 MCP_API_KEY进行比对。
  4. 返回结果：
  5. 匹配成功：放行请求，执行业务逻辑。
  6. 匹配失败：立即抛出 MCP 标准错误（例如 ErrorCode 1002: UNAUTHORIZED），提示 "Invalid API Key"，拒绝执行。

7.2 配置变更

需在 pydantic_settings配置类中新增一个必填字段：

MCP_API_KEY(string, required): 客户端调用 MCP 服务所需的秘钥令牌。

8. Hermes 集成与使用指南 (User Manual)

本章节指导最终用户（你自己或你的团队成员）如何将开发好的 MCP 服务接入 Hermes 应用，并通过自然语言流畅地使用。

8.1 第一步：服务部署与启动

  1. 根据前文 docker-compose.yml配置好 .env环境变量文件（包含 MCP_API_KEY）。

  2. 在项目根目录下执行一键部署命令：

docker-compose up -d

  1. 服务将在后台运行，并监听 http://localhost:11099（或你配置的端口）。

8.2 第二步：在 Hermes 中配置 MCP 服务

Hermes 作为支持标准 MCP 协议的客户端，需要感知到这个服务的存在。通常在 Hermes 的设置中找到 MCP Servers 配置项，添加一个新的 STDIO 或 SSE 连接。

如果是通过 SSE (Server-Sent Events) 连接本地部署的服务，配置示例如下（具体以 Hermes 实际 UI 为准）：

{
  "aliyundrive": {
    "url": "http://localhost:11099/sse",
    "headers": {
      "X-API-Key": "你设置的超级秘钥"
    }
  }
}

(注：保存配置后，Hermes 应该会提示“成功连接 AliDrive MCP”)。

8.3 第三步：在 Hermes 对话框中触发使用

配置成功后，你就可以在 Hermes 的对话框中，通过自然语言直接驱使 AI 调用阿里云盘了！

触发方式示例 1：查询文件

你：@AliDrive 帮我看看我网盘根目录下都有哪些文件和文件夹？

AI 行为：识别意图 -> 调用 list_files工具 (path=/) -> 格式化返回结果并呈现给你。

触发方式示例 2：下载文件到本地（容器中转）

你：@AliDrive 帮我把网盘路径 /docs/项目汇报.pdf 下载下来，我想看一下。

AI 行为：识别意图 -> 检查磁盘空间 -> 调用 download_file工具 -> 返回下载成功信息及容器内路径 -> AI 通过自身权限读取该文件内容并展示给你。

触发方式示例 3：上传文件

你：@AliDrive 帮我把我刚生成的这个代码片段（附带代码片段或本地路径），上传到网盘的 /backup/codes 目录下。

AI 行为：识别意图 -> 调用 upload_file工具 -> 返回上传成功的状态。