MCP Python SDK教程：深入理解FastMCP Context机制

最新推荐文章于 2025-06-07 16:43:13 发布

花淑云Nell

最新推荐文章于 2025-06-07 16:43:13 发布

阅读量299

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_01092/article/details/148440258

MCP Python SDK教程：深入理解FastMCP Context机制

Tutorial-Codebase-Knowledge Turns Codebase into Easy Tutorial with AI 项目地址: https://gitcode.com/gh_mirrors/tu/Tutorial-Codebase-Knowledge

前言

在构建AI应用服务时，一个常见的需求是让长时间运行的任务能够实时反馈执行状态，或者让工具函数能够访问服务端的共享资源。MCP Python SDK中的FastMCP框架通过Context机制优雅地解决了这些问题。本文将深入解析这一核心机制，帮助开发者掌握如何利用Context构建更强大的AI服务。

Context机制概述

Context是FastMCP框架中一个强大的上下文对象，它为工具函数和资源函数提供了请求级别的上下文环境。简单来说，Context就像是一个"后台通行证"，允许你的函数在执行过程中：

向客户端发送实时日志信息
报告任务执行进度
访问服务端定义的其他资源
获取当前请求的元数据

核心功能解析

1. 日志反馈机制

Context提供了多级日志反馈接口：

await ctx.debug("调试信息")  # 调试级别日志
await ctx.info("普通信息")   # 信息级别日志
await ctx.warning("警告信息") # 警告级别日志
await ctx.error("错误信息")   # 错误级别日志

这些日志会实时发送到客户端，非常适合用于：

记录任务执行的关键步骤
报告异常情况
提供调试信息

2. 进度报告功能

对于长时间运行的任务，进度反馈至关重要：

await ctx.report_progress(current_step, total_steps)

这个功能可以：

让客户端显示进度条
预估剩余时间
提供任务取消的依据

3. 资源访问能力

Context允许工具函数访问服务端定义的其他资源：

resource_contents = await ctx.read_resource("config://task_settings")

这种设计实现了：

松耦合的模块设计
动态配置加载
资源共享与复用

实战示例

基础示例：带进度报告的任务

import anyio
from mcp.server.fastmcp import FastMCP
from mcp.server.fastmcp.server import Context

server = FastMCP(name="TaskServer")

@server.tool(name="long_task")
async def run_long_task(duration: int, ctx: Context) -> str:
    await ctx.info(f"任务开始，预计耗时{duration}秒")
    
    steps = 5
    for i in range(steps):
        await ctx.debug(f"正在处理第{i+1}/{steps}步")
        await anyio.sleep(duration/steps)
        await ctx.report_progress(i+1, steps)
    
    await ctx.info("任务完成！")
    return "执行成功"

进阶示例：结合资源访问

@server.resource(uri="config://settings")
def get_settings() -> dict:
    return {"mode": "fast", "retry": 3}

@server.tool(name="enhanced_task")
async def enhanced_task(ctx: Context) -> str:
    settings = await ctx.read_resource("config://settings")
    await ctx.info(f"当前配置：{settings}")
    
    if settings.get("mode") == "fast":
        await ctx.debug("快速模式执行中...")
    else:
        await ctx.debug("标准模式执行中...")
    
    return "任务完成"

实现原理深度解析

1. 上下文生命周期

请求到达：客户端发起请求
上下文创建：FastMCP创建底层RequestContext
包装处理：生成高级Context对象
函数调用：通过工具管理器调用目标函数
参数注入：自动注入Context对象
执行反馈：通过Context与客户端交互

2. 关键技术点

类型提示(Type Hint)：通过ctx: Context参数标记实现自动注入
请求隔离：每个请求拥有独立的Context实例
会话管理：通过底层ServerSession实现双向通信

3. 核心类结构

classDiagram
    class Context {
        +_request_context: RequestContext
        +_fastmcp: FastMCP
        +info(message: str)
        +debug(message: str)
        +warning(message: str)
        +error(message: str)
        +report_progress(current, total)
        +read_resource(uri)
    }
    
    class FastMCP {
        +get_context() Context
        +read_resource(uri)
    }
    
    class RequestContext {
        +session: ServerSession
        +meta: RequestMeta
    }
    
    Context --> FastMCP
    Context --> RequestContext