FastMCP项目中如何正确暴露FastAPI的Swagger文档

在FastMCP项目中，开发者经常遇到一个常见问题：当使用FastMCP.from_fastapi方法将FastAPI应用转换为MCP服务器后，原本FastAPI自带的Swagger文档接口/docs无法正常访问。本文将深入分析这一问题的原因，并提供几种可行的解决方案。

问题本质分析

FastMCP的from_fastapi方法实际上创建的是一个MCP服务器，它虽然能够暴露FastAPI应用的路由，但本质上已经不再是FastAPI应用。这种转换导致了原生FastAPI特性的丢失，包括Swagger文档接口。

解决方案一：反向挂载MCP服务器

正确的架构设计应该是将MCP服务器作为子路由挂载到主FastAPI应用中，而不是反过来。以下是实现这一架构的代码示例：

# 创建SSE传输层
sse_transport = SseServerTransport("/mcp/messages/")

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 初始化MCP服务器
    app.state.mcp = FastMCP.from_fastapi(app=app)
    # 存储SSE传输层
    app.state.sse = sse_transport

# 创建主FastAPI应用
app = FastAPI(
    openapi_url="/openapi.json",
    lifespan=lifespan,
    redirect_slashes=False
)

# 挂载MCP消息处理路由
app.router.routes.append(Mount("/mcp/messages", app=sse_transport.handle_post_message))

这种架构保持了FastAPI应用的主体地位，MCP服务器作为其子组件运行，从而保留了所有FastAPI原生功能。

解决方案二：文档增强技巧

对于需要特别说明的MCP端点，可以通过添加文档路由来增强Swagger文档的完整性：

@app.get("/mcp/messages", tags=["MCP"], include_in_schema=True)
def messages_docs():
    """
    SSE通信的消息端点
    
    此端点用于向SSE客户端发送消息。
    注意：此路由仅用于文档目的。
    实际实现由SSE传输层处理。
    """
    pass

这种方法既保持了接口文档的完整性，又不会影响实际的功能实现。

解决方案三：SSE端点实现

对于需要建立SSE连接的端点，可以这样实现：

@app.get("/mcp/sse", tags=["MCP"])
async def handle_sse(request: Request):
    """
    SSE端点，连接到MCP服务器
    
    此端点建立与客户端的服务器发送事件(SSE)连接，
    并将通信转发到模型上下文协议服务器。
    """
    mcp = request.app.state.mcp
    async with sse_transport.connect_sse(request.scope, request.receive, request._send) as (
        read_stream,
        write_stream,
    ):
        await mcp._mcp_server.run(
            read_stream,
            write_stream,
            mcp._mcp_server.create_initialization_options(),
        )

最佳实践建议

1. 架构设计：始终将MCP服务器作为FastAPI应用的子组件，而不是相反
2. 文档完整性：为所有特殊端点添加文档路由，保持API文档的完整性
3. 生命周期管理：合理利用FastAPI的生命周期管理机制初始化MCP相关组件
4. 路由组织：使用清晰的路由前缀(如/mcp)组织MCP相关端点

通过以上方法，开发者可以在使用FastMCP的同时，仍然享受FastAPI提供的完整功能，包括Swagger文档接口。这种架构既保持了功能的完整性，又遵循了良好的设计原则。