python-sdk/i18n/uk/pages/servers/media.md

translation
sections tool 496394d24d221bf1 4ceb4591180dc6c3 0fd63e4682d02e0c 969ede0bd3686a16 043f526230dd243d 6ee3e9bcfd24047a 1

Медіа

Текст — не єдине, що може повернути інструмент.

SDK містить два допоміжні класи для двійкових результатів (Image і Audio) та тип Icon, що дає серверу, інструментам, ресурсам і промптам власне обличчя в інтерфейсі клієнта.

Повернення зображення

Оголосіть тип результату як Image, вкажіть файл і поверніть об'єкт:

--8<-- "docs_src/media/tutorial001.py"

• Image приймає рівно один із двох аргументів: path (файл, який треба прочитати) або data (сирі байти).
• MIME-тип, який бачить клієнт, визначається за розширенням: logo.png оголошується як image/png.
• У логотипах тут немає нічого особливого. Підійде будь-який PNG поруч із server.py: графік, який побудував ваш код, діаграма, фото.

Image — це зручність SDK, а не тип протоколу. У переданих даних повернене значення стає блоком ImageContent (байти файлу в кодуванні base64 плюс MIME-тип):

result.content             # [ImageContent(type="image", data="iVBORw0KGgoAAAANSUhEUg...", mime_type="image/png")]
result.structured_content  # None

Зверніть увагу на дві речі:

• data — це base64. Байтів ви не торкалися: SDK прочитав файл і закодував його сам.
• structured_content дорівнює None. Image — це вміст, на який дивиться модель, а не дані, які розбирає застосунок: схеми виводу немає. (Порівняйте зі структурованим виводом, де анотація результату і є схемою.)

!!! info ImageContent і AudioContent містяться в mcp.types, поруч із TextContent, на який перетворюється звичайний результат str (Інструменти). Результат інструмента — це список блоків вмісту; Image і Audio — найкоротший спосіб отримати два двійкові різновиди.

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

Покладіть будь-який PNG поруч із server.py, назвіть його logo.png і запустіть:

uv run mcp dev server.py

Відкрийте вкладку Tools і викличте logo. Результат — не рядок: це блок вмісту image, і Inspector показує ваше зображення. Усе між файлом на диску й пікселями на екрані зробив SDK.

Повернення аудіо

Audio має ту саму форму. Залиште logo.png на місці й покладіть поруч будь-який WAV під назвою chime.wav:

--8<-- "docs_src/media/tutorial002.py"

Результат — блок AudioContent:

result.content             # [AudioContent(type="audio", data="UklGR...", mime_type="audio/wav")]
result.structured_content  # None

Те саме: на вході — файл на диску, на виході — base64 і MIME-тип, без схеми виводу.

Байти чи файл

Обидва допоміжні класи приймають також data= (сирі байти) замість path=. Це режим для байтів, які ніколи не були окремим файлом: стовпець бази даних, HTTP-відповідь, щось щойно намальоване в Pillow:

--8<-- "docs_src/media/tutorial003.py"

Із path= оголошувати нічого не потрібно: файл читається під час побудови результату, а MIME-тип визначається за розширенням:

• Image: .png, .jpg, .jpeg, .gif, .webp.
• Audio: .wav, .mp3, .ogg, .flac, .aac, .m4a.

Нерозпізнане розширення дає application/octet-stream.

!!! check Із data= імені файлу немає, тож визначати тип немає з чого. Забудете format= — і SDK візьме типове значення: image/png для зображень, audio/wav для аудіо. Створіть так Audio з байтів MP3 — і клієнту повідомлять mime_type="audio/wav", після чого він сумлінно не зможе це декодувати. Передаєте data= — передавайте й format=.

Іконки

Icon — це метадані, а не вміст. Він не містить зображення, а вказує на нього через URI, і клієнт може завантажити його й показати поруч із назвою сервера, інструментом, ресурсом чи промптом.

--8<-- "docs_src/media/tutorial004.py"

• src — це URI, який клієнт може розв'язати: https: або data:, якщо потрібно вбудувати іконку без додаткового запиту.
• mime_type і sizes ("48x48" або "any" для масштабованого формату) дають клієнту змогу вибрати потрібну, коли ви пропонуєте кілька.
• theme="light" або theme="dark" позначає іконку для однієї колірної схеми.

Той самий іменований аргумент icons=[...] приймають MCPServer(...), @mcp.tool(), @mcp.resource() і @mcp.prompt().

Де їх бачить клієнт

Іконки передаються разом із тим, що вони прикрашають. Іконки сервера надходять під час підключення клієнта, у client.server_info (на з'єднаннях покоління 2026 це поле необов'язкове, тож спершу звузьте тип):

assert client.server_info is not None  # python-sdk servers identify themselves by default
client.server_info.icons  # [Icon(src="https://example.com/brand-kit.png", mime_type="image/png", sizes=["48x48"])]

Іконки інструмента містяться в об'єкті Tool з tools/list, ресурсу — в Resource з resources/list, промпту — в Prompt з prompts/list. Поле завжди називається icons.

Підсумки

• Поверніть з інструмента Image або Audio — і клієнт отримає блок ImageContent / AudioContent: ваші байти в кодуванні base64 з MIME-типом.
• Створюйте їх із path=, і тоді MIME-тип визначить розширення, або з data= у пам'яті плюс явний format=.
• Медіарезультати не мають ні structured_content, ні схеми виводу.
• Icon — це вказівник: URI src плюс необов'язкові mime_type, sizes і theme.
• icons=[...] працює на сервері, інструментах, ресурсах і промптах, а клієнти знаходять їх у відповідних об'єктах.

Це все, що інструмент може покласти в результат. Що відбувається, коли інструмент зазнає невдачі (і хто має про це дізнатися), — на сторінці Обробка помилок.