Промпти

Промпт — це шаблон повідомлення, який обирає користувач.

Інструменти призначені для моделі. Промпт — навпаки: користувач обирає його з меню у своєму клієнті (слеш-команда, кнопка), заповнює аргументи, і згенеровані повідомлення потрапляють у розмову так, ніби він набрав їх сам.

Щоб оголосити промпт, поставте @mcp.prompt() над функцією, яка повертає текст.

Ваш перший промпт

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}"

SDK зчитує ті самі три речі, що й з інструмента:

• Ім'я — це ім'я функції: review_code.
• Опис, який показує клієнт, — це docstring: Review a piece of code.
• Аргументи беруться з параметрів. code не має типового значення, тому він обов'язковий.

Ось що клієнт отримує у відповідь на prompts/list:

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

Тут немає JSON Schema. Аргументи промпту — це плоский список іменованих рядкових значень: форма, яку заповнює людина, а не дані, які конструює модель.

Генерування

Клієнт генерує повідомлення за шаблоном через prompts/get, передаючи аргументи. Ваша функція виконується, і повернутий str стає одним повідомленням користувача:

{
  "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"
}

Оце й усе життя промпту: його показують у списку за іменем, генерують на вимогу і вставляють у чат.

mcp.shared.exceptions.MCPError: Internal server error

Спробуйте самі

Запустіть сервер із MCP Inspector:

uv run mcp dev server.py

Відкрийте вкладку Prompts і виберіть review_code. Inspector намалює форму з одним обов'язковим полем code. Заповніть його, згенеруйте промпт — і отримаєте точно те повідомлення користувача, що наведене вище.

Більше ніж одне повідомлення

Рев'ю коду — це одне повідомлення. Сеанс налагодження — це розмова, і промпт може закласти її цілком.

Поверніть список повідомлень замість str:

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 і AssistantMessage імпортуються з mcp.server.mcpserver.prompts.base. Передайте їм str, і вони самі загорнуть його в TextContent. Роль — це ім'я класу.
• Message — їхній спільний базовий клас. Використовуйте його як анотацію типу результату.

Генерування debug_error тепер дає три повідомлення по порядку:

{
  "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"
}

Зверніть увагу на останнє. Заздалегідь заповнена репліка assistant — це спосіб спрямувати наступну відповідь моделі, не змушуючи користувача набирати ці настанови самому.

Заголовки та описи аргументів

review_code — це ім'я функції, а не підпис. Дайте клієнту щось краще для напису на кнопці й опишіть кожен аргумент, щоб форма пояснювала себе сама:

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" — це зрозуміла людині назва, точно як title в інструмента.
• Annotated[str, Field(description=...)] — той самий шаблон, яким на сторінці Інструменти описано параметри інструмента. Тут опис потрапляє на аргумент, а не в схему.
• language має типове значення, тому перестає бути обов'язковим.

Запис у prompts/list тепер містить усе, що потрібно клієнту, щоб намалювати хорошу форму:

{
  "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}
  ]
}

Підсумки

• @mcp.prompt() над функцією робить її промптом. Ім'я — з функції, опис — з docstring.
• Промптами керує користувач: клієнт показує їхній список, користувач обирає один і заповнює аргументи.
• Аргументи — це плоский список іменованих рядків (без схеми). Параметр із типовим значенням необов'язковий.
• Поверніть str — і він стане одним повідомленням користувача. Поверніть список UserMessage / AssistantMessage, щоб закласти багатоходову розмову.
• title= і Field(description=...) — це те, що клієнт показує у своєму інтерфейсі.
• Відсутній обов'язковий аргумент провалює весь запит. Окремого результату з помилкою для промпту немає.

Серверне автодоповнення аргументів промпту (або шаблону ресурсу) — це Автодоповнення.