Örnekleme ve kök dizinler

Bir işleyici, bağlı istemciden iki şey daha isteyebilir: istemcinin kendi modelinden bir tamamlama (örnekleme (sampling)) ve istemcinin çalışma alanı klasörleri (kök dizinler (roots)).

İkisi de SDK'nın konuştuğu her protokol sürümünde hâlâ çalışır. Ancak tasarımınızı bunların üzerine kurmadan önce uyarıyı okuyun:

Örnekleme: istemcinin modelini ödünç alma

Bir çözümleyici Sample(...) döndürür ve araç tamamlamayı alır; bu, Bağımlılıklar sayfasında Elicit'i çalıştıran bağımlılık mekanizmasının aynısıdır:

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 parametrelerini yansıtır. Enjekte edilen değer istemcinin CreateMessageResult'ıdır; tools veya tool_choice geçirirseniz bunun yerine bir CreateMessageResultWithTools olur.
• İstemcinin sampling yeteneğini bildirmiş olması gerekir (tools veya tool_choice geçiriyorsanız sampling.tools). Bildirmediyse çağrı, istemcinin işleyemeyeceği bir istek göndermek yerine -32021 protokol hatasıyla başarısız olur. Geri kanalı (back-channel) olmayan 2026 öncesi bir oturum, gönderecek bir yer olmadığından her zamanki geri-kanal-yok hatasıyla başarısız olur.
• 2026-07-28'de istek, çok turlu (multi-round-trip) akışın içinde iletilir (Çok turlu istekler); 2025-11-25'te ise istemciye gönderilen bağımsız bir istektir. Kod her iki durumda da aynıdır, ancak çok turlu kurala dikkat edin: istek, yeniden deneme turları boyunca birebir aynı şekilde oluşmalıdır. Bu yüzden onu yalnızca aracın argümanlarından ve diğer kararlı verilerden oluşturun.
• include_context'e dokunmayın: "none" dışındaki değerlerin kendisi de kullanım dışı bırakıldı (SEP-2596) ve neredeyse hiçbir istemcinin bildirmediği bir yetenek gerektirir.

Kök dizinler: bu nereye gitmeli?

Kök dizinler, istemcinin sunucunun üzerinde çalışabileceğini söylediği klasörlerdir. Bilgilendirme amaçlı bir yönlendirmedir, erişim denetimi mekanizması değil. Bir çözümleyici ListRoots() döndürür:

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)

• Enjekte edilen ListRootsResult, bir Root listesi taşır: her biri bir file:// URI'si ve isteğe bağlı bir görünen ad.
• Denetim örneklemeyle aynıdır: bildirilmiş bir roots yeteneği yoksa çağrı, isteği göndermek yerine -32021 ile başarısız olur.

Bağlantının diğer ucunda istemci, her iki isteği de zaten sahip olduğu callback'lerle yanıtlar: İstemci callback'leri sayfasında anlatılan sampling_callback ve list_roots_callback.

2025 neslinden bağlantılarda

ctx.session.create_message(...) ve ctx.session.list_roots(), oturumu doğrudan yöneten kod için hâlâ mevcuttur. Yalnızca bir geri kanalın bulunduğu yerde (2025 neslinden, durumsuz olmayan bağlantılarda) çalışırlar ve çağrıldıklarında kullanım dışı bırakma uyarısı verirler. Desteklenen biçim yukarıdaki çözümleyici işaretçileridir: iletim yolunu anlaşılan sürüme göre seçerler ve uyarı vermezler.

Özet

• Bir çözümleyiciden Sample(...) veya ListRoots() döndürün; araç CreateMessageResult'ı veya ListRootsResult'ı diğer bağımlılıklar gibi alır.
• İstemcinin eşleşen yeteneği bildirmesi gerekir; aksi hâlde çağrı, bir istek gönderilmek yerine -32021 ile başarısız olur.
• İki özellik de 2026-07-28'de kullanım dışı bırakıldı: şimdilik tamamen işlevsel, ancak yeni tasarımlar için yanlış tercih. Örnekleme yerine sağlayıcı API'lerini, kök dizinler yerine açık parametreleri tercih edin.

Yavaş bir aracın ne kadar ilerlediğini bildirme: İlerleme.