Claude Academy
Wird geladen

Protokoll- und Fortschrittsbenachrichtigungen

Lektion 37 Min.

Logging und Fortschrittsbenachrichtigungen sind einfach zu implementieren, machen aber einen großen Unterschied in der Nutzererfahrung bei der Arbeit mit MCP-Servern. Sie helfen Nutzern zu verstehen, was während lang laufender Operationen passiert, anstatt sich zu fragen, ob etwas kaputt gegangen ist.

Wenn Claude ein Tool aufruft, das Zeit zur Fertigstellung benötigt – etwa das Recherchieren eines Themas oder das Verarbeiten von Daten – sehen Nutzer in der Regel nichts, bis die Operation abgeschlossen ist. Das kann frustrierend sein, weil sie nicht wissen, ob das Tool arbeitet oder hängen geblieben ist.

Mit aktivierten Logging- und Fortschrittsbenachrichtigungen erhalten Nutzer Echtzeit-Feedback, das genau zeigt, was im Hintergrund passiert. Sie können Fortschrittsbalken, Statusmeldungen und detaillierte Protokolle sehen, während die Operation läuft.

Wie es funktioniert

Im Python MCP SDK funktionieren Logging und Fortschrittsbenachrichtigungen über das Context-Argument, das automatisch an deine Tool-Funktionen übergeben wird. Dieses Context-Objekt gibt dir Methoden, um während der Ausführung mit dem Client zu kommunizieren.

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

Die wichtigsten Methoden, die du verwenden wirst, sind:

  • context.info() - Sendet Protokollnachrichten an den Client
  • context.report_progress() - Aktualisiert den Fortschritt mit aktuellen und Gesamtwerten

Client-seitige Implementierung

Auf der Client-Seite musst du Callback-Funktionen einrichten, um diese Benachrichtigungen zu verarbeiten. Der Server sendet diese Nachrichten, aber es liegt an deiner Client-Anwendung zu entscheiden, wie sie den Nutzern präsentiert werden.

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

Du stellst den Logging-Callback beim Erstellen der Client-Sitzung bereit und den Fortschritts-Callback bei einzelnen Tool-Aufrufen. Das gibt dir die Flexibilität, verschiedene Arten von Benachrichtigungen angemessen zu behandeln.

Darstellungsoptionen

Wie du diese Benachrichtigungen präsentierst, hängt von deinem Anwendungstyp ab:

  • CLI-Anwendungen - Gib einfach Nachrichten und Fortschritt im Terminal aus
  • Webanwendungen - Verwende WebSockets, Server-Sent Events oder Polling, um Updates an den Browser zu senden
  • Desktop-Anwendungen - Aktualisiere Fortschrittsbalken und Statusanzeigen in deiner Benutzeroberfläche

Denk daran, dass die Implementierung dieser Benachrichtigungen völlig optional ist. Du kannst sie komplett ignorieren, nur bestimmte Typen anzeigen oder sie so präsentieren, wie es für deine Anwendung sinnvoll ist. Sie sind reine Verbesserungen der Nutzererfahrung, um Nutzern zu helfen zu verstehen, was während lang laufender Operationen passiert.