Перейти до змісту

Медіа

Машинний переклад

Цю сторінку перекладено автоматично з англомовної документації, і основною версією є англомовна сторінка. Якщо щось читається неправильно, на сторінці Переклади пояснено, як про це повідомити.

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

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

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

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

server.py
from pathlib import Path

from mcp.server import MCPServer
from mcp.server.mcpserver import Image

mcp = MCPServer("Brand kit")

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


@mcp.tool()
def logo() -> Image:
    """The brand logo as a PNG."""
    return Image(path=LOGO_FILE)
  • 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:

server.py
from pathlib import Path

from mcp.server import MCPServer
from mcp.server.mcpserver import Audio, Image

mcp = MCPServer("Brand kit")

LOGO_FILE = Path(__file__).parent / "logo.png"
CHIME_FILE = Path(__file__).parent / "chime.wav"


@mcp.tool()
def logo() -> Image:
    """The brand logo as a PNG."""
    return Image(path=LOGO_FILE)


@mcp.tool()
def chime() -> Audio:
    """The notification chime as a WAV."""
    return Audio(path=CHIME_FILE)

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

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

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

Байти чи файл

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

server.py
from pathlib import Path

from mcp.server import MCPServer
from mcp.server.mcpserver import Image

mcp = MCPServer("Brand kit")

LOGO_FILE = Path(__file__).parent / "logo.png"


@mcp.tool()
def logo_from_bytes() -> Image:
    """The brand logo as a PNG."""
    png = LOGO_FILE.read_bytes()  # a database read, an HTTP response, Pillow output...
    return Image(data=png, format="png")

Із 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, і клієнт може завантажити його й показати поруч із назвою сервера, інструментом, ресурсом чи промптом.

server.py
from mcp.server import MCPServer
from mcp.types import Icon

LOGO = Icon(src="https://example.com/brand-kit.png", mime_type="image/png", sizes=["48x48"])
PALETTE = Icon(src="https://example.com/palette.svg", mime_type="image/svg+xml", sizes=["any"])

mcp = MCPServer("Brand kit", icons=[LOGO])


@mcp.tool(icons=[PALETTE])
def palette() -> list[str]:
    """The brand colour palette as hex codes."""
    return ["#1d4ed8", "#f59e0b", "#10b981"]


@mcp.resource("brand://guidelines", icons=[LOGO])
def guidelines() -> str:
    """How to use the brand assets."""
    return "Use the primary colour for calls to action."
  • 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=[...] працює на сервері, інструментах, ресурсах і промптах, а клієнти знаходять їх у відповідних об'єктах.

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