Промпти

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

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

Щоб оголосити промпт, поставте @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}
  ]
}

Більше ніж текст

UserMessage і AssistantMessage також приймають блок вмісту або допоміжний об'єкт Image / Audio всюди, де приймають str. У промптах трапляються два випадки: прикріпити документ і прикріпити зображення.

Вбудовування файлу

from pathlib import Path

from mcp.server import MCPServer
from mcp.server.mcpserver import Message, UserMessage
from mcp.types import EmbeddedResource, TextResourceContents

mcp = MCPServer("Code Helper")

STYLE_GUIDE_FILE = Path(__file__).parent / "style-guide.md"  # or the path to your file on disk


@mcp.resource("style://python", mime_type="text/markdown")
def style_guide() -> str:
    """The team's Python style guide."""
    return STYLE_GUIDE_FILE.read_text(encoding="utf-8")


@mcp.prompt()
def review_code(code: str) -> list[Message]:
    """Review a piece of code against the team style guide."""
    guide = TextResourceContents(uri="style://python", mime_type="text/markdown", text=style_guide())
    return [
        UserMessage(EmbeddedResource(resource=guide)),
        UserMessage(f"Review this code against the style guide above:\n\n{code}"),
    ]

• Посібник зі стилю — це ресурс за адресою style://python (про них — на сторінці Ресурси), який читається з файлу style-guide.md поруч із server.py. Покладіть туди будь-який Markdown-файл.
• EmbeddedResource(resource=TextResourceContents(...)), обидва з mcp.types, несе файл разом із його URI та MIME-типом як перше повідомлення; запит, що на нього посилається, іде слідом як звичайний текст.
• Вбудовування замість вставлення посібника в f-рядок дає клієнту змогу показати його як вкладення й пізніше знову відкрити style://python, а модель отримує файл дослівно. Для двійкового файлу використовуйте BlobResourceContents із blob у base64.

Після генерування content першого повідомлення — це блок resource:

{"type": "resource", "resource": {"uri": "style://python", "mimeType": "text/markdown", "text": "* Prefer early returns.\n..."}}

Прикріплення зображення

from pathlib import Path

from mcp.server import MCPServer
from mcp.server.mcpserver import Image, Message, UserMessage

mcp = MCPServer("Code Helper")

DIAGRAM_FILE = Path(__file__).parent / "architecture.png"  # or the path to your file on disk


@mcp.prompt()
def explain_component(component: str) -> list[Message]:
    """Explain one component using the architecture diagram."""
    return [
        UserMessage(Image(path=DIAGRAM_FILE)),
        UserMessage(f"Where does {component} sit in this architecture, and what does it talk to?"),
    ]

• Image — допоміжний клас зі сторінки Зображення, аудіо та піктограми. UserMessage перетворює його на блок ImageContent (файл закодовано в base64, MIME-тип вгадано з .png), коли промпт генерується; Audio так само стає AudioContent.
• Покладіть будь-який PNG з іменем architecture.png поруч із server.py. Аргументи промпту — рядки, тому зображення завжди надходить із сервера; component лише дає слова.

{"type": "image", "data": "iVBORw0KGgoAAAANSUhEUg...", "mimeType": "image/png"}

Зміна списку під час роботи

Промпти можна додавати, поки клієнти під'єднані, наприклад щоб користувач міг зберегти інструкцію як власний пункт меню. Зареєструйте промпт, а тоді надішліть сповіщення:

from contextlib import suppress

from mcp.server import MCPServer
from mcp.server.mcpserver import Context
from mcp.server.mcpserver.prompts import Prompt

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.tool()
async def save_template(name: str, instruction: str, ctx: Context) -> str:
    """Save an instruction as a prompt the user can pick from the menu."""

    def template(code: str) -> str:
        return f"{instruction}\n\n{code}"

    with suppress(ValueError):  # replace an existing entry of the same name
        mcp.remove_prompt(name)
    mcp.add_prompt(Prompt.from_function(template, name=name, description=instruction))
    await ctx.notify_prompts_changed()
    await ctx.session.send_prompt_list_changed()
    return f"Saved '{name}' to the prompt menu."

• mcp.add_prompt(Prompt.from_function(fn, name=..., description=...)) реєструє функцію точно так, як це зробив би @mcp.prompt(), а mcp.remove_prompt(name) — зворотна дія. add_prompt залишає наявний запис із тим самим іменем, а не перезаписує його, тому інструмент спершу видаляє старий, щоб збереження працювало як заміна. prompts/list відображає зміну одразу.
• await ctx.notify_prompts_changed() надсилає notifications/prompts/list_changed кожному клієнту 2026-07-28, що слухає потік subscriptions/listen (Підписки). await ctx.session.send_prompt_list_changed() надсилає його клієнту, який зробив виклик, якщо той старший за 2026 (Обслуговування клієнтів старого покоління). Викликайте обидва; кожен нічого не робить, коли сповіщати нікого.
• Клієнт, що отримав сповіщення, знову викликає prompts/list. У Python-класі Client це async with client.listen(prompts_list_changed=True) as sub:, що видає подію PromptsListChanged.

Підсумки

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

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