ModelContextProtocol Python SDK 日志功能使用指南

日志功能概述

ModelContextProtocol (MCP) Python SDK 提供了一套完整的日志记录系统，开发者可以通过 Context 对象的方法来实现不同级别的日志输出和进度报告。这些功能对于调试和监控长时间运行的计算任务特别有用。

核心日志方法

MCP SDK 提供了三个主要的日志相关方法：

1. info() - 用于记录一般信息性消息
2. debug() - 用于记录调试信息
3. report_progress() - 用于报告任务执行进度

正确使用方式

以下是经过修正的正确使用示例：

from mcp.server.fastmcp import FastMCP, Context
import asyncio

mcp = FastMCP("示例服务器", debug=True, log_level="DEBUG")

@mcp.tool()
async def my_tool(x: float, y: float, ctx: Context) -> str:
    """执行长时间运行的计算"""
    
    # 正确使用日志方法
    await ctx.info("处理消息1")
    await ctx.report_progress(1, 2)
    await asyncio.sleep(2)  # 使用异步sleep
    
    await ctx.debug("处理消息2")
    await ctx.report_progress(2, 2)
    await asyncio.sleep(2)
    
    return str(x * y)

关键注意事项

1. 异步调用：所有日志方法都是异步的，必须使用await关键字调用
2. 避免阻塞：在异步函数中应该使用asyncio.sleep而不是time.sleep
3. 日志级别：需要在初始化FastMCP时设置适当的log_level才能看到相应级别的日志
4. 进度报告：report_progress方法接受当前进度和总进度两个参数

常见问题解决

如果在使用过程中遇到"coroutine was never awaited"警告，通常是因为：

1. 忘记在日志方法调用前加await关键字
2. 在非异步上下文中调用了异步方法
3. 使用了阻塞式操作(如time.sleep)导致事件循环被阻塞

最佳实践建议

1. 对于长时间运行的任务，定期调用report_progress更新进度
2. 在开发阶段使用DEBUG级别日志，生产环境可调整为INFO
3. 为重要操作添加info级别的日志记录
4. 使用try-except块捕获异常并通过日志记录错误信息

通过遵循这些指导原则，开发者可以充分利用MCP SDK的日志功能，更好地监控和调试应用程序。