构建基于 FastAPI 的 MCP 流式服务器:从协议设计到多端实现

基于FastAPI与MCP协议构建标准化AI工具后端:从原理到实践 在现代AI应用开发中,API设计与协议标准化是提升系统可维护性和扩展性的关键。通过定义清晰的接口规范和数据交换格式,不同组件能够高效协同工作。模型上下文协议(MCP)作为一种新兴的开放协议,为AI助手提供了标准化访问外部工具和数据源的能力。其技术价值在于解耦工具实现与客户端交互,使开发者能够专注于业务逻辑而非通信细节。结合FastAPI框架的异步处理、自动验证和文档生成特性,可以快速构建生产就绪的MCP服务器。这种组合特别适用于需要将企业内部工具或数据源安全暴露给AI助手的场景,例如智能代理后端开发。通过P 阅读详情

1. 为什么你需要一个流式 MCP 服务器?

如果你正在开发一个AI应用,比如一个智能聊天助手、一个代码生成工具,或者一个需要实时反馈的文档分析系统,你肯定遇到过这样的问题:用户问了一个复杂的问题,模型吭哧吭哧“思考”了十几秒,最后才吐出一个完整的答案。在这段等待时间里,用户盯着空白的屏幕,心里可能在想:“是不是卡了?还是出错了?” 这种体验非常糟糕。

我几年前做第一个AI项目时,就踩过这个坑。当时我们的后端用同步接口,模型生成一段长文本需要近20秒,前端页面就跟死了一样。后来我们引入了流式响应,让答案像打字一样一个字一个字地“流”出来,哪怕总时间没变,用户的感知体验却好了十倍不止——他们能立刻看到系统在“工作”,有反馈,心里就踏实。

这就是 Streamable HTTP 的核心价值。它不是一项高深莫测的技术,你可以把它理解为服务器和客户端之间的一条“数据水管”。服务器这边一边处理(比如模型一边推理),一边把处理好的片段通过这根水管实时推送给客户端。客户端则像接水一样,收到一段就展示一段。对于需要长时间运行或实时更新的任务,这几乎是提升用户体验的必选项。

而 MCP(Model Context Protocol),你可以把它看作在这根“数据水管”上传输的“货物包装标准”。它定义了一套规则,约定了客户端和服务器之间应该如何打招呼(初始化)、如何发送指令(方法调用)、如何报告进度、如何传递上下文信息。有了这个协议,你的AI服务就不再是一个黑盒,客户端能清楚地知道当前处理状态,也能更结构化地与模型交互。

所以,把 FastAPI、Streamable HTTP 和 MCP 结合起来,你得到的就是一个现代化、高性能、体验优秀的实时AI服务后端架构。FastAPI 凭借其原生的异步支持和简洁的语法,是实现这类流式服务的绝佳选择。接下来,我就带你从协议设计开始,一步步搭建一个完整的、支持多端接入的流式 MCP 服务器。

2. 动手之前:理解核心协议与设计思路

在敲代码之前,我们得先把“游戏规则”定好。直接照搬别人的协议可能不适合你的业务,所以我们先从设计自己的 MCP 协议开始。别担心,这并不复杂,我们可以参考 JSON-RPC 2.0 的格式,因为它结构清晰、广泛支持。

我们的 MCP 协议主要围绕几个核心交互展开:

  1. 会话初始化:客户端和服务器建立连接,互相告知“我能做什么”(能力协商)。
  2. 方法调用:客户端请求服务器执行某个任务,比如 generateText、analyzeDocument。
  3. 流式响应:对于耗时任务,服务器通过 Server-Sent Events (SSE) 流式返回中间结果和最终结果。
  4. 进度跟踪:在流式响应中,携带进度令牌,让客户端能精确知道任务处理到了哪一步。
  5. 会话管理:通过一个唯一的 session_id 来关联同一用户的所有请求,维持对话上下文。

这里我画一个简单的交互流程图来帮你理解(我们用文字描述):客户端首先发送一个 initialize 请求,服务器创建一个会话并返回 session_id。之后客户端的每个请求都带上这个 session_id。当客户端调用一个如 generate 的流式方法时,服务器会返回一个 SSE 流的端点地址,客户端监听这个流,服务器则把生成的文本片段、中间状态或进度信息,源源不断地推送到这个流中。

一个典型的请求体看起来是这样的:

{
  "jsonrpc": "2.0",
  "id": 123,
  "method": "generate",
  "params": {
    "prompt": "请用Python写一个快速排序函数",
    "stream": true,
    "_meta": {
      "progressToken": "progress_abc"
    }
  }
}

响应可能是立即返回的 JSON,也可能是开启一个流。对于流式响应,我们选择 SSE 而不是 WebSocket,原因在于 SSE 是纯粹的服务器推送,基于 HTTP,更简单轻量,自动处理重连,对于这种单向数据流(服务器->客户端)的场景非常适合。

设计协议时,一个我踩过的坑是版本管理。一定要在初始化请求里带上 protocolVersion 字段。这样当你的协议未来升级时,服务器可以识别旧版客户端,并做出兼容性处理,避免直接报错导致服务不可用。

3. 搭建 FastAPI 服务器核心骨架

理论说得差不多了,我们开始动真格的。首先创建一个新的项目目录,并设置虚拟环境,这是保持环境干净的好习惯。

mkdir mcp-streaming-server
cd mcp-streaming-server
python -m venv venv
# 激活虚拟环境
# Windows: venv\Scripts\activate
# Mac/Linux: source venv/bin/activate

接下来安装核心依赖。FastAPI 是我们的框架,Uvicorn 是高性能的异步服务器,pydantic 用于数据验证(FastAPI 自带,但明确一下有好处)。

pip install fastapi uvicorn pydantic

现在,创建 server.py 文件,我们来构建服务器的核心。第一步是基础的 FastAPI 应用和跨域处理。因为我们的客户端很可能是独立的前端应用,所以必须处理 CORS。

from fastapi import FastAPI, Request, HTTPException, Depends
from fastapi.responses import StreamingResponse, JSONResponse
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from typing import Optional, Dict, Any
import asyncio
import uuid
import json
import time

app = FastAPI(title="MCP Streaming Server", version="1.0.0")

# 关键:配置CORS,允许前端访问
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 生产环境应替换为具体的前端域名
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
    expose_headers=["Mcp-Session-Id"]  # 允许前端JS读取这个自定义头
)

这里有个细节:expose_headers 非常重要。默认情况下,浏览器的 JavaScript 只能访问一些基本的响应头(如Content-Type)。如果我们不把 Mcp-Session-Id 暴露出来,前端即使收到了,也无法通过 response.headers.get('Mcp-Session-Id') 读到它,会话管理就会失败。

接下来,我们需要一个地方来存储会话状态。在真实的生产环境中,你可能会用 Redis 或数据库。但为了演示,我们先用一个内存字典。注意,这个字典需要是线程安全或异步环境安全的,这里简单处理。

# 内存中的会话存储(生产环境请使用Redis等)
sessions: Dict[str, Dict[str, Any]] = {}

# Pydantic模型,用于定义请求/响应结构
class RPCRequest(BaseModel):
    jsonrpc: str = "2.0"
    id: Optional[int] = None
    method: str
    params: Optional[Dict[str, Any]] = None

class InitializeParams(BaseModel):
    protocolVersion: str
    capabilities: Dict[str, Any]
    clientInfo: Dict[str, str]

定义数据模型能让 FastAPI 自动帮我们做请求验证和文档生成,减少很多低级错误。现在,让我们实现第一个核心端点:初始化。

4. 实现会话管理与初始化端点

初始化是握手环节。客户端告诉服务器:“嗨,我来了,这是我的协议版本和能力。” 服务器则回复:“好的,这是你的会话ID,这是我的能力。”

我们创建一个 /initialize 的 POST 端点。

@app.post("/initialize")
async def initialize_session(request: Request, rpc_req: RPCRequest):
    if rpc_req.method != "initialize":
        raise HTTPException(status_code=400, detail="Method must be 'initialize'")

    params = rpc_req.params
    if not params:
        raise HTTPException(status_code=400, detail="Missing params")

    # 这里可以校验 protocolVersion,做版本兼容逻辑
    client_version = params.get("protocolVersion", "unknown")
    print(f"Client connected with version: {client_version}")

    # 生成唯一的会话ID
    session_id = str(uuid.uuid4())
    # 初始化会话存储,可以存放用户上下文、模型状态等
    sessions[session_id] = {
        "created_at": time.time(),
        "client_info": params.get("clientInfo", {}),
        "context": []  # 用于存储对话上下文
    }

    # 构建成功响应
    response_data = {
        "jsonrpc": "2.0",
        "id": rpc_req.id,
        "result": {
            "sessionId": session_id,
            "serverInfo": {
                "name": "MCP-Streaming-Server",
                "version": "1.0",
                "protocolVersion": "2024-11-05"
            },
            "capabilities": {  # 告诉客户端服务器支持什么
                "streaming": True,
                "methods": ["generate", "analyze", "chat"],
                "supportsProgress": True
            }
        }
    }
    # 关键:将会话ID放在响应头中返回
    return JSONResponse(content=response_data, headers={"Mcp-Session-Id": session_id})

你可能注意到,我们把 session_id 放在了响应头里,而不是响应体里。这是一种常见的 RESTful 实践,尤其是对于这种“会话”概念的资源。客户端在后续所有请求中,都需要在 Mcp-Session-Id 头里带上这个 ID。

那如果客户端没带会话ID就访问其他接口怎么办?我们需要一个依赖项来校验它。

from fastapi import Header

async def get_session(session_id: Optional[str] = Header(None, alias="Mcp-Session-Id")):
    if not session_id:
        raise HTTPException(status_code=401, detail="Mcp-Session-Id header is required")
    if session_id not in sessions:
        raise HTTPException(status_code=404, detail="Session not found or expired")
    return session_id, sessions[session_id]

@app.post("/rpc")
async def handle_rpc(request: Request, session_info: tuple = Depends(get_session)):
    session_id, session_data = session_info
    # 获取原始的JSON体,因为我们可能要根据method动态处理
    body = await request.json()
    method = body.get("method")

    # 根据不同的方法路由到不同的处理逻辑
    if method == "generate":
        return await handle_generate(session_id, session_data, body)
    elif method == "chat":
        return await handle_chat(session_id, session_data, body)
    else:
        raise HTTPException(status_code=404, detail=f"Method '{method}' not supported")

这样,我们就有了一个带基础会话管理的 RPC 入口。接下来,就是最精彩的部分:实现流式响应。

5. 核心魔法:实现流式响应与进度反馈

流式响应的本质,是服务器生成一个异步生成器,这个生成器每次 yield 一段数据,FastAPI 的 StreamingResponse 会把这些数据按照指定的格式(如 text/event-stream)发送给客户端。

我们来实现一个 handle_generate 函数,模拟一个流式文本生成。

async def handle_generate(session_id: str, session_data: dict, rpc_body: dict):
    params = rpc_body.get("params", {})
    prompt = params.get("prompt", "")
    stream = params.get("stream", False)
    progress_token = params.get("_meta", {}).get("progressToken")

    if not stream:
        # 非流式响应:直接处理并返回完整结果(模拟)
        await asyncio.sleep(2)  # 模拟处理耗时
        result = {"text": f"这是对‘{prompt}’的完整回复(非流式)。"}
        return JSONResponse(content={"jsonrpc": "2.0", "id": rpc_body.get("id"), "result": result})

    # 流式响应:返回一个 StreamingResponse
    async def event_stream():
        # 首先,可以立即返回一个“开始”事件
        if progress_token:
            yield f"event: progress\ndata: {json.dumps({'token': progress_token, 'value': 0})}\n\n"

        # 模拟分块生成文本
        simulated_chunks = [
            "让我们来思考一下这个问题。",
            "首先,我们需要理解核心需求。",
            "然后,我们可以分步骤实现。",
            "最后,进行测试和优化。",
            "完成!"
        ]
        
        for i, chunk in enumerate(simulated_chunks):
            await asyncio.sleep(1)  # 模拟每块生成需要1秒
            # 1. 发送进度更新
            if progress_token:
                progress = (i + 1) / len(simulated_chunks)
                yield f"event: progress\ndata: {json.dumps({'token': progress_token, 'value': progress})}\n\n"
            # 2. 发送文本块
            yield f"data: {json.dumps({'chunk': chunk, 'index': i})}\n\n"

        # 3. 发送最终结果事件,标记流结束
        yield f"event: result\ndata: {json.dumps({'text': '所有内容生成完毕。'})}\n\n"
        # 4. 可选的:发送一个 [DONE] 事件,某些前端库需要
        # yield "event: done\ndata: [DONE]\n\n"

    # 关键:media_type 必须设置为 text/event-stream
    return StreamingResponse(
        event_stream(),
        media_type="text/event-stream",
        headers={"Mcp-Session-Id": session_id, "Cache-Control": "no-cache"}
    )

这段代码里有几个关键点:

  1. event_stream 是一个异步生成器:它用 async def 定义,里面用 yield 返回数据块。await asyncio.sleep 模拟了IO或模型计算耗时。
  2. SSE 格式:每个 yield 返回的字符串必须遵循 SSE 格式。data: 开头后面跟数据,以两个换行符 \n\n 结束。我们还可以定义自定义事件,如 event: progress。
  3. 进度反馈:通过 progress 事件,携带一个 progressToken 和进度值 value,客户端可以用这个来更新进度条。
  4. 最终标记:使用 event: result 或 [DONE] 来明确告诉客户端流式传输已结束。

现在,我们的服务器已经具备了流式响应的能力。用 uvicorn server:app --reload 启动服务器,它将在 http://127.0.0.1:8000 运行。

6. 打造一个健壮的 Python 客户端

服务器准备好了,我们需要一个能对话的客户端。我们先从 Python 客户端开始,因为它常用于自动化脚本、后端服务间调用或测试。

创建一个 client.py 文件。我们将使用 httpx 库,因为它对异步和流式请求的支持比 requests 更原生、更友好。

pip install httpx
import httpx
import asyncio
import json

class MCPClient:
    def __init__(self, base_url="http://127.0.0.1:8000"):
        self.base_url = base_url
        self.session_id = None
        self.client = httpx.AsyncClient(timeout=30.0)  # 设置一个较长的超时

    async def initialize(self):
        """初始化会话"""
        init_request = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "initialize",
            "params": {
                "protocolVersion": "2024-11-05",
                "capabilities": {
                    "roots": {"listChanged": True},
                    "sampling": {}
                },
                "clientInfo": {
                    "name": "PythonDemoClient",
                    "version": "1.0.0"
                }
            }
        }
        try:
            response = await self.client.post(f"{self.base_url}/initialize", json=init_request)
            response.raise_for_status()
            result = response.json()
            self.session_id = response.headers.get("Mcp-Session-Id")
            print(f"[初始化成功] 会话ID: {self.session_id}")
            print(f"服务器能力: {result.get('result', {}).get('capabilities')}")
            return result
        except httpx.HTTPStatusError as e:
            print(f"初始化请求失败: {e}")
            return None

    async def call_method(self, method: str, params: dict, stream=False):
        """调用RPC方法"""
        if not self.session_id:
            print("错误:请先调用 initialize() 初始化会话。")
            return None

        request_data = {
            "jsonrpc": "2.0",
            "id": 2,  # ID应递增,这里简化为固定值
            "method": method,
            "params": params
        }
        headers = {"Mcp-Session-Id": self.session_id}

        if stream:
            # 流式请求:我们使用 /rpc 端点,服务器返回StreamingResponse
            async with self.client.stream('POST', f"{self.base_url}/rpc", json=request_data, headers=headers) as response:
                print(f"[流式响应开始] 状态码: {response.status_code}")
                async for line in response.aiter_lines():
                    if line.startswith('data:'):
                        # 解析SSE的data字段
                        data_str = line[5:].strip()
                        if data_str:
                            try:
                                data = json.loads(data_str)
                                print(f"收到数据块: {data}")
                            except json.JSONDecodeError:
                                print(f"收到文本块: {data_str}")
                    elif line.startswith('event:'):
                        event_type = line[6:].strip()
                        print(f"收到事件: {event_type}")
                    # 空行是SSE的分隔符,忽略
        else:
            # 非流式请求
            response = await self.client.post(f"{self.base_url}/rpc", json=request_data, headers=headers)
            result = response.json()
            print(f"[非流式响应] 结果: {result}")
            return result

    async def close(self):
        """关闭客户端连接"""
        await self.client.aclose()

async def main():
    client = MCPClient()
    try:
        # 1. 初始化
        await client.initialize()
        
        # 2. 发送一个非流式请求
        print("\n--- 测试非流式请求 ---")
        await client.call_method("chat", {"message": "你好,世界!"}, stream=False)
        
        # 3. 发送一个流式请求
        print("\n--- 测试流式请求 ---")
        await client.call_method(
            "generate",
            {
                "prompt": "解释一下人工智能",
                "stream": True,
                "_meta": {"progressToken": "test_progress_123"}
            },
            stream=True
        )
    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

这个客户端类做了几件重要的事:

  1. 封装会话管理:自动在 initialize 中获取并存储 session_id,并在后续请求的 header 中自动携带。
  2. 区分流式与非流式调用:call_method 根据 stream 参数决定如何处理。对于流式请求,它使用 httpx 的 stream 上下文管理器和 aiter_lines() 来异步迭代服务器推送的每一行数据。
  3. 解析 SSE:它按照 SSE 格式解析每一行,区分 data: 和 event:,并尝试解析 JSON 数据。

运行这个客户端,你会看到它先初始化,然后收到一个即时回复,最后开始接收流式的文本块和进度事件,体验非常直观。

7. 构建一个交互式的前端 Web 客户端

对于最终用户,一个网页界面是最直观的。我们将创建一个简单的 index.html,使用原生 JavaScript 的 EventSource API 来接收 SSE 流,并用 fetch API 发送 RPC 请求。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>MCP 流式客户端演示</title>
    <style>
        * { box-sizing: border-box; }
        body { font-family: 'Segoe UI', system-ui, sans-serif; margin: 0; padding: 20px; background: #f5f7fa; color: #333; }
        .container { max-width: 900px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 6px 16px rgba(0,0,0,0.08); padding: 30px; }
        h1 { color: #2d3748; border-bottom: 2px solid #4299e1; padding-bottom: 10px; }
        .control-panel { background: #edf2f7; padding: 20px; border-radius: 8px; margin-bottom: 25px; }
        .btn { padding: 12px 24px; margin: 0 10px 10px 0; border: none; border-radius: 6px; cursor: pointer; font-weight: 600; transition: all 0.2s; }
        .btn-primary { background: #4299e1; color: white; }
        .btn-primary:hover { background: #3182ce; }
        .btn-success { background: #48bb78; color: white; }
        .btn-success:hover { background: #38a169; }
        .btn-danger { background: #f56565; color: white; }
        .btn-danger:hover { background: #e53e3e; }
        .input-group { margin-bottom: 15px; }
        label { display: block; margin-bottom: 5px; font-weight: 500; }
        input[type="text"], textarea { width: 100%; padding: 10px; border: 1px solid #cbd5e0; border-radius: 6px; font-size: 16px; }
        textarea { height: 100px; resize: vertical; font-family: monospace; }
        .status { padding: 15px; border-radius: 6px; margin: 15px 0; }
        .status-info { background: #bee3f8; color: #2c5282; }
        .status-error { background: #fed7d7; color: #c53030; }
        .messages { border: 1px solid #e2e8f0; border-radius: 8px; padding: 20px; max-height: 500px; overflow-y: auto; background: #fafafa; }
        .message { padding: 12px 16px; margin-bottom: 10px; border-left: 4px solid #4299e1; background: white; border-radius: 4px; }
        .message.server { border-left-color: #48bb78; }
        .message.event { border-left-color: #ed8936; }
        .progress-bar { width: 100%; height: 8px; background: #e2e8f0; border-radius: 4px; overflow: hidden; margin-top: 5px; }
        .progress-fill { height: 100%; background: #4299e1; width: 0%; transition: width 0.3s ease; }
    </style>
</head>
<body>
    <div class="container">
        <h1>🤖 MCP 流式交互演示</h1>
        <p>这是一个与后台 FastAPI MCP 服务器交互的演示界面。点击“初始化会话”开始。</p>

        <div class="control-panel">
            <div class="input-group">
                <label for="promptInput">输入你的请求:</label>
                <textarea id="promptInput" placeholder="例如:请用Python写一个二分查找算法...">请介绍一下你自己。</textarea>
            </div>
            <button class="btn btn-primary" onclick="initializeSession()">初始化会话</button>
            <button class="btn btn-success" onclick="sendMessage(false)">发送请求(非流式)</button>
            <button class="btn btn-success" onclick="sendMessage(true)">发送请求(流式)</button>
            <button class="btn btn-danger" onclick="closeSession()">关闭会话</button>
            <div id="progressContainer" style="display:none; margin-top:15px;">
                <div>处理进度:<span id="progressText">0%</span></div>
                <div class="progress-bar"><div id="progressFill" class="progress-fill"></div></div>
            </div>
        </div>

        <div id="statusArea"></div>

        <h3>消息流</h3>
        <div class="messages" id="messageArea">
            <!-- 消息会动态添加到这里 -->
        </div>
    </div>

    <script>
        const serverBaseUrl = 'http://127.0.0.1:8000';
        let currentSessionId = null;
        let eventSource = null;
        let currentProgressToken = null;

        function logMessage(content, type = 'info') {
            const messageArea = document.getElementById('messageArea');
            const msgDiv = document.createElement('div');
            msgDiv.className = `message ${type}`;
            msgDiv.innerHTML = `<strong>[${new Date().toLocaleTimeString()}]</strong> ${content}`;
            messageArea.appendChild(msgDiv);
            messageArea.scrollTop = messageArea.scrollHeight; // 自动滚动到底部
        }

        function setStatus(message, isError = false) {
            const statusArea = document.getElementById('statusArea');
            statusArea.innerHTML = `<div class="status ${isError ? 'status-error' : 'status-info'}">${message}</div>`;
        }

        function updateProgress(token, value) {
            if (token !== currentProgressToken) return;
            const percent = Math.round(value * 100);
            document.getElementById('progressText').textContent = `${percent}%`;
            document.getElementById('progressFill').style.width = `${percent}%`;
            document.getElementById('progressContainer').style.display = 'block';
        }

        async function initializeSession() {
            setStatus('正在初始化会话...');
            const initRequest = {
                jsonrpc: "2.0",
                id: 1,
                method: "initialize",
                params: {
                    protocolVersion: "2024-11-05",
                    capabilities: { streaming: true },
                    clientInfo: { name: "WebDemoClient", version: "1.0.0" }
                }
            };
            try {
                const resp = await fetch(`${serverBaseUrl}/initialize`, {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify(initRequest)
                });
                if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
                const data = await resp.json();
                currentSessionId = resp.headers.get('Mcp-Session-Id');
                setStatus(`会话初始化成功!会话ID: ${currentSessionId}`);
                logMessage(`会话已建立。服务器信息: ${JSON.stringify(data.result.serverInfo)}`, 'server');
                // 初始化后可以开始监听SSE(如果需要)
                // startSSEListener();
            } catch (error) {
                setStatus(`初始化失败: ${error.message}`, true);
            }
        }

        async function sendMessage(useStream = false) {
            if (!currentSessionId) {
                setStatus('请先初始化会话!', true);
                return;
            }
            const prompt = document.getElementById('promptInput').value.trim();
            if (!prompt) {
                setStatus('请输入请求内容!', true);
                return;
            }

            const method = useStream ? 'generate' : 'chat';
            const requestId = Date.now(); // 简单生成唯一ID
            const progressToken = useStream ? `progress_${requestId}` : null;
            currentProgressToken = progressToken;

            const requestBody = {
                jsonrpc: "2.0",
                id: requestId,
                method: method,
                params: {
                    prompt: prompt,
                    stream: useStream,
                    ...(useStream && { _meta: { progressToken: progressToken } })
                }
            };

            setStatus(`正在发送${useStream ? '流式' : ''}请求...`);
            logMessage(`客户端 -> 发送请求: ${JSON.stringify(requestBody)}`);

            if (useStream) {
                // 流式请求:使用 /rpc 端点,并处理SSE
                handleStreamingRequest(requestBody);
            } else {
                // 非流式请求
                try {
                    const resp = await fetch(`${serverBaseUrl}/rpc`, {
                        method: 'POST',
                        headers: {
                            'Content-Type': 'application/json',
                            'Mcp-Session-Id': currentSessionId
                        },
                        body: JSON.stringify(requestBody)
                    });
                    const data = await resp.json();
                    setStatus('请求完成!');
                    logMessage(`服务器 -> 完整响应: ${JSON.stringify(data.result)}`, 'server');
                } catch (error) {
                    setStatus(`请求失败: ${error.message}`, true);
                }
            }
        }

        function handleStreamingRequest(requestBody) {
            // 先关闭之前的SSE连接
            if (eventSource) {
                eventSource.close();
                eventSource = null;
            }

            // 使用EventSource监听流(注意:EventSource只支持GET,我们需要用fetch模拟POST流)
            // 更通用的做法是使用fetch的ReadableStream,这里为了演示简单,我们假设服务器对GET也支持(实际项目请用fetch)
            // 这里我们改用fetch API来读取流
            fetch(`${serverBaseUrl}/rpc`, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'Mcp-Session-Id': currentSessionId
                },
                body: JSON.stringify(requestBody)
            }).then(response => {
                const reader = response.body.getReader();
                const decoder = new TextDecoder();
                function readStream() {
                    reader.read().then(({done, value}) => {
                        if (done) {
                            logMessage('流式传输结束。', 'event');
                            document.getElementById('progressContainer').style.display = 'none';
                            return;
                        }
                        const chunk = decoder.decode(value);
                        // 处理SSE格式的数据行
                        const lines = chunk.split('\n');
                        for (const line of lines) {
                            if (line.startsWith('data:')) {
                                const dataStr = line.substring(5).trim();
                                if (dataStr) {
                                    try {
                                        const data = JSON.parse(dataStr);
                                        logMessage(`数据块: ${data.chunk || JSON.stringify(data)}`, 'server');
                                    } catch {
                                        logMessage(`文本块: ${dataStr}`, 'server');
                                    }
                                }
                            } else if (line.startsWith('event:')) {
                                const eventType = line.substring(6).trim();
                                logMessage(`事件: ${eventType}`, 'event');
                            } else if (line.startsWith('{')) {
                                // 可能是不符合SSE格式的JSON直接输出(非流式回退)
                                try {
                                    const data = JSON.parse(line);
                                    logMessage(`直接响应: ${JSON.stringify(data)}`, 'server');
                                } catch(e) { /* 忽略 */ }
                            }
                        }
                        readStream(); // 继续读取下一块
                    }).catch(error => {
                        setStatus(`读取流失败: ${error.message}`, true);
                    });
                }
                readStream();
            }).catch(error => {
                setStatus(`流式请求失败: ${error.message}`, true);
            });
        }

        function closeSession() {
            if (eventSource) {
                eventSource.close();
                eventSource = null;
                logMessage('SSE连接已关闭。', 'event');
            }
            currentSessionId = null;
            setStatus('会话已重置。请重新初始化。');
            document.getElementById('progressContainer').style.display = 'none';
        }
    </script>
</body>
</html>

这个前端页面包含了所有核心功能:

  • 会话管理:初始化、关闭。
  • 双模式请求:可以选择流式或非流式发送请求。
  • 实时消息展示:用不同的颜色和样式区分服务器消息、客户端消息和事件。
  • 进度条可视化:当服务器发送 progress 事件时,页面上的进度条会实时更新。
  • 健壮的流处理:使用 fetch API 的 ReadableStream 来处理 POST 请求的流式响应,这比 EventSource(仅支持GET)更灵活通用。

将这段代码保存为 index.html,用浏览器打开(注意,由于CORS,你可能需要从 http://localhost 或 http://127.0.0.1 访问,或者使用 python -m http.server 启动一个简单的本地服务器)。点击按钮,你就能看到一个完整的、可交互的流式AI客户端了。

8. 部署、优化与踩坑指南

把代码跑起来只是第一步。要真正用在生产环境,还有不少坑要填。这里分享几个我实战中总结的经验。

部署注意事项:

  1. 生产级ASGI服务器:开发时用 uvicorn --reload 很方便,但生产环境一定要用更稳定的服务器,如 uvicorn 搭配 gunicorn(使用 uvicorn.workers.UvicornWorker),或者 hypercorn。并且要设置合适的 worker 数量。
    # 使用gunicorn的例子
    gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 server:app
    
  2. 会话存储:内存字典 sessions 在服务器重启或多进程时会丢失。生产环境必须用外部存储,比如 Redis。把 sessions 字典的操作换成 Redis 的 set/get,并设置合理的过期时间。
  3. 超时与心跳:SSE连接可能会因为代理或负载均衡器的超时设置而断开。一个常见的做法是,在流式生成器中定期发送一个注释行(以 : 开头的行,SSE规范中这是注释)作为心跳,保持连接活跃。
    async def event_stream():
        # ... 你的业务逻辑
        # 每隔15秒发送一个心跳
        heartbeat_task = asyncio.create_task(_send_heartbeat())
        try:
            # 生成数据
            yield data
        finally:
            heartbeat_task.cancel()
    async def _send_heartbeat():
        while True:
            await asyncio.sleep(15)
            yield ": heartbeat\n\n"  # SSE注释行,不会触发客户端事件
    
  4. CORS 安全:生产环境下,绝对不要使用 allow_origins=["*"]。应该配置为具体的前端域名列表。
  5. 日志与监控:记录重要的操作日志,并监控流式连接的活跃数量、错误率等指标。

常见问题与调试:

  • 前端收不到流数据:首先打开浏览器开发者工具的“网络”标签页,查看对 /rpc 的请求。响应类型应该是 text/event-stream,状态码是200。查看响应体,应该能看到持续到达的数据。如果连接很快关闭,检查服务器端代码是否有未处理的异常。
  • Mcp-Session-Id 头丢失:确保服务器响应头设置了 Access-Control-Expose-Headers: Mcp-Session-Id(FastAPI的 CORSMiddleware 通过 expose_headers 参数设置),并且前端 fetch 请求能正确读取。
  • 流式响应中途停止:检查服务器生成器函数中是否有 return 语句提前退出,或者 await 的协程被意外取消。使用 try...finally 块来确保资源清理。
  • 性能问题:如果流式生成的内容很大,注意不要一次性加载所有数据到内存再 yield。应该采用“处理一块,发送一块”的模式。对于AI文本生成,这通常意味着从模型推理循环中直接 yield 每个新生成的token。

最后,这个架构的扩展性很好。你可以很容易地在这个基础上添加更多功能,比如:

  • 身份认证:在 get_session 依赖项中加入JWT或API Key验证。
  • 速率限制:使用 slowapi 等库为不同接口设置请求频率限制。
  • 更复杂的协议:在 params 里支持文件上传、工具调用(function calling)、上下文管理等。
  • 多模型路由:根据请求参数,将请求路由到后端不同的AI模型服务。

我从一个简单的同步接口改造到现在的流式架构,最大的感受是用户体验的提升是实实在在的。虽然底层复杂度增加了,但用 FastAPI 的异步和流式响应特性来实现,代码依然能保持相当的清晰度。希望这个从协议设计到多端实现的完整 walkthrough,能帮你顺利搭建起自己的实时AI服务。如果在实现过程中遇到具体问题,多看看服务器日志和网络请求,大部分问题都能定位。

避开这3个坑!用FastAPI实现SSE流式传输的正确姿势(含MCP协议完整示例) 本文深入探讨了使用FastAPI实现SSE流式传输时常见的三个关键陷阱及其解决方案,特别针对MCP协议场景。重点剖析了CORS配置的隐藏细节、会话ID传递的多种方式对比,以及流中断的健壮性处理,并提供了包含完整会话管理和进度跟踪的MCP协议示例代码,帮助开发者构建稳定可靠的实时数据推送系统。 阅读详情

相关推荐

FastAPI与MCP协议集成:构建下一代AI应用接口的实践指南

在现代Web开发中,RESTful API和微服务架构已成为构建分布式系统的标准范式。FastAPI作为高性能的Python Web框架,凭借其异步支持、自动API文档生成和类型安全等特性,在API开发领域广受欢迎。随着AI应用的普及,如何让大语言模型(LLM)安全、高效地调用外部工具和服务成为新的技术挑战。模型上下文协议(MCP)应运而生,它定义了AI模型与外部工具交互的统一标准,类似于USB协议在硬件领域的角色。通过将FastAPI与MCP协议深度集成,开发者可以构建标准化、可插拔的AI工具服务器,实现

weixin_30920853的博客 292

深度解析 FastAPI-MCP:零配置实现 FastAPI 与 MCP 协议的无缝集成

FastAPI-MCP 是一个革命性的开源工具,它通过零配置方式将 FastAPI 端点自动转换为符合 MCP(Model Context Protocol)协议的工具,为微服务架构提供了标准化的服务通信解决方案。该工具的核心价值在于消除分布式系统中服务集成的复杂性,使开发者能够专注于业务逻辑而非通信协议的实现细节,同时保持与现有 FastAPI 生态系统的完全兼容性。 ## 核心价值主张:从

gitblog_00240的博客 454

实现一个支持 Streamable HTTP 的 MCP 服务器及客户端

在现代的 Web 开发中,实时数据传输是一个常见的需求。本文将介绍如何使用 FastAPI 实现一个支持 Streamable HTTP 的 MCP(Model Context Protocol)服务器,并提供 Python 客户端和前端客户端的实现。Streamable HTTP 是一种允许服务器以流的形式向客户端发送数据的技术。这在处理长时间运行的操作或实时数据更新时非常有用。MCP(Model Context Protocol) 是一种协议,用于在客户端和服务器之间传输模型上下文信息。

蜗牛沐雨 6712

【开发者导航】轻松将 API 转化为 MCP 工具的框架:fastapi_mcp

fastapi_mcp是一款新型框架,能快速将FastAPI接口转化为支持MCP协议的AI工具,只需几行代码即可完成转换。它完整保留原接口的鉴权、数据校验和文档功能,支持独立部署和SSE流式传输,显著降低传统API与AI工作流的集成门槛。适用于后端开发者和AI应用开发者,基于MIT开源协议免费使用,是提升开发效率的实用工具。

开发者导航 1278

FastAPI实战:5步搭建MCP协议抓包分析工具(附完整代码)

本文详细介绍了如何使用FastAPI快速搭建一个MCP协议抓包分析工具,帮助开发者透明地监控Cline等MCP Host与AI模型之间的交互过程。通过5个步骤,从原理设计、环境搭建到代码实现,提供了完整的中间人代理方案,特别适用于调试复杂的Agent工作流、分析XML格式的请求与ReAct模式,并附带了可直接运行的完整代码。

weixin_29231263的博客 345

基于MCP协议实现AI助手与Alexa语音交互的完整实践

模型上下文协议(MCP)作为连接大型语言模型与外部工具的标准接口,其核心价值在于解决了AI能力扩展的碎片化问题。通过定义统一的服务器-客户端通信规范,MCP使得像Claude这类LLM能够安全、标准化地调用外部功能,极大提升了AI应用的工程化水平。在智能家居与物联网场景中,语音交互是自然的人机接口,而亚马逊Alexa提供了成熟的语音服务平台。本文将MCP协议与Alexa技能开发相结合,构建了一个双向协议转换桥接层——Alexa-MCPs服务器。该服务器同时扮演MCP服务提供者和Alexa技能后端的双重角色,

weixin_33709609的博客 657

基于FastAPI与MCP协议快速构建Telegram AI机器人

在人工智能应用开发中,API网关与协议适配是连接前端交互与后端AI能力的关键技术。通过标准化协议(如MCP)实现前后端解耦,开发者可以快速集成各类AI模型,无需重复处理底层通信逻辑。这种架构显著提升了开发效率与系统可维护性,尤其适用于需要即时交互的聊天机器人场景。本文以FastAPI框架与MCP协议为核心,深入解析如何构建一个连接Telegram Bot与AI服务的**协议转换器**,实现用户消息的自动转发与流式响应。通过**Webhook**机制与异步处理,项目能够高效处理高并发请求,为个人助手、团队工具

weixin_30628801的博客 515

FastAPI实战:5分钟搞定MCP Streamable HTTP服务端开发(含完整代码)

本文详细介绍了如何使用FastAPI在5分钟内快速开发符合最新MCP标准的Streamable HTTP服务端。通过对比传统SSE方案的缺陷,阐述了Streamable HTTP在统一端点、按需流式传输和灵活会话管理方面的核心优势,并提供了完整的代码实现,帮助开发者高效构建高并发、资源友好的AI工具扩展服务。

weixin_29302047的博客 540

构建基于 FastAPI 的 MCP 流式通信系统:从服务器到客户端的完整实践

本文详细介绍了如何利用FastAPI构建一个基于MCP协议的流式通信系统。通过实现Server-Sent Events端点,服务器能够向客户端实时推送进度更新和日志信息,解决了传统请求-响应模式在实时应用中的体验割裂问题。文章提供了从服务器搭建、会话管理到Python客户端和动态前端实现的完整实践指南,并深入探讨了SSE与WebSocket的选型对比及生产环境部署要点。

v4w5x6的博客 201

FastAPI MCP Server测试覆盖率实践:零配置开发的质量守护

在软件开发领域,测试覆盖率是衡量代码质量的重要指标,它通过量化测试用例对项目代码的覆盖程度,帮助开发者识别测试盲区。其核心原理在于通过静态或动态分析工具追踪代码执行路径,为质量评估提供客观依据。从技术价值看,高测试覆盖率不仅能保障业务逻辑正确性,还能在重构与迭代时提供信心,降低维护成本。在Web开发、API服务构建等应用场景中,测试覆盖率尤为关键,特别是对于FastAPI这类现代框架构建的服务。本文将聚焦于如何为基于FastAPI的MCP Server建立深度集成的测试覆盖体系,通过pytest-cov等工

weixin_30335353的博客 322

LLM - 使用 FastAPI-MCP 库部署 FastAPI 接口 与 MCP 服务

MCP,即 Model Context Protocol,模型上下文协议,开放协议(Open Protocol),用于规范应用程序为语言模型提供工具和上下文。FastAPI 服务可通过 fastapi-mcp 库构建 MCP 服务,对外提供 MCP 工具。

AGI 1900

MCP Server构建方式

MCP是一种开发协议,皆在标准化LLM大模型与外部工具,数据源之间的通信。它如同“AI界的USB-C接口”, 统一了智能体与外部资源的交互方式,是智能体的“万能工具手”。Higress是一款云原生 API 网关,其内核基于Istio和Envoy。它可以使用 Go、Rust、JS 等编写 Wasm 插件,并提供了数十个现成的通用插件以及开箱即用的控制台。对于简单小型的项目,可以直接采用相关兼容技术栈实现MCP服务,避免在架构中引入Higress,增加管理复杂度。

weixin_45809780的博客 890

开源模型应用落地-模型上下文协议(MCP)-让传统API无缝融入大模型生态的利器-FastAPI_MCP(十四)

FastAPI_MCP 作为一款轻量级适配工具,可在不侵入原有代码的前提下,将 FastAPI 接口自动转化为符合模型上下文协议(MCP)的服务描述,使已有业务逻辑无缝接入大模型系统,实现从自然语言指令到后端服务的闭环调用。

以微薄之力,予他人些许温暖. 7759

突破实时通信瓶颈:MCP协议事件流SSE实现指南

Model Context Protocol (MCP) 是一种创新的实时通信协议,专为解决AI模型与客户端之间的高效数据交互而设计。本文将深入探讨如何利用MCP协议的Server-Sent Events (SSE) 实现突破传统HTTP通信的瓶颈,为新手开发者提供完整的操作指南。 ## 为什么选择MCP协议的SSE实现? 传统的HTTP请求-响应模式在处理实时数据流时面临诸多挑战,如连接频繁

gitblog_00245的博客 774

ADS 2024 Circuit Envelope 仿真:3步配置调制源,分析5G NR EVM与ACPR

本文详细介绍了ADS 2024 Circuit Envelope仿真技术在5G NR调制源配置与关键指标分析中的应用。通过3步配置调制源,工程师可以高效评估EVM与ACPR等关键指标,特别适用于功放设计中的非线性效应诊断。文章还提供了优化仿真设置和精确提取EVM、ACPR的实用方法,助力5G射频前端设计。

weixin_28559803的博客 387

三维模型转变为点云模型的好工具——CloudCompare使用小记

普通三维模型能够直观地展示物体的三维全貌,但是在一些场合需要将三维模型变为相应的点云模型进行展示,而使用激光雷达等传感器采集到的点云信息往往只能反应模型表面的情况,或是使用PCL库中的可执行文件进行转换,这两种操作较为麻烦。笔者最近就遇到了这样一个情况,找到了一个名叫CloudCompare(CC)的软件,能够支持将多种文件格式的三维模型转变为点云模型。以下将本人在使用过程中所使用到的一些操作简记下来供朋友们和将来的自己参考。 一、下载 CloudCompare是一款免费软件,其可以在CloudComp

hdlwyt的博客 2万+

手把手教你用FastAPI搭建MCP协议分析工具:从抓包到XML解析全流程

本文详细介绍了如何使用FastAPI构建MCP协议分析工具,实现从抓包到XML解析的全流程。通过搭建代理服务器拦截并分析AI Agent(如Cline)与模型间的通信,深入解析MCP协议中XML格式的ReAct思维链和工具调用过程,帮助开发者精准定位问题、优化提示词并理解Agent的决策逻辑。

a1b2c的博客 208

Mamba再封神!与YOLO结合,拿下二区!好发不卷!

相比传统的YOLO改进,Mamba是新技术,两者结合尚在蓝海阶段,可发挥空间大!更为关键的是,它在检测精度和速度方面,都让以往的YOLO模型难以望其项背!比如代表模型Mamba YOLO,便在参数减少45.5%、FLOPs减少50%的同时,精度还比YOLOv8高6.1%!这主要得益于,Mamba能够捕捉长期依赖关系,而YOLO则擅长捕捉局部特征,两者能够优势互补,且Mamba线性复杂度的特性,也有利于提高计算效率!为了让大家能够紧跟前沿发展,找到更多灵感启发,我给大家10种。

2401_88190197的博客 2511

mcpo架构深度解析:理解MCP协议与OpenAPI的桥梁实现

mcpo是一款轻量级的MCP协议转OpenAPI代理服务器,它能够将任何MCP工具转换为兼容OpenAPI标准的HTTP服务,让工具与LLM代理和应用程序无缝对接。作为MCP协议与OpenAPI之间的桥梁,mcpo通过自动化的转换逻辑和灵活的配置机制,解决了不同协议间的通信障碍。 ## MCP与OpenAPI:协议转换的核心价值 MCP(Modular Command Protocol)是一种

gitblog_00181的博客 369

pytest-bdd封装

简介 pytestbdd主要是用于代码封装 代码封装的好处: 1、提升代码复用率 2、提示测试效率 手工测试–使用框架0代码 流程+数据驱动 产品经理这样的不懂测试的人员–流程驱动 自动化测试–数据驱动 pytest-bdd:流程驱动封装 行为驱动–敏捷开发模式,消除开发/测试对需要了解的歧义 使用方式: 描述需求/用户场景 Feature(需求) Scenario(场景) Given(假设) When(操作步骤) Then(验证,清除) #新建feature 文件之前 需要提取安装支持featrue文.

liao_11的博客 2734

SAP ABAP开发避坑:BAPI_MATVAL_PRICE_CHANGE调用报‘估价未维护’的完整解决流程

本文深入解析SAP ABAP开发中调用BAPI_MATVAL_PRICE_CHANGE函数时遇到的'估价未维护'错误,提供从基础配置检查到CKML_PRICE_SEND表维护的完整解决方案。通过实战案例和代码示例,帮助开发者快速定位问题并实现批量价格更新的自动化处理,提升开发效率。

weixin_28705087的博客 428

Python实现MCP协议:构建LLM应用的标准化通信

通信协议是分布式系统交互的基础,MCP(Model Context Protocol)作为专为大型语言模型(LLM)设计的标准化协议,通过定义工具、资源和上下文三大核心组件,解决了AI系统间的异构通信问题。其基于Python的实现充分利用了异步IO特性,支持stdio、HTTP和SSE等多种传输方式,特别适合构建AI助手后端、可插拔功能模块等场景。从技术实现来看,MCP协议通过JWT认证、角色授权等安全机制保障系统安全,配合uvloop和连接池等优化手段,能满足生产环境的高并发需求。开发者可以通过MCP P

weixin_33835103的博客 530

通过Python实现物联网金橙子自动打标

对于自家公司使用金橙子打标卡时,为了与生产线或者PLC联动等,往往需要对金橙子打标卡进行二次开发,而在二次开发中不得不涉及到MarkEzd.dll这个文件,而这个dll文件网上版本多不说,一般都没法直接使用,最后还不得不花大价钱购买专用库。而本文针对这个问题,涉法通过python来绕过MarkEzd.dll文件,直接进行自动化控制EzCad来实现联动,可应用于实际生产。文章最后拓展一下以物联网的形式,实现手机平台等登录网页,输入想要的印字内容后,远程打印的案例。

lylelo的博客 3366

Dify与MCP协议集成:SSE连接实现AI工具标准化调用

在AI应用开发中,工具调用是扩展模型能力的关键环节。传统方式需要为每个外部服务单独开发适配器,导致开发维护成本高昂。Model Context Protocol(MCP)作为一种标准化协议,定义了工具发现、调用和结果返回的统一规范,实现了AI模型与外部工具的解耦。通过SSE(Server-Sent Events)协议建立长连接,MCP客户端能够高效接收服务器推送的工具执行结果。这种组合方案在Dify低代码平台中尤为重要,通过dify-plugin-tools-mcp_sse插件,开发者可以快速接入各类MCP

weixin_30596735的博客 578

基于改进YOLOv5的小目标检测 | 添加CBAM注意机制 + 更换Neck网络之BiFPN + 增加高分辨率检测头

本文针对图像中小目标难以检测的问题,提出了一种基于YOLOv5的改进模型。在主干网络中,加入CBAM注意力模块增强网络特征提取能力;在颈部网络部分,使用BiFPN结构替换PANet结构,强化底层特征利用;在检测头部分,增加高分辨率检测头,改善对于微小目标的检测能力。本文算法在无人机数据集VisDrone2019数据集上进行了多次对比实验,结果表明本文算法可以有效地检测小目标。🌈

小哥谈 2937

openclaw本地模型对接

使用是官方推荐的一种集成方式,它可以简化配置过程。但由于您的系统环境和之前复杂的配置历史,我为您梳理了一个核心流程,并增加了关键的“事后检查”步骤,以确保能从根本上解决问题。

suny8的专栏 2463
上一篇: SameSite Strict策略下,如何利用客户端重定向Gadget实现CSRF攻击
下一篇: 【实战拆解】影刀RPA高级考试:Python编码版数据抓取与数据库入库全流程
php55
博客等级 码龄15年 51粉丝 1553原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符  | 博主筛选后可见
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值