Промпты и шаблоны

Промпты в MCP — это шаблоны сообщений, которые сервер предоставляет AI-клиенту. В отличие от инструментов (которые выполняют действия) и ресурсов (которые отдают данные), промпты генерируют текст, готовый к использованию в диалоге с AI-моделью.

Промпт — это мост между сервером и AI-моделью клиента. Сервер знает, что спросить у модели, а клиент решает, когда это сделать.

#Зачем нужны промпты

Представьте, что ваш MCP-сервер предоставляет доступ к аналитической базе данных. Пользователь просит AI-ассистента: «Проанализируй продажи за квартал». AI-клиент может:

Без промпта: самостоятельно составить запрос к БД — но он не знает бизнес-контекст, метрики, формат отчёта
С промптом: использовать промпт сервера, который уже содержит экспертные инструкции — какие метрики важны, как интерпретировать данные, в каком формате дать вывод

Промпт кодирует экспертные знания сервера в виде инструкций для AI-модели.

#Создание простого промпта

from fastmcp import FastMCP

mcp = FastMCP("AnalyticsServer")

@mcp.prompt()
def analyze_sales(quarter: str, year: int) -> str:
    """Генерирует промпт для анализа продаж."""
    return (
        f"Проанализируй продажи за {quarter}-й квартал {year} года. "
        f"Сравни с предыдущим кварталом, выдели тренды и аномалии. "
        f"Предоставь краткий вывод и рекомендации."
    )

Когда клиент вызовет prompts/get с аргументами quarter="3", year=2025, сервер вернёт сгенерированное сообщение. AI-модель клиента получит конкретные инструкции: что анализировать, на что обратить внимание, в каком формате ответить.

#Промпт с аргументами по умолчанию

Аргументы промпта могут иметь значения по умолчанию — тогда они необязательны:

@mcp.prompt()
def debug_code(language: str = "Python", error_type: str = "runtime") -> str:
    """Генерирует промпт для отладки кода."""
    templates = {
        "runtime": "Код выполняется, но даёт неверный результат. Проверь логику.",
        "syntax": "Код не компилируется. Найди синтаксические ошибки.",
        "performance": "Код работает слишком медленно. Оптимизируй алгоритм."
    }
    instruction = templates.get(error_type, "Проанализируй код на ошибки.")
    return f"Я пишу на {language}. {instruction}"

Вызов без аргументов использует language="Python", error_type="runtime". Вызов с error_type="performance" переопределит только один параметр.

#Промпт с Context

Промпт может использовать Context для чтения ресурсов сервера — это добавляет динамические данные в шаблон:

from fastmcp import FastMCP
from fastmcp.server.context import Context

mcp = FastMCP("DocServer")

@mcp.prompt()
async def review_changes(ctx: Context, pr_number: int) -> str:
    """Генерирует промпт для ревью изменений."""
    # Читаем ресурс с последними изменениями
    diff_data = await ctx.read_resource(f"changes://pr/{pr_number}")
    return (
        f"Проведи код-ревью pull request #{pr_number}.\n\n"
        f"Изменения:\n{diff_data}\n\n"
        f"Обрати внимание на: безопасность, производительность, читаемость кода."
    )

Контекст позволяет промпту читать ресурсы в момент генерации. Когда клиент вызовет prompts/get для pr_number=42, сервер сначала прочитает ресурс changes://pr/42, затем включит данные в промпт.

Важно: функция промпта с Context должна быть async, так как ctx.read_resource() — асинхронная операция.

#Многосоставные промпты

Промпт может возвращать не одну строку, а список сообщений — это полезно, когда нужно задать систему и пользовательский запрос отдельно:

from fastmcp import promp

# В некоторых версиях FastMCP промпт может возвращать список кортежей (role, content)
@mcp.prompt()
def code_review_with_context(code: str) -> str:
    """Промпт для код-ревью с контекстом."""
    return (
        f"Ты — senior Python-разработчик. Проведи детальное код-ревью.\n\n"
        f"Код для ревью:\n```python\n{code}\n```\n\n"
        f"Оцени: архитектуру, обработку ошибок, производительность, безопасность."
    )

Хотя FastMCP пока поддерживает возврат строки, вы можете структурировать сообщение с разделителями ролей через системные инструкции в тексте.

#Когда использовать промпты

Промпт уместен, когда:

Сервер знает экспертный контекст, полезный для AI-модели (метрики, формат анализа, приоритеты)
Нужно стандартизировать, как AI подходит к определённой задаче
Сервер хочет подсказать клиенту, что спросить у модели

Промпт не нужен, когда:

Задача простая — AI-модель клиента сама справится
Сервер просто предоставляет данные (используйте ресурсы)
Сервер выполняет действие (используйте инструменты)

#Обнаружение промптов

Как и инструменты, промпты обнаруживаются автоматически. При подключении клиент вызывает prompts/list и получает:

{
  "prompts": [
    {
      "name": "analyze_sales",
      "description": "Генерирует промпт для анализа продаж",
      "arguments": [
        {"name": "quarter", "required": true, "type": "string"},
        {"name": "year", "required": true, "type": "integer"}
      ]
    },
    {
      "name": "debug_code",
      "description": "Генерирует промпт для отладки кода",
      "arguments": [
        {"name": "language", "required": false, "type": "string"},
        {"name": "error_type", "required": false, "type": "string"}
      ]
    }
  ]
}

AI-клиент видит список промптов, их аргументы и описания — и решает, какой промпт использовать для запроса пользователя.