Перейти к содержанию

Медиа

Машинный перевод

Эта страница переведена с английской документации автоматически, и основной версией остаётся английская страница. Если что-то читается неправильно, на странице Переводы объясняется, как об этом сообщить.

Текст — не единственное, что может вернуть инструмент.

В 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=[...] работает на сервере, инструментах, ресурсах и промптах, а клиенты находят их в соответствующих объектах.

Это всё, что инструмент может положить в результат. Что происходит, когда инструмент завершается ошибкой (и кто должен об этом узнать), — на странице Обработка ошибок.