Ana içeriğe geç

Medya

Makine çevirisi

Bu sayfa İngilizce dokümantasyondan otomatik olarak çevrildi; esas alınması gereken sürüm İngilizce sayfadır. Yanlış görünen bir şey varsa, nasıl bildireceğinizi Çeviriler sayfası açıklar.

Bir aracın döndürebileceği tek şey metin değildir.

SDK, ikili sonuçlar için iki yardımcı (Image ve Audio) ile sunucunuza, araçlarınıza, kaynaklarınıza ve prompt'larınıza istemcinin arayüzünde bir yüz kazandıran Icon türünü sunar.

Görsel döndürme

Dönüş türünü Image olarak belirtin, bir dosyaya yönlendirin ve döndürün:

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 (okunacak bir dosya) veya data (ham baytlar) argümanlarından tam olarak birini alır.
  • İstemcinin gördüğü MIME türü dosya uzantısından tahmin edilir: logo.png, image/png olarak bildirilir.
  • Burada logolara özgü hiçbir şey yok. server.py dosyasının yanındaki herhangi bir PNG iş görür: kodunuzun çizdiği bir grafik, bir diyagram, bir fotoğraf.

Image bir protokol türü değil, SDK'nın sağladığı bir kolaylıktır. İletilen veride dönüş değeriniz bir ImageContent bloğuna dönüşür (dosyanın base64 ile kodlanmış baytları ve MIME türü):

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

Dikkat edilecek iki nokta:

  • data base64'tür. Baytlara hiç dokunmadınız; dosyayı SDK okudu ve kodlamayı yaptı.
  • structured_content değeri None. Bir Image, uygulamanın ayrıştıracağı veri değil, modelin bakacağı içeriktir: çıktı şeması yoktur. (Dönüş tür ipucunun şemanın ta kendisi olduğu Yapılandırılmış çıktı sayfasıyla karşılaştırın.)

Info

ImageContent ve AudioContent, mcp.types modülünde, düz bir str sonucunun dönüştüğü TextContent'in hemen yanında yer alır (Araçlar). Bir araç sonucu, içerik bloklarından oluşan bir listedir; Image ve Audio iki ikili türü üretmenin en kısa yoludur.

Deneyin

server.py dosyasının yanına herhangi bir PNG koyun, adını logo.png yapın ve çalıştırın:

uv run mcp dev server.py

Tools sekmesini açın ve logo aracını çağırın. Sonuç bir dize değil: bir image içerik bloğu ve Inspector resminizi görüntülüyor. Diskteki dosya ile ekrandaki pikseller arasındaki her şeyi SDK yaptı.

Ses döndürme

Audio da aynı biçimdedir. logo.png dosyasını yerinde bırakın ve yanına herhangi bir WAV dosyasını chime.wav adıyla koyun:

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)

Sonuç bir AudioContent bloğudur:

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

Aynı düzen: diskteki bir dosya girer, base64 ve bir MIME türü çıkar, çıktı şeması yok.

Baytlar veya dosya

Her iki yardımcı da path= yerine data= (ham baytlar) kabul eder. Bu, hiçbir zaman kendi dosyasından gelmemiş baytlar içindir: bir veritabanı sütunu, bir HTTP yanıtı, Pillow'un az önce çizdiği bir şey:

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= ile bildirilecek bir şey yoktur: dosya, sonuç oluşturulurken okunur ve MIME türü uzantıdan tahmin edilir:

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

Tanımadığı bir uzantı application/octet-stream'e geri düşer.

Check

data= ile bir dosya adı yoktur, dolayısıyla tahmin yapılacak bir şey de yoktur. format= argümanını unutursanız SDK bir varsayılana geri düşer: görseller için image/png, ses için audio/wav. MP3 baytlarından bu şekilde bir Audio oluşturursanız istemciye mime_type="audio/wav" söylenir ve o da sadakatle çözmeyi başaramaz. data= geçirdiğinizde format= da geçirin.

Simgeler

Icon içerik değil, meta veridir. Görseli taşımaz; bir URI ile ona işaret eder ve istemci onu getirip sunucunuzun adının, bir aracın, bir kaynağın veya bir prompt'un yanında gösterebilir.

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, istemcinin çözümleyebileceği bir URI'dir: https: veya simgeyi ek bir getirme olmadan gömmek isterseniz bir data: URI'si.
  • mime_type ve sizes ("48x48" ya da ölçeklenebilir bir biçim için "any"), birkaç tane sunduğunuzda istemcinin doğru olanı seçmesini sağlar.
  • theme="light" veya theme="dark", bir simgeyi tek bir renk şeması için işaretler.

Aynı icons=[...] anahtar sözcüğünü MCPServer(...), @mcp.tool(), @mcp.resource() ve @mcp.prompt() kabul eder.

İstemcinin bunları gördüğü yer

Simgeler, süsledikleri şeyle birlikte yolculuk eder. Sunucununkiler istemci bağlandığında client.server_info üzerinde gelir (2026 neslinden bağlantılarda isteğe bağlıdır, bu yüzden önce türünü daraltın):

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"])]

Bir aracın simgeleri tools/list'ten gelen Tool nesnesinde, bir kaynağınkiler resources/list'ten gelen Resource'ta, bir prompt'unkiler prompts/list'ten gelen Prompt'ta bulunur. Alanın adı her zaman icons'tur.

Özet

  • Bir araçtan Image veya Audio döndürün; istemci bir ImageContent / AudioContent bloğu alır: base64 ile kodlanmış baytlarınız ve bir MIME türü.
  • Bunu bir path= ile oluşturup MIME türünü uzantının belirlemesine bırakın ya da bellekteki data= ile açık bir format= kullanın.
  • Medya sonuçları structured_content ve çıktı şeması taşımaz.
  • Icon bir işaretçidir: bir src URI'si ile isteğe bağlı mime_type, sizes ve theme.
  • icons=[...] sunucuda, araçlarda, kaynaklarda ve prompt'larda çalışır; istemciler bunları eşleşen nesnelerde bulur.

Bir aracın bir sonuca koyabileceği her şey bu kadar. Bir araç başarısız olduğunda ne olacağı (ve bundan kimin haberi olması gerektiği) Hataları ele alma sayfasında.