로그 및 진행 상황 알림 · Model Context Protocol: 고급 주제

로깅 및 진행 상황 알림은 구현하기 간단하지만 MCP 서버로 작업할 때 사용자 경험에 큰 차이를 만듭니다. 이는 사용자가 장시간 실행되는 작업 중에 무언가가 고장났는지 궁금해하는 대신 무슨 일이 일어나고 있는지 이해하도록 도와줍니다.

Claude가 주제를 조사하거나 데이터를 처리하는 것과 같이 완료하는 데 시간이 걸리는 도구를 호출할 때, 사용자는 일반적으로 작업이 끝날 때까지 아무것도 보지 못합니다. 이는 도구가 작동 중인지 멈췄는지 알 수 없기 때문에 답답할 수 있습니다.

로깅 및 진행 상황 알림이 활성화되면, 사용자는 백그라운드에서 정확히 무슨 일이 일어나고 있는지 보여주는 실시간 피드백을 받습니다. 작업이 실행되는 동안 진행률 표시줄, 상태 메시지, 상세 로그를 볼 수 있습니다.

작동 방식

Python MCP SDK에서 로깅 및 진행 상황 알림은 도구 함수에 자동으로 제공되는 Context 인수를 통해 작동합니다. 이 컨텍스트 객체는 실행 중에 클라이언트와 다시 통신할 수 있는 메서드를 제공합니다.

python

@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

사용하게 될 주요 메서드는 다음과 같습니다:

context.info() - 클라이언트에 로그 메시지 전송
context.report_progress() - 현재 값과 전체 값으로 진행 상황 업데이트

클라이언트 측 구현

클라이언트 측에서는 이러한 알림을 처리하기 위한 콜백 함수를 설정해야 합니다. 서버가 이러한 메시지를 내보내지만, 이를 사용자에게 어떻게 표시할지는 클라이언트 애플리케이션에 달려 있습니다.

python

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,
            )

클라이언트 세션을 생성할 때 로깅 콜백을 제공하고, 개별 도구 호출을 할 때 진행 상황 콜백을 제공합니다. 이를 통해 다양한 유형의 알림을 적절하게 처리할 수 있는 유연성을 얻을 수 있습니다.

표시 옵션

이러한 알림을 표시하는 방법은 애플리케이션 유형에 따라 다릅니다:

CLI 애플리케이션 - 터미널에 메시지와 진행 상황을 단순히 출력합니다
웹 애플리케이션 - WebSocket, 서버 전송 이벤트 또는 폴링을 사용하여 브라우저에 업데이트를 푸시합니다
데스크톱 애플리케이션 - UI에서 진행률 표시줄과 상태 표시를 업데이트합니다

이러한 알림을 구현하는 것은 전적으로 선택 사항이라는 점을 기억하세요. 완전히 무시하거나, 특정 유형만 표시하거나, 애플리케이션에 적합한 방식으로 표시할 수 있습니다. 이는 장시간 실행되는 작업 중에 무슨 일이 일어나고 있는지 사용자가 이해하도록 돕기 위한 순수한 사용자 경험 향상 기능입니다.