Claude Academy
Chargement

Journalisation et notifications de progression

Leçon 37 min

La journalisation et les notifications de progression sont simples à mettre en œuvre, mais elles font une énorme différence dans l'expérience utilisateur lorsque l'on travaille avec des serveurs MCP. Elles aident les utilisateurs à comprendre ce qui se passe pendant les opérations de longue durée, au lieu de se demander si quelque chose s'est cassé.

Lorsque Claude appelle un outil qui prend du temps à s'exécuter - comme faire des recherches sur un sujet ou traiter des données - les utilisateurs ne voient généralement rien jusqu'à ce que l'opération se termine. Cela peut être frustrant, car ils ne savent pas si l'outil fonctionne ou s'il est bloqué.

Avec la journalisation et les notifications de progression activées, les utilisateurs obtiennent un retour en temps réel montrant exactement ce qui se passe en coulisses. Ils peuvent voir des barres de progression, des messages d'état et des journaux détaillés pendant le déroulement de l'opération.

Comment ça fonctionne

Dans le SDK Python MCP, la journalisation et les notifications de progression fonctionnent via l'argument Context qui est automatiquement fourni à vos fonctions d'outil. Cet objet de contexte vous donne des méthodes pour communiquer avec le client pendant l'exécution.

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

Les méthodes clés que vous utiliserez sont :

  • context.info() - Envoie des messages de journal au client
  • context.report_progress() - Met à jour la progression avec les valeurs actuelle et totale

Mise en œuvre côté client

Côté client, vous devez configurer des fonctions de rappel pour gérer ces notifications. Le serveur émet ces messages, mais c'est à votre application cliente de décider comment les présenter aux utilisateurs.

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

Vous fournissez le rappel de journalisation lors de la création de la session client, et le rappel de progression lors des appels d'outils individuels. Cela vous donne la flexibilité de gérer différents types de notifications de manière appropriée.

Options de présentation

La façon dont vous présentez ces notifications dépend du type de votre application :

  • Applications CLI - Affichez simplement les messages et la progression dans le terminal
  • Applications web - Utilisez les WebSockets, les événements envoyés par le serveur (server-sent events) ou le polling pour transmettre les mises à jour au navigateur
  • Applications de bureau - Mettez à jour les barres de progression et les affichages d'état dans votre interface utilisateur

N'oubliez pas que la mise en œuvre de ces notifications est entièrement facultative. Vous pouvez choisir de les ignorer complètement, de n'afficher que certains types, ou de les présenter de la manière qui a du sens pour votre application. Elles ne sont que des améliorations de l'expérience utilisateur destinées à aider les utilisateurs à comprendre ce qui se passe pendant les opérations de longue durée.