【MCP系列教程】 Python 实现 FastMCP StreamableHTTP MCP：在通义灵码 IDE 开发并部署至阿里云百炼

一、前言：为何 StreamableHTTP 是下一代 MCP 通信标准？

随着大模型智能体（AI Agent）生态的快速演进，模型与外部工具之间的高效、可靠、实时通信机制 已成为构建复杂 AI 应用的关键瓶颈。

阅读原文：https://developer.aliyun.com/article/1679329

传统的 Stdio（标准输入输出）和 SSE（Server-Sent Events）协议在远程调用、上下文维护和云原生部署方面存在明显局限。而 StreamableHTTP 作为一种新兴的 MCP（Model Context Protocol）传输协议，正以其双向流式通信、无状态设计、断点续传能力等优势，成为企业级 AI 工具集成的新选择。

✅ 阿里云百炼平台已于近期全面支持 StreamableHTTP MCP 协议，标志着 MCP 技术向生产级落地迈出关键一步。

本文将带你使用 FastMCP 框架 + Python ，从零搭建一个基于 通义万象 qwen-image 文生图 API 的 StreamableHTTP MCP 服务，并完成本地测试、云端部署与百炼平台集成的全链路实践。

---

二、核心优势对比：为什么选择 StreamableHTTP？

场景	StreamableHTTP	SSE	Stdio
远程实时通信	✅ 双向流式 + 断点续传	❌ 单向推送，需轮询维护	❌ 仅限本地进程
云原生 / 微服务	✅ 无状态，天然适配 Serverless	❌ 长连接资源消耗高	❌ 不支持网络调用
企业级部署兼容性	✅ 兼容防火墙、代理、负载均衡	❌ 易被中间件中断	❌ 无法跨网络
AI Agent 多轮交互	✅ 支持上下文维护与异步任务查询	❌ 上下文难维护	✅ 本地调试方便

StreamableHTTP 的三大核心价值：

1. 架构简化：单一 HTTP 端点 + 动态协议升级，降低开发与运维复杂度。
2. 高可靠性：支持任务中断后恢复，提升长耗时任务成功率。
3. 未来兼容：面向云原生、Serverless 和分布式 Agent 架构设计。

---

三、整体实现思路

我们希望通过 MCP 协议，将 通义万象的文生图能力封装为 AI 模型可调用的"工具"，实现如下流程：

用户提问 → 百炼智能体 → 调用 MCP 服务 → 创建图像任务 → 返回 task_id → 查询任务结果 → 返回图片 URL → 回复用户

为此，我们将：

1. 使用 FastMCP 框架封装两个 API：
   • imageSynthesis：提交文生图请求，返回 task_id
   • tasks：根据 task_id 查询生成状态与结果
2. 本地开发测试 → 部署至阿里云函数计算 → 集成至阿里云百炼 MCP 服务

---

四、环境准备与项目搭建

1. 安装高性能 Python 包管理工具 uv

pip install uv

🔍 uv 是由 Astral 开发的 Rust 编写的 Python 工具链替代品，集成了 pip、venv、pip-tools 等功能，速度快、依赖解析精准。

若安装失败，请参考官方文档：https://docs.astral.sh/uv/

2. 创建项目

uv init --package --python 3.10 bailian-streamablehttp-mcp-server
cd bailian-streamablehttp-mcp-server

⚠️ 建议统一使用 Python 3.10，避免后续部署时出现兼容性问题。

3. 创建虚拟环境并安装依赖

# 创建虚拟环境
uv venv

# 激活虚拟环境
# macOS / Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

# 安装 FastMCP（推荐版本 2.11.3）
uv add fastmcp==2.11.3

---

五、代码实现：构建 StreamableHTTP MCP 服务

1. 项目结构

bailian-streamablehttp-mcp-server/
├── src/
│   └── bailian_streamablehttp_mcp_server/
│       ├── __init__.py
│       └── server.py
├── pyproject.toml
└── .venv/

2. 编写 server.py

from fastmcp import FastMCP
from fastmcp.server.dependencies import get_http_request
import requests
from starlette.requests import Request

# 初始化 MCP 服务器
mcp = FastMCP("text2image")

# 通义万象 API 地址
image_synthesis_url = "https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis"
tasks_url = "https://dashscope.aliyuncs.com/api/v1/tasks/"

@mcp.tool(
    name="通义万象qwen-image文生图 - 创建任务",
    description="提交文生图请求，返回任务ID（task_id）。"
                "参数说明："
                "prompt: 提示词（中英文，≤800字符）；"
                "size: 图片尺寸（如1328*1328，默认1:1）；"
                "prompt_extend: 是否启用智能改写（true/false，默认true）；"
                "watermark: 是否添加水印（true/false，默认false）"
)
def image_synthesis(prompt: str, size: str = "1328*1328", prompt_extend: bool = True, watermark: bool = False) -> dict:
    request: Request = get_http_request()
    api_key = request.headers.get("api_key")
    if not api_key:
        raise ValueError("请求头中缺少 api_key")

    headers = {
        'X-DashScope-Async': 'enable',
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }

    data = {
        "model": "qwen-image",
        "input": {"prompt": prompt},
        "parameters": {
            "size": size,
            "n": 1,
            "prompt_extend": prompt_extend,
            "watermark": watermark
        }
    }

    response = requests.post(
        url=image_synthesis_url,
        headers=headers,
        json=data,
        timeout=30
    )
    response.raise_for_status()
    return response.json()


@mcp.tool(
    name="通义万象qwen-image文生图 - 查询任务结果",
    description="根据 task_id 查询图像生成进度与结果。"
)
def tasks(task_id: str) -> dict:
    if not task_id:
        raise ValueError("task_id 不能为空")

    request: Request = get_http_request()
    api_key = request.headers.get("api_key")
    if not api_key:
        raise ValueError("请求头中缺少 api_key")

    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"{tasks_url}{task_id}"

    response = requests.get(url, headers=headers, timeout=30)
    response.raise_for_status()
    return response.json()


def run():
    mcp.run(transport="http", host="127.0.0.1", port=8000)

3. 在 __init__.py 中启动服务

from .server import run

if __name__ == "__main__":
    run()

---

六、本地测试：使用通义灵码验证 MCP 服务

1. 启动本地服务

python -m bailian_streamablehttp_mcp_server

服务将运行在 http://127.0.0.1:8000，支持 StreamableHTTP 协议。

2. 使用通义灵码进行集成测试

在支持 MCP 的 IDE（如通义灵码插件）中配置：

{
  "mcp_servers": {
    "text2image": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "api_key": "your-dashscope-api-key"
      }
    }
  }
}

3. 测试流程

1. 调用 image_synthesis 工具，输入提示词如 "一只在太空骑自行车的熊猫"。
2. 获取返回的 task_id。
3. 调用 tasks(task_id) 查询任务状态，直到返回 "status": "SUCCEEDED"。
4. 获取图片下载链接并展示。

✅ 测试成功后，即可进入部署阶段。

---

七、详细内容阅读原文：阅读原文：https://developer.aliyun.com/article/1679329