Prompts

Traduction automatique

Cette page a été traduite automatiquement à partir de la documentation en anglais, et la page en anglais fait foi. Si quelque chose vous semble incorrect, la page Traductions explique comment le signaler.

Un prompt est un modèle de message que l’utilisateur choisit.

Les outils sont destinés au modèle. Un prompt, c’est l’inverse : l’utilisateur en choisit un dans un menu de son client (une commande slash, un bouton), renseigne ses arguments, et les messages rendus entrent dans la conversation comme s’il les avait saisis lui-même.

Vous en déclarez un en plaçant @mcp.prompt() sur une fonction qui renvoie le texte.

Votre premier prompt

server.py

from mcp.server import MCPServer

mcp = MCPServer("Code Helper")


@mcp.prompt()
def review_code(code: str) -> str:
    """Review a piece of code."""
    return f"Please review this code:\n\n{code}"

Le SDK lit les trois mêmes éléments qu’il lit sur un outil :

Le nom est le nom de la fonction : review_code.
La description que le client affiche est la docstring : Review a piece of code.
Les arguments proviennent des paramètres. code n’a pas de valeur par défaut, il est donc obligatoire.

Voici ce qu’un client obtient en retour de prompts/list :

{
  "name": "review_code",
  "description": "Review a piece of code.",
  "arguments": [
    {"name": "code", "required": true}
  ]
}

Il n’y a pas de JSON Schema ici. Les arguments d’un prompt forment une liste plate de valeurs chaînes nommées : un formulaire qu’une personne remplit, pas une charge utile qu’un modèle construit.

Le rendre

Le client rend le modèle avec prompts/get, en passant les arguments. Votre fonction s’exécute et la str que vous renvoyez devient un seul message utilisateur :

{
  "description": "Review a piece of code.",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Please review this code:\n\ndef add(a, b): return a + b"
      }
    }
  ],
  "resultType": "complete"
}

C’est toute la vie d’un prompt : listé par son nom, rendu à la demande, déposé dans la conversation.

Check

required est vérifié avant l’exécution de votre fonction. Rendez review_code sans code et la requête elle-même échoue avec une erreur JSON-RPC (code -32603) :

mcp.shared.exceptions.MCPError: Internal server error

Il n’y a pas de résultat d’erreur à la manière des outils à remettre à un modèle, car aucun modèle n’est dans la boucle : l’appel lève une exception. La raison (Missing required arguments: {'code'}) arrive dans le journal de votre serveur.

Essayer

Lancez le serveur avec le MCP Inspector :

uv run mcp dev server.py

Ouvrez l’onglet Prompts et sélectionnez review_code. L’Inspector dessine un formulaire avec un seul champ obligatoire code. Renseignez-le, lancez le rendu, et vous obtenez en retour exactement le message utilisateur ci-dessus.

Plus d’un message

Une revue de code, c’est un message. Une session de débogage, c’est une conversation, et un prompt peut l’amorcer tout entière.

Renvoyez une liste de messages au lieu d’une str :

server.py

from mcp.server import MCPServer
from mcp.server.mcpserver.prompts.base import AssistantMessage, Message, UserMessage

mcp = MCPServer("Code Helper")


@mcp.prompt()
def review_code(code: str) -> str:
    """Review a piece of code."""
    return f"Please review this code:\n\n{code}"


@mcp.prompt()
def debug_error(error: str) -> list[Message]:
    """Start a debugging conversation."""
    return [
        UserMessage("I'm seeing this error:"),
        UserMessage(error),
        AssistantMessage("I'll help debug that. What have you tried so far?"),
    ]

UserMessage et AssistantMessage viennent de mcp.server.mcpserver.prompts.base. Passez-leur une str et ils l’enveloppent dans un TextContent pour vous. Le rôle est le nom de la classe.
Message est leur classe de base commune. Utilisez-la comme annotation de retour.

Le rendu de debug_error produit désormais trois messages, dans l’ordre :

{
  "description": "Start a debugging conversation.",
  "messages": [
    {"role": "user", "content": {"type": "text", "text": "I'm seeing this error:"}},
    {"role": "user", "content": {"type": "text", "text": "TypeError: 'int' object is not iterable"}},
    {
      "role": "assistant",
      "content": {"type": "text", "text": "I'll help debug that. What have you tried so far?"}
    }
  ],
  "resultType": "complete"
}

Remarquez le dernier. Préremplir un tour assistant, c’est la façon d’orienter la prochaine réponse du modèle sans obliger l’utilisateur à saisir lui-même cette orientation.

Titres et descriptions d’arguments

review_code est un nom de fonction, pas un libellé. Donnez au client quelque chose de mieux à afficher sur le bouton, et décrivez chaque argument pour que le formulaire s’explique de lui-même :

server.py

from typing import Annotated

from pydantic import Field

from mcp.server import MCPServer

mcp = MCPServer("Code Helper")


@mcp.prompt(title="Code review")
def review_code(
    code: Annotated[str, Field(description="The code to review.")],
    language: Annotated[str, Field(description="The language the code is written in.")] = "python",
) -> str:
    """Review a piece of code."""
    return f"Please review this {language} code:\n\n{code}"

title="Code review" est le nom lisible par un humain, exactement comme le title d’un outil.
Annotated[str, Field(description=...)] est le même motif que celui que Outils utilise pour décrire les paramètres d’un outil. Ici, la description se retrouve sur l’argument plutôt que dans un schéma.
language a une valeur par défaut, il cesse donc d’être obligatoire.

L’entrée prompts/list contient désormais tout ce dont un client a besoin pour dessiner un bon formulaire :

{
  "name": "review_code",
  "title": "Code review",
  "description": "Review a piece of code.",
  "arguments": [
    {"name": "code", "description": "The code to review.", "required": true},
    {"name": "language", "description": "The language the code is written in.", "required": false}
  ]
}

Info

Si vous avez lu Outils, vous connaissez déjà tout ce que contient cette page. Même décorateur, même docstring servant de description, mêmes Annotated/Field. Seuls changent qui le déclenche (l’utilisateur) et où va le résultat (dans la conversation).

Récapitulatif

@mcp.prompt() sur une fonction en fait un prompt. Le nom vient de la fonction, la description de la docstring.
Les prompts sont contrôlés par l’utilisateur : le client les liste, l’utilisateur en choisit un et renseigne les arguments.
Les arguments forment une liste plate de chaînes nommées (pas de schéma). Un paramètre avec une valeur par défaut est facultatif.
Renvoyez une str et elle devient un seul message utilisateur. Renvoyez une liste de UserMessage / AssistantMessage pour amorcer une conversation à plusieurs tours.
title= et Field(description=...) sont ce qu’un client affiche dans son interface.
Un argument obligatoire manquant fait échouer toute la requête. Il n’y a pas de résultat d’erreur par prompt.

L’autocomplétion côté serveur des arguments d’un prompt (ou d’un modèle de ressource), c’est Complétions.