零代码实现文件传输：FastAPI-MCP打造MCP文件处理工具

你是否还在为FastAPI项目手动配置文件上传下载功能而烦恼？是否希望有一种方式能自动将文件处理端点转换为模型上下文协议（MCP）工具？本文将带你通过FastAPI-MCP工具，零配置实现文件上传下载功能的MCP工具转换，无需复杂代码即可让你的FastAPI应用支持模型调用。

项目概述

FastAPI-MCP是一个零配置工具，用于自动将FastAPI端点公开为模型上下文协议（MCP）工具。通过简单的初始化和挂载操作，即可将现有的FastAPI应用转换为支持MCP协议的服务，使AI模型能够直接调用你的API端点。

项目核心模块结构如下：

• 核心逻辑：fastapi_mcp/server.py
• 认证代理：fastapi_mcp/auth/proxy.py
• 传输协议：fastapi_mcp/transport/
• 类型定义：fastapi_mcp/types.py
• 官方文档：docs/getting-started/quickstart.mdx

快速开始：基础MCP服务搭建

初始化MCP服务器

要将文件处理功能转换为MCP工具，首先需要在FastAPI应用中初始化MCP服务器。以下是基础用法示例：

# 导入必要的模块
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# 创建FastAPI应用实例
app = FastAPI(title="文件处理API", description="支持文件上传下载的FastAPI应用")

# 初始化MCP服务器
mcp = FastApiMCP(
    app,
    name="文件处理MCP服务",
    description="将文件上传下载端点转换为MCP工具",
    headers=["authorization", "content-type"]  # 配置需要转发的请求头
)

# 挂载MCP端点
mcp.mount_http(mount_path="/mcp")  # 将MCP服务挂载到/mcp路径

# 启动应用（生产环境使用uvicorn）
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

完整示例代码

官方提供了基础用法示例，展示了如何快速将FastAPI应用转换为MCP服务：

# 基础用法示例：examples/01_basic_usage_example.py
from examples.shared.apps.items import app  # 导入FastAPI应用
from examples.shared.setup import setup_logging

from fastapi_mcp import FastApiMCP

setup_logging()

# 添加MCP服务器到FastAPI应用
mcp = FastApiMCP(app)

# 挂载MCP服务器到FastAPI应用
mcp.mount_http()

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

文件上传功能实现

添加文件上传端点

首先，在FastAPI应用中实现文件上传功能。以下是一个简单的文件上传端点示例：

from fastapi import UploadFile, File
from fastapi.responses import JSONResponse
import os
from uuid import uuid4

# 创建上传文件保存目录
UPLOAD_DIR = "uploads"
os.makedirs(UPLOAD_DIR, exist_ok=True)

@app.post("/upload", tags=["files"], operation_id="upload_file")
async def upload_file(file: UploadFile = File(...)):
    """
    上传文件到服务器
    
    - **file**: 要上传的文件
    - 返回文件ID和访问URL
    """
    # 生成唯一文件名
    file_id = str(uuid4())
    file_ext = os.path.splitext(file.filename)[1]
    file_path = os.path.join(UPLOAD_DIR, f"{file_id}{file_ext}")
    
    # 保存文件
    with open(file_path, "wb") as f:
        f.write(await file.read())
    
    # 返回文件信息
    return {
        "file_id": file_id,
        "file_name": file.filename,
        "content_type": file.content_type,
        "file_path": file_path,
        "download_url": f"/download/{file_id}"
    }

自动转换为MCP工具

添加文件上传端点后，FastAPI-MCP会自动将其转换为MCP工具。转换逻辑在fastapi_mcp/openapi/convert.py中实现，主要通过convert_openapi_to_mcp_tools函数完成OpenAPI schema到MCP工具的转换。

MCP服务器初始化时会自动扫描所有FastAPI端点，包括我们添加的文件上传端点，并将其转换为可被AI模型调用的工具。

文件下载功能实现

添加文件下载端点

接下来实现文件下载功能，与上传功能配合使用：

from fastapi import HTTPException
from fastapi.responses import FileResponse
import os

@app.get("/download/{file_id}", tags=["files"], operation_id="download_file")
async def download_file(file_id: str):
    """
    从服务器下载文件
    
    - **file_id**: 上传文件时返回的文件ID
    - 返回文件下载响应
    """
    # 在实际应用中，应该从数据库查询file_id对应的文件路径
    # 这里简化处理，直接遍历上传目录查找
    file_path = None
    for filename in os.listdir(UPLOAD_DIR):
        if filename.startswith(file_id):
            file_path = os.path.join(UPLOAD_DIR, filename)
            break
    
    if not file_path or not os.path.exists(file_path):
        raise HTTPException(status_code=404, detail="文件不存在")
    
    # 返回文件下载响应
    return FileResponse(
        path=file_path,
        filename=os.path.basename(file_path),
        media_type="application/octet-stream"
    )

MCP工具调用流程

当文件上传和下载端点添加完成后，FastAPI-MCP会自动将它们转换为MCP工具。MCP工具调用流程如下：

1. AI模型通过MCP协议发送工具调用请求
2. MCP服务器接收请求并验证权限（如配置了认证）
3. 请求被转发到对应的FastAPI端点（上传或下载）
4. 端点处理请求并返回结果
5. MCP服务器将结果格式化为MCP协议响应返回给AI模型

核心处理逻辑在fastapi_mcp/server.py中的handle_call_tool方法实现，该方法负责调用相应的工具并返回处理结果。

高级配置

完整响应模式

如果需要在MCP工具描述中包含完整的响应模式，可以在初始化MCP服务器时设置相关参数：

mcp = FastApiMCP(
    app,
    name="文件处理MCP服务",
    describe_all_responses=True,  # 包含所有可能的响应模式
    describe_full_response_schema=True  # 包含完整的响应JSON模式
)

此配置会影响工具描述的生成，相关实现可参考examples/02_full_schema_description_example.py。

认证配置

对于需要保护的文件处理端点，可以配置MCP认证。以下是一个简单的认证配置示例：

from fastapi_mcp.auth.proxy import AuthConfig

# 配置认证
auth_config = AuthConfig(
    provider_url="https://your-auth-provider.com",
    client_id="your-client-id",
    scopes=["file:read", "file:write"]
)

# 使用认证配置初始化MCP服务器
mcp = FastApiMCP(
    app,
    auth_config=auth_config,
    headers=["authorization", "x-api-key"]  # 转发认证相关请求头
)

认证代理逻辑在fastapi_mcp/auth/proxy.py中实现，支持多种认证方式。

传输协议选择

FastAPI-MCP支持多种传输协议，包括HTTP和SSE（Server-Sent Events）。默认使用HTTP协议，也可以配置为SSE协议：

# 挂载SSE传输协议的MCP服务
mcp.mount_sse(mount_path="/mcp/sse")

SSE协议实现位于fastapi_mcp/transport/sse.py，适用于需要持续通信的场景。

测试与验证

查看MCP工具列表

启动应用后，可以通过访问/mcp/tools端点查看所有转换后的MCP工具列表，包括我们添加的文件上传和下载工具。

调用MCP工具

使用curl命令测试文件上传MCP工具：

curl -X POST "http://localhost:8000/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "upload_file",
    "parameters": {
      "file": "@/path/to/your/file.txt"
    }
  }'

总结与展望

通过FastAPI-MCP，我们可以轻松地将FastAPI应用的文件上传下载功能转换为MCP工具，无需复杂配置即可实现AI模型与文件处理功能的集成。这种零代码转换方式极大地简化了AI模型调用外部工具的流程，为构建AI驱动的应用提供了便利。

未来，FastAPI-MCP可能会支持更多的传输协议和认证方式，进一步扩展其适用场景。如果你有特定的需求，可以通过CONTRIBUTING.md了解如何为项目贡献代码。

要获取更多信息和高级用法，请参考以下资源：

• 完整示例代码：examples/
• 高级配置文档：docs/advanced/
• 自定义配置指南：docs/configurations/customization.mdx