विषय पर बढ़ें

Media

मशीनी अनुवाद

यह page अंग्रेज़ी documentation से अपने-आप अनुवादित किया गया है, और अंग्रेज़ी page ही प्रामाणिक version है। अगर कुछ गलत लगे, तो अनुवाद page बताता है कि इसकी सूचना कैसे दें।

tool सिर्फ़ text ही लौटा सके, ऐसा नहीं है।

SDK में binary results के लिए दो helpers (Image और Audio) हैं, और एक Icon type है जो client के UI में आपके server, tools, resources और prompts को एक चेहरा देता है।

image लौटाना

return type को Image से annotate करें, उसे किसी file की ओर point करें, और लौटा दें:

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 (पढ़ने के लिए file) या data (raw bytes)।
  • client को जो MIME type दिखता है, उसका अंदाज़ा suffix से लगाया जाता है: logo.png को image/png बताया जाता है।
  • यहाँ logos में कुछ खास नहीं है। server.py के बगल में रखी कोई भी PNG चलेगी: आपके code का render किया हुआ chart, कोई diagram, कोई photo।

Image SDK की सुविधा है, protocol type नहीं। wire पर आपकी return value एक ImageContent block बन जाती है (file के bytes base64-encoded, साथ में MIME type):

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

दो बातें ध्यान देने लायक हैं:

  • data base64 है। आपने bytes को छुआ तक नहीं; SDK ने file पढ़ी और encoding की।
  • structured_content None है। Image model के देखने के लिए content है, application के parse करने के लिए data नहीं: कोई output schema नहीं है। (इसकी तुलना Structured output से करें, जहाँ return annotation ही schema है।)

Info

ImageContent और AudioContent mcp.types में रहते हैं, ठीक उस TextContent के बगल में जो एक सादा str result बन जाता है (Tools)। tool result content blocks की list होता है; दो binary किस्मों को बनाने का सबसे छोटा रास्ता Image और Audio हैं।

इसे आज़माएँ

कोई भी PNG server.py के बगल में रखें, उसका नाम logo.png रखें, और चलाएँ:

uv run mcp dev server.py

Tools tab खोलें और logo को call करें। result कोई string नहीं है: यह image content block है, और Inspector आपकी तस्वीर render करता है। disk पर रखी file से लेकर screen पर दिखते pixels तक, बीच का सारा काम SDK ने किया।

audio लौटाना

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)

result एक AudioContent block है:

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

वही बात: अंदर disk पर रखी file जाती है, बाहर base64 और MIME type आते हैं, कोई output schema नहीं।

bytes या file

दोनों helpers path= की जगह data= (raw bytes) भी लेते हैं। यह उन bytes के लिए है जो कभी अपनी किसी file से आए ही नहीं — कोई database column, कोई HTTP response, कुछ जो 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= के साथ कुछ declare करने की ज़रूरत नहीं: result बनते समय file पढ़ी जाती है, और MIME type का अंदाज़ा suffix से लगाया जाता है:

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

जिस suffix को यह नहीं पहचानता, वह application/octet-stream पर लौट आता है।

Check

data= के साथ कोई filename नहीं होता, इसलिए अंदाज़ा लगाने के लिए कुछ नहीं है। format= भूल जाएँ तो SDK default पर आ जाता है: images के लिए image/png, audio के लिए audio/wav। इस तरह MP3 bytes से Audio बनाएँ तो client को mime_type="audio/wav" बताया जाता है, और फिर वह ईमानदारी से उसे decode करने में नाकाम रहता है। जब data= दें, तो format= भी दें।

resource embed करना

tool एक document भी लौटा सकता है: कुछ text या bytes, साथ में वह URI जहाँ वह रहता है और एक MIME type। यह EmbeddedResource है, content block की एक और किस्म। सादे str के उलट यह client को बताता है कि content क्या है, ताकि client उसे attachment की तरह दिखा सके या ऐसे resource को पहचान सके जिसे वह पहले से जानता है।

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 एक साधारण resource है (इनके बारे में Resources बताता है)। माँगे जाने पर tool वही document model को सौंपता है, और guidelines() को सीधे call करने से सच का एक ही स्रोत बना रहता है।
  • EmbeddedResource और TextResourceContents mcp.types से आते हैं। images जैसा कोई helper यहाँ नहीं है: जो block आप बनाते हैं वह बिना छुए result में जाता है, और कोई structured_content नहीं होता।
  • वही URI इस्तेमाल करें जिसके तहत resource register है, ताकि client बता सके कि attachment और brand://guidelines एक ही document हैं। कोई भी URI मान्य है, register हो या न हो।
result.content  # [EmbeddedResource(type="resource", resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text="# Brand guidelines\n\n..."))]

binary content के लिए TextResourceContents की जगह BlobResourceContents(uri=..., mime_type=..., blob=...) इस्तेमाल करें, जिसमें bytes base64-encoded होकर blob में जाते हैं। सिर्फ़ एक pointer भेजना हो, जिसे client बाद में resources/read कर सके, तो उसकी जगह ResourceLink(name=..., uri=...) लौटाएँ; यह भी content block ही है।

Icons

Icon metadata है, content नहीं। इसमें image नहीं होती; यह URI से किसी image की ओर इशारा करता है, और client उसे fetch करके आपके server के नाम, किसी tool, resource या prompt के बगल में दिखा सकता है।

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 है जिसे client resolve कर सके: https:, या data: URI अगर आप icon को बिना किसी अतिरिक्त fetch के embed करना चाहें।
  • mime_type और sizes ("48x48", या scalable format के लिए "any") से client सही icon चुन पाता है जब आप कई icons दें।
  • theme="light" या theme="dark" किसी icon को एक colour scheme के लिए चिह्नित करता है।

यही icons=[...] keyword MCPServer(...), @mcp.tool(), @mcp.resource() और @mcp.prompt() सब लेते हैं।

client इन्हें कहाँ देखता है

icons उसी चीज़ के साथ चलते हैं जिसे वे सजाते हैं। server के icons client के connect होने पर client.server_info पर आते हैं (2026 पीढ़ी के connections पर यह optional है, इसलिए पहले इसे narrow करें):

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 के icons tools/list से मिले Tool object पर होते हैं, resource के resources/list से मिले Resource पर, और prompt के prompts/list से मिले Prompt पर। field का नाम हमेशा icons होता है।

सारांश

  • tool से Image या Audio लौटाएँ तो client को ImageContent / AudioContent block मिलता है: आपके bytes base64-encoded, MIME type के साथ।
  • इसे path= से बनाएँ और suffix को MIME type तय करने दें, या in-memory data= और स्पष्ट format= से बनाएँ।
  • result में कोई document (text या base64 blob, उसके URI और MIME type के साथ) डालने के लिए EmbeddedResource लौटाएँ, या सिर्फ़ pointer भेजने के लिए ResourceLink।
  • media results में न structured_content होता है, न output schema।
  • Icon एक pointer है: src URI और साथ में optional mime_type, sizes और theme।
  • icons=[...] server पर, tools पर, resources पर और prompts पर काम करता है, और clients इन्हें संबंधित objects पर पाते हैं।

tool किसी result में जो कुछ डाल सकता है, वह सब यही है। जब tool नाकाम होता है तब क्या होता है (और किसे पता चलना चाहिए), यह errors संभालना में है।