Bỏ qua đến nội dung chính

Log and progress notifications

📖 Nội dung bài học

Tóm tắt

Logging và thông báo tiến độ rất dễ triển khai nhưng tạo ra sự khác biệt lớn về trải nghiệm người dùng khi làm việc với máy chủ MCP. Chúng giúp người dùng hiểu điều gì đang xảy ra trong các thao tác chạy dài thay vì băn khoăn liệu có gì đó đã bị lỗi hay không.

Khi Claude gọi một tool tốn thời gian để hoàn thành - như nghiên cứu một chủ đề hoặc xử lý dữ liệu - người dùng thường không thấy gì cho đến khi thao tác kết thúc. Điều này có thể gây khó chịu vì họ không biết tool có đang hoạt động hay đã bị kẹt.

Với logging và thông báo tiến độ được bật, người dùng nhận được phản hồi theo thời gian thực hiển thị chính xác những gì đang xảy ra phía sau hậu trường. Họ có thể thấy thanh tiến trình, thông báo trạng thái và log chi tiết khi thao tác chạy.

Cách hoạt động

Trong Python MCP SDK, logging và thông báo tiến độ hoạt động thông qua đối số Context được cung cấp tự động cho các hàm tool của bạn. Đối tượng context này cung cấp cho bạn các phương thức để giao tiếp trở lại client trong quá trình thực thi.

@mcp.tool(
    name="research",
    description="Research a given topic"
)
async def research(
    topic: str = Field(description="Topic to research"),
    *,
    context: Context
):
    await context.info("About to do research...")
    await context.report_progress(20, 100)
    sources = await do_research(topic)
    
    await context.info("Writing report...")
    await context.report_progress(70, 100)
    results = await generate_report(sources)
    
    return results

Các phương thức chính bạn sẽ sử dụng là:

  • context.info() - Gửi tin nhắn log đến client
  • context.report_progress() - Cập nhật tiến độ với các giá trị hiện tại và tổng số

Triển khai phía client

Ở phía client, bạn cần thiết lập các hàm callback để xử lý các thông báo này. Máy chủ phát ra các tin nhắn này, nhưng tùy thuộc vào ứng dụng client của bạn để quyết định cách trình bày chúng cho người dùng.

async def logging_callback(params: LoggingMessageNotificationParams):
    print(params.data)

async def print_progress_callback(
    progress: float, total: float | None, message: str | None
):
    if total is not None:
        percentage = (progress / total) * 100
        print(f"Progress: {progress}/{total} ({percentage:.1f}%)")
    else:
        print(f"Progress: {progress}")

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(
            read,
            write,
            logging_callback=logging_callback
        ) as session:
            await session.initialize()
            
            await session.call_tool(
                name="add",
                arguments={"a": 1, "b": 3},
                progress_callback=print_progress_callback,
            )

Bạn cung cấp callback logging khi tạo session client, và callback tiến độ khi thực hiện các lệnh gọi tool riêng lẻ. Điều này mang lại cho bạn sự linh hoạt để xử lý các loại thông báo khác nhau một cách phù hợp.

Tùy chọn trình bày

Cách bạn trình bày các thông báo này phụ thuộc vào loại ứng dụng của bạn:

  • Ứng dụng CLI - Đơn giản là in tin nhắn và tiến độ ra terminal
  • Ứng dụng Web - Sử dụng WebSockets, server-sent events hoặc polling để đẩy cập nhật lên trình duyệt
  • Ứng dụng Desktop - Cập nhật thanh tiến trình và hiển thị trạng thái trong UI của bạn

Hãy nhớ rằng việc triển khai các thông báo này là hoàn toàn tùy chọn. Bạn có thể chọn bỏ qua chúng hoàn toàn, chỉ hiển thị một số loại nhất định hoặc trình bày chúng theo bất kỳ cách nào có ý nghĩa cho ứng dụng của bạn. Chúng hoàn toàn là những cải tiến về trải nghiệm người dùng để giúp người dùng hiểu điều gì đang xảy ra trong các thao tác chạy dài.

🔁 Bài học liên quan

📚 Nguồn & ghi nhận

Bài học có hữu ích không?

Góp ý / Báo lỗiPhát hiện sai sót hoặc có ý tưởng cải thiện?