読み込み中

ログと進捗通知は実装が簡単でありながら、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アプリケーション - メッセージと進捗をターミナルに単純に出力する
  • Webアプリケーション - WebSocket、サーバー送信イベント、またはポーリングを使用してブラウザに更新を送信する
  • デスクトップアプリケーション - UI内の進捗バーとステータス表示を更新する

これらの通知の実装は完全に任意であることに注意してください。完全に無視することも、特定の種類のみを表示することも、アプリケーションに合った形で提示することも選択できます。これらは、長時間実行される操作中にユーザーが何が起きているかを理解する助けとなる、純粋なユーザー体験の向上のための機能です。