docs: publish translated docs in twelve languages and the tool that maintains them (#3280)

This commit is contained in:
Max 2026-08-14 17:07:34 +01:00 • committed by GitHub
commit 52ad0a8876
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -0,0 +1,155 @@
---
translation:
sections: [d65c098f37f5b6c3, dd0c2724d6f2877e, 6835bb3570c6714c, ffe823cb0fedd488, f33651add1b59094]
tool: 1
---
# Промпти {#prompts}
**Промпт** — це шаблон повідомлення, який обирає користувач.
Інструменти призначені для моделі. Промпт — навпаки: користувач обирає його з меню у своєму клієнті (слеш-команда, кнопка), заповнює аргументи, і згенеровані повідомлення потрапляють у розмову так, ніби він набрав їх сам.
Щоб оголосити промпт, поставте `@mcp.prompt()` над функцією, яка повертає текст.
## Ваш перший промпт {#your-first-prompt}
```python title="server.py" hl_lines="6-9"
--8<-- "docs_src/prompts/tutorial001.py"
```
SDK зчитує ті самі три речі, що й з інструмента:
* **Ім'я** — це ім'я функції: `review_code`.
* **Опис**, який показує клієнт, — це docstring: `Review a piece of code.`
* **Аргументи** беруться з параметрів. `code` не має типового значення, тому він обов'язковий.
Ось що клієнт отримує у відповідь на `prompts/list`:
```json
{
"name": "review_code",
"description": "Review a piece of code.",
"arguments": [
{"name": "code", "required": true}
]
}
```
Тут немає JSON Schema. Аргументи промпту — це плоский список **іменованих рядкових значень**: форма, яку заповнює людина, а не дані, які конструює модель.
### Генерування {#rendering-it}
Клієнт генерує повідомлення за шаблоном через `prompts/get`, передаючи аргументи. Ваша функція виконується, і повернутий `str` стає **одним повідомленням користувача**:
```json
{
"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"
}
```
Оце й усе життя промпту: його показують у списку за іменем, генерують на вимогу і вставляють у чат.
!!! check
`required` перевіряється ще до запуску вашої функції. Згенеруйте `review_code` без `code` —
і сам запит завершиться помилкою JSON-RPC (код `-32603`):
```text
mcp.shared.exceptions.MCPError: Internal server error
```
Результату з помилкою на кшталт інструмента, який можна було б передати моделі, тут немає, бо моделі в цьому ланцюжку немає взагалі:
виклик викидає виняток. Причина (`Missing required arguments: {'code'}`) потрапляє в лог вашого сервера.
### Спробуйте самі {#try-it}
Запустіть сервер із MCP Inspector:
```console
uv run mcp dev server.py
```
Відкрийте вкладку **Prompts** і виберіть `review_code`. Inspector намалює форму з одним обов'язковим полем `code`. Заповніть його, згенеруйте промпт — і отримаєте точно те повідомлення користувача, що наведене вище.
## Більше ніж одне повідомлення {#more-than-one-message}
Рев'ю коду — це одне повідомлення. Сеанс налагодження — це розмова, і промпт може закласти її цілком.
Поверніть список повідомлень замість `str`:
```python title="server.py" hl_lines="2 13-20"
--8<-- "docs_src/prompts/tutorial002.py"
```
* `UserMessage` і `AssistantMessage` імпортуються з `mcp.server.mcpserver.prompts.base`. Передайте їм `str`, і вони самі загорнуть його в `TextContent`. Роль — це ім'я класу.
* `Message` — їхній спільний базовий клас. Використовуйте його як анотацію типу результату.
Генерування `debug_error` тепер дає три повідомлення по порядку:
```json
{
"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` — це спосіб спрямувати *наступну* відповідь моделі, не змушуючи користувача набирати ці настанови самому.
## Заголовки та описи аргументів {#titles-and-argument-descriptions}
`review_code` — це ім'я функції, а не підпис. Дайте клієнту щось краще для напису на кнопці й опишіть кожен аргумент, щоб форма пояснювала себе сама:
```python title="server.py" hl_lines="10-13"
--8<-- "docs_src/prompts/tutorial003.py"
```
* `title="Code review"` — це зрозуміла людині назва, точно як `title` в інструмента.
* `Annotated[str, Field(description=...)]` — той самий шаблон, яким на сторінці **[Інструменти](tools.md)** описано параметри інструмента. Тут опис потрапляє на аргумент, а не в схему.
* `language` має типове значення, тому перестає бути обов'язковим.
Запис у `prompts/list` тепер містить усе, що потрібно клієнту, щоб намалювати хорошу форму:
```json
{
"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
Якщо ви читали сторінку **[Інструменти](tools.md)**, то вже знаєте все, що є на цій. Той самий декоратор, той самий
docstring як опис, ті самі `Annotated`/`Field`. Змінюється лише те, хто
його запускає (користувач) і куди йде результат (у розмову).
## Підсумки {#recap}
* `@mcp.prompt()` над функцією робить її промптом. Ім'я — з функції, опис — з docstring.
* Промптами **керує користувач**: клієнт показує їхній список, користувач обирає один і заповнює аргументи.
* Аргументи — це плоский список іменованих рядків (без схеми). Параметр із типовим значенням необов'язковий.
* Поверніть `str` — і він стане одним повідомленням користувача. Поверніть список `UserMessage` / `AssistantMessage`, щоб закласти багатоходову розмову.
* `title=` і `Field(description=...)` — це те, що клієнт показує у своєму інтерфейсі.
* Відсутній обов'язковий аргумент провалює весь запит. Окремого результату з помилкою для промпту немає.
Серверне автодоповнення аргументів промпту (або шаблону ресурсу) — це **[Автодоповнення](completions.md)**.