Medya

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:

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

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:

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:

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.

Bir kaynağı gömme

Bir araç bir belge de döndürebilir: bulunduğu URI ve bir MIME türüyle birlikte bir miktar metin ya da bayt. Bu bir EmbeddedResource'tur, bir başka içerik bloğu türü. Düz bir str'den farklı olarak istemciye içeriğin ne olduğunu söyler; böylece istemci onu bir ek olarak gösterebilir ya da zaten bildiği bir kaynağı tanıyabilir.

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 sıradan bir kaynaktır (bunları Kaynaklar sayfası anlatır). Araç, istek üzerine aynı belgeyi modele verir ve guidelines()'ı doğrudan çağırmak tek bir doğruluk kaynağını korur.
• EmbeddedResource ve TextResourceContents, mcp.types modülünden gelir. Görsellerdeki gibi bir yardımcı yoktur: oluşturduğunuz blok sonuca olduğu gibi girer ve structured_content yoktur.
• Kaynağın kaydedildiği URI'yi kullanın; böylece istemci ekin ve brand://guidelines kaynağının aynı belge olduğunu anlayabilir. Kayıtlı olsun olmasın her URI geçerlidir.

result.content  # [EmbeddedResource(type="resource", resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text="# Brand guidelines\n\n..."))]

İkili içerik için TextResourceContents yerine, baytları base64 ile kodlayıp blob alanına koyarak BlobResourceContents(uri=..., mime_type=..., blob=...) kullanın. Yalnızca istemcinin daha sonra resources/read ile okuyabileceği bir işaretçi göndermek için bunun yerine bir ResourceLink(name=..., uri=...) döndürün; o da bir içerik bloğudur.

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.

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.
• Sonuca bir belge (URI'si ve MIME türüyle birlikte metin ya da base64 blob) koymak için bir EmbeddedResource, yalnızca işaretçiyi göndermek için bir ResourceLink döndürü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.