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

Медіа

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

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

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

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=.

Вбудовування ресурсу

Інструмент може повернути й документ: текст або байти разом з URI, за яким він доступний, і MIME-типом. Це EmbeddedResource, ще один різновид блока вмісту. На відміну від звичайного str, він повідомляє клієнту, що саме це за вміст, тож клієнт може показати його як вкладення або впізнати ресурс, який уже знає.

server.py
from mcp.server import MCPServer
from mcp.types import EmbeddedResource, TextResourceContents

mcp = MCPServer("Brand kit")


@mcp.resource("brand://guidelines", mime_type="text/markdown")
def guidelines() -> str:
    """How to use the brand assets."""
    return "# Brand guidelines\n\nUse the primary colour for calls to action.\n"


@mcp.tool()
def brand_guidelines() -> EmbeddedResource:
    """The brand guidelines as a Markdown document."""
    return EmbeddedResource(
        resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text=guidelines())
    )
  • brand://guidelines — звичайний ресурс (про них — на сторінці Ресурси). Інструмент на запит передає моделі той самий документ, а прямий виклик guidelines() зберігає єдине джерело істини.
  • EmbeddedResource і TextResourceContents беруться з mcp.types. Допоміжного класу, як для зображень, немає: побудований блок потрапляє в результат без змін, і structured_content теж немає.
  • Використовуйте URI, під яким ресурс зареєстровано, щоб клієнт міг зрозуміти, що вкладення й brand://guidelines — той самий документ. Дозволений будь-який URI, зареєстрований чи ні.
result.content  # [EmbeddedResource(type="resource", resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text="# Brand guidelines\n\n..."))]

Для двійкового вмісту замість TextResourceContents використовуйте BlobResourceContents(uri=..., mime_type=..., blob=...) з байтами в кодуванні base64 у полі blob. Щоб надіслати лише вказівник, за яким клієнт зможе пізніше виконати resources/read, поверніть натомість ResourceLink(name=..., uri=...) — це теж блок вмісту.

Іконки

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=.
  • Поверніть EmbeddedResource, щоб покласти в результат документ (текст або blob у base64 з його URI та MIME-типом), або ResourceLink, щоб надіслати лише вказівник.
  • Медіарезультати не мають ні structured_content, ні схеми виводу.
  • Icon — це вказівник: URI src плюс необов'язкові mime_type, sizes і theme.
  • icons=[...] працює на сервері, інструментах, ресурсах і промптах, а клієнти знаходять їх у відповідних об'єктах.

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