35_FastMCP 2.x 中文文档之FastMCP客户端高级功能：接收并处理服务端日志详解

一、服务器日志记录

接收并处理来自 MCP 服务器的日志消息。

新版本：2.0.0 功能

MCP 服务器可以向客户端发送日志消息。客户端可以通过日志处理程序回调来处理这些日志。

二、日志处理程序

在创建客户端时提供一个 log_handler 函数。为了实现健壮的日志记录，可以将日志消息与 Python 的标准 logging 模块集成。

import logging
from fastmcp import Client
from fastmcp.client.logging import LogMessage

# 在实际应用中，您可以在主入口点配置此设置
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# 获取使用客户端的模块的日志记录器
logger = logging.getLogger(__name__)

# 此映射对于将 MCP 级别字符串转换为 Python 级别很有用
LOGGING_LEVEL_MAP = logging.getLevelNamesMapping()

async def log_handler(message: LogMessage):
    """
    处理来自 MCP 服务器的传入日志，
    并将其转发到标准 Python 日志记录系统。
    """
    msg = message.data.get('msg')
    extra = message.data.get('extra')

    # 将 MCP 日志级别转换为 Python 日志级别
    level = LOGGING_LEVEL_MAP.get(message.level.upper(), logging.INFO)

    # 使用标准日志记录库记录消息
    logger.log(level, msg, extra=extra)


client = Client(
    "my_mcp_server.py",
    log_handler=log_handler,
)

2.1 处理结构化日志

message.data 属性是一个字典，包含来自服务器的日志有效负载。这支持结构化日志记录，允许您接收丰富的上下文信息。

该字典包含两个键：

• msg：字符串日志消息

• extra：包含服务器发送的任何额外数据的字典

即使日志通过 FastMCP 代理转发，这种结构也会被保留，使其成为调试复杂的多服务器应用程序的强大工具。

2.2 处理程序参数

每次收到日志消息时都会调用 log_handler。它接收一个 LogMessage 对象：

• LogMessage：日志消息对象

属性：

• level：日志级别（字面量：“debug”、“info”、“notice”、“warning”、“error”、“critical”、“alert”、“emergency”）

• logger：日志记录器名称（可选，可能为 None）

• data：日志有效负载，包含 msg 和 extra 键

async def detailed_log_handler(message: LogMessage):
    msg = message.data.get('msg')
    extra = message.data.get('extra')

    if message.level == "error":
        print(f"错误: {msg} | 详情: {extra}")
    elif message.level == "warning":
        print(f"警告: {msg} | 详情: {extra}")
    else:
        print(f"{message.level.upper()}: {msg}")

三、默认日志处理

如果您不提供自定义的 log_handler，FastMCP 的默认处理程序会将服务器日志路由到适当的 Python 日志记录级别。MCP 级别的映射如下：notice → INFO；alert 和 emergency → CRITICAL。如果服务器包含日志记录器名称，它会在消息中加上前缀，任何 extra 数据都通过日志记录 extra 参数转发。

client = Client("my_mcp_server.py")

async with client:
    # 服务器日志以其适当的严重性级别转发（DEBUG/INFO/WARNING/ERROR/CRITICAL）
    await client.call_tool("some_tool")