Resource tanımlamak — Introduction to Model Context Protocol

Orijinal İngilizce video — Anthropic Academy / JWPlayer. Aşağıdaki Türkçe metin dersi birebir özetler.

Bu modül için tahmini süre: 10 dakika

Genel bakış

MCP server’larındaki resource’lar, tipik bir HTTP server’daki GET request handler’larına benzer şekilde client’lara veri açmanızı sağlar. Aksiyon yapmak yerine bilgi almak istediğiniz senaryolar için idealdir. Bu derste direct ve templated resource tiplerini, MIME type’ları ve inspector ile testi göreceğiz.

Resource’ları bir örnek üzerinden anlamak

Kullanıcıların dosyalara referans vermek için @document_name yazabildiği bir doküman mention özelliği inşa etmek istediğinizi varsayın. Bu iki işlem gerektirir:

Mevcut tüm dokümanların listesini almak (autocomplete için)
Mention edildiğinde belirli bir dokümanın içeriğini almak

Kullanıcı @ yazdığında, mevcut dokümanları göstermeniz gerekir. Mention içeren bir mesaj gönderildiğinde, o dokümanın içeriğini otomatik olarak Claude’a giden prompt’a enjekte edersiniz.

Resource’lar nasıl çalışır

Resource’lar bir request-response pattern’ini takip eder. Client’ınız bir URI ile ReadResourceRequest gönderir; MCP server da veriyle yanıt verir. URI, erişmek istediğiniz resource’un adresi gibi davranır.

Resource tipleri

İki tür resource vardır:

Direct Resources: Değişmeyen statik URI’ler, örneğin docs://documents
Templated Resources: Parametre içeren URI’ler, örneğin docs://documents/{doc_id}

Templated resource’lar için Python SDK, parametreleri URI’den otomatik olarak parse eder ve fonksiyonunuza keyword argüman olarak aktarır.

Resource implementasyonu

Resource’lar @mcp.resource() decorator’ı ile tanımlanır. Her iki türü nasıl oluşturacağınız:

Direct resource (List Documents)

@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

Templated resource (Fetch Document)

@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

MIME type’lar

Resource’lar her tür veriyi dönebilir — string, JSON, binary vb. mime_type parametresi, döndürdüğünüz veriyi client’lara işaret eder:

application/json — Yapılandırılmış JSON veri
text/plain — Düz metin içerik
Farklı veri formatları için geçerli herhangi bir MIME type

MCP Python SDK return değerlerinizi otomatik serialize eder. Manuel olarak JSON string’e çevirmeniz gerekmez.

Resource’ları test etmek

Resource’larınızı MCP Inspector ile test edebilirsiniz. Server’ı şu komutla çalıştırın:

uv run mcp dev mcp_server.py

Sonra tarayıcıdan inspector’a bağlanın. Şunları göreceksiniz:

Resources: Direct/static resource’larınızı listeler
Resource Templates: Parametre kabul eden templated resource’ları gösterir

Herhangi bir resource’a tıklayıp test ederek client’ınızın alacağı yanıt yapısını tam olarak görebilirsiniz.

Temel noktalar

Resource’lar veri açar, tool’lar aksiyon yapar
Statik veri için direct, parametreli sorgular için templated resource kullanın
MIME type’lar client’lara yanıt formatını anlatır
SDK serialization’ı otomatik yapar
Templated URI’lerdeki parametre adları fonksiyon argümanı olur

Resource’lar, MCP client’lara veri sunmanın temiz bir yoludur; doküman mention, dosya tarama veya server’dan bilgi alma gerektiren her senaryoyu etkinleştirir.

Temel çıkarımlar

Resource’lar HTTP GET handler’larının MCP karşılığıdır
@mcp.resource() decorator’ı ile tanımlanır
İki tür: direct (statik URI) ve templated (parametreli URI)
mime_type parametresi client’a veri formatını işaret eder
MCP Inspector’da Resources ve Resource Templates bölümleri ayrı listelenir
SDK return değerini MIME type’a göre otomatik serialize eder