Sampling और roots

handler जुड़े हुए client से दो और चीज़ें माँग सकता है: client के अपने model से एक completion (sampling), और client के workspace folders (roots)।

दोनों अब भी काम करते हैं, उस हर protocol version पर जो SDK बोलता है। लेकिन इनके इर्द-गिर्द design बनाने से पहले यह warning पढ़ लें:

Sampling: client का model उधार लेना

resolver Sample(...) लौटाता है और tool को completion मिलता है, उसी dependency तंत्र के ज़रिए जो Dependencies में Elicit चलाता है:

from typing import Annotated

from mcp.server import MCPServer
from mcp.server.mcpserver import Resolve, Sample
from mcp.types import CreateMessageResult, SamplingMessage, TextContent

mcp = MCPServer("Bookshop")


def draft_blurb(title: str) -> Sample:
    prompt = f"Write a one-sentence blurb for the book {title!r}."
    return Sample(
        [SamplingMessage(role="user", content=TextContent(type="text", text=prompt))],
        max_tokens=60,
    )


@mcp.tool()
async def blurb(title: str, draft: Annotated[CreateMessageResult, Resolve(draft_blurb)]) -> str:
    """Draft a blurb for a book."""
    return draft.content.text if draft.content.type == "text" else "No blurb."

• Sample(messages, max_tokens=...) sampling/createMessage के parameters को दोहराता है। inject की गई value client का CreateMessageResult है; tools या tool_choice दें तो यह CreateMessageResultWithTools बन जाता है।
• client ने sampling capability declare की होनी चाहिए (अगर आप tools या tool_choice देते हैं तो sampling.tools)। अगर नहीं की, तो ऐसी request भेजने के बजाय जिसे client संभाल नहीं सकता, call -32021 protocol error के साथ fail हो जाता है। बिना back-channel वाला 2026 से पहले का session अपने सामान्य no-back-channel error के साथ fail होता है, क्योंकि भेजने के लिए कोई रास्ता ही नहीं है।
• 2026-07-28 पर request multi-round-trip flow के अंदर पहुँचाई जाती है (Multi-round-trip requests); 2025-11-25 पर यह client को भेजी गई एक अलग request होती है। code दोनों तरह से वही रहता है, लेकिन multi-round-trip का नियम ध्यान में रखें: request हर retry round में एक जैसी बननी चाहिए, इसलिए इसे सिर्फ़ tool के arguments और दूसरे स्थिर data से ही बनाएँ।
• include_context को न छेड़ें: "none" के अलावा बाकी values खुद deprecated हैं (SEP-2596) और उन्हें ऐसी capability चाहिए जो लगभग कोई client declare नहीं करता।

Roots: यह कहाँ जाए?

Roots वे folders हैं जिन पर, client के अनुसार, server काम कर सकता है। ये जानकारी के लिए दिए गए मार्गदर्शन हैं, access-control का तंत्र नहीं। resolver ListRoots() लौटाता है:

from typing import Annotated

from mcp.server import MCPServer
from mcp.server.mcpserver import ListRoots, Resolve
from mcp.types import ListRootsResult

mcp = MCPServer("Bookshop")


def workspace_roots() -> ListRoots:
    return ListRoots()


@mcp.tool()
async def catalog_folder(roots: Annotated[ListRootsResult, Resolve(workspace_roots)]) -> str:
    """Pick the folder the catalog export should go to."""
    if not roots.roots:
        return "No workspace folders shared."
    return str(roots.roots[0].uri)

• inject किया गया ListRootsResult Roots की एक सूची रखता है: एक file:// URI और एक वैकल्पिक display name।
• शर्त वही है जो sampling के लिए है: declare की गई roots capability के बिना, request भेजने के बजाय call -32021 के साथ fail हो जाता है।

wire के दूसरी तरफ़, client दोनों requests का जवाब उन्हीं callbacks से देता है जो उसके पास पहले से हैं: sampling_callback और list_roots_callback, जिनकी जानकारी Client callbacks में है।

2025 पीढ़ी के connections पर

ctx.session.create_message(...) और ctx.session.list_roots() उस code के लिए अब भी मौजूद हैं जो session को सीधे चलाता है। ये सिर्फ़ वहीं काम करते हैं जहाँ back-channel मौजूद है (2025 पीढ़ी के, non-stateless connections), और इन्हें call करने पर deprecation warning आती है। ऊपर दिए गए resolver markers ही समर्थित तरीका हैं: वे negotiate हुए version के हिसाब से delivery चुनते हैं और कोई warning नहीं देते।

सारांश

• resolver से Sample(...) या ListRoots() लौटाएँ; tool को CreateMessageResult या ListRootsResult किसी भी दूसरी dependency की तरह मिलता है।
• client को मेल खाती capability declare करनी होगी, वरना request भेजे जाने के बजाय call -32021 के साथ fail हो जाता है।
• दोनों features 2026-07-28 पर deprecated हैं: फ़िलहाल पूरी तरह काम करते हैं, पर नए designs के लिए गलत चुनाव हैं। sampling की जगह provider APIs और roots की जगह स्पष्ट parameters को तरजीह दें।

धीमा tool कितना आगे बढ़ा, यह बताना: Progress।