MCP ile tool tanımlamak

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

Genel bakış

Resmi Python SDK’sını kullandığınızda MCP server kurmak çok daha basit hale gelir. Tool’lar için karmaşık JSON schema’ları elle yazmak yerine, SDK tüm karmaşıklığı decorator’lar ve type hint’lerle sizin yerinize halleder. Bu derste bellekte dokümanları yöneten basit bir MCP server için iki tool tanımlayacağız.

Resmi Python SDK’sını kullandığınızda MCP server inşa etmek çok daha basit hale gelir. Tool’lar için karmaşık JSON schema’ları elle yazmak yerine, SDK tüm karmaşıklığı decorator’lar ve type hint’lerle sizin yerinize halleder.

Bu örnekte, bellekte saklanan dokümanları yöneten bir MCP server oluşturuyoruz. Server iki temel tool sağlayacak: biri doküman içeriklerini okumak, diğeri ise bir find-and-replace işlemiyle güncellemek için.

MCP server’ı kurmak

Python MCP SDK, server oluşturmayı son derece kolay hale getirir. Tek bir satırla eksiksiz bir MCP server başlatabilirsiniz:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("DocumentMCP", log_level="ERROR")

Bu implementasyon için dokümanlar basit bir Python dictionary’sinde saklanır; key’ler doküman ID’lerini, value’lar ise doküman içeriklerini tutar:

docs = {
    "deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
    "report.pdf": "The report details the state of a 20m condenser tower.",
    "financials.docx": "These financials outline the project's budget and expenditure",
    "outlook.pdf": "This document presents the projected future performance of the",
    "plan.md": "The plan outlines the steps for the project's implementation.",
    "spec.txt": "These specifications define the technical requirements for the equipment"
}

Decorator ile tool tanımı

SDK, tool yaratmayı uzun soluklu bir süreçten temiz ve okunabilir bir şeye dönüştürür. Uzun JSON schema’lar yazmak yerine Python decorator’larını ve type hint’lerini kullanırsınız.

Doküman okuyucu tool’u oluşturmak

İlk tool, Claude’un herhangi bir dokümanı ID’siyle okumasına izin verir. İşte tam implementasyon:

@mcp.tool(
    name="read_doc_contents",
    description="Read the contents of a document and return it as a string."
)
def read_document(
    doc_id: str = Field(description="Id of the document to read")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")

    return docs[doc_id]

@mcp.tool decorator’ı, Claude’un ihtiyaç duyduğu JSON schema’yı otomatik olarak üretir. Pydantic’in Field sınıfı, her argümanın ne beklediğini Claude’un anlamasına yardımcı olan parametre açıklamaları sağlar.

Doküman editör tool’unu inşa etmek

İkinci tool, dokümanlar üzerinde basit find-and-replace işlemleri yapar:

@mcp.tool(
    name="edit_document",
    description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
    doc_id: str = Field(description="Id of the document that will be edited"),
    old_str: str = Field(description="The text to replace. Must match exactly, including whitespace."),
    new_str: str = Field(description="The new text to insert in place of the old text.")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")

    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

Bu tool üç parametre alır: doküman ID’si, bulunacak metin ve değiştirilecek metin. Implementasyon, basit tutmak için Python’un yerleşik replace() metodunu kullanır.

Hata yönetimi

Her iki tool da, Claude var olmayan bir doküman istediğinde durumu yönetmek için temel hata kontrolü içerir. Geçersiz bir doküman ID’si verildiğinde tool’lar, Claude’un anlayıp gerekirse aksiyon alabileceği açıklayıcı bir mesajla ValueError fırlatır.

SDK yaklaşımının temel faydaları

• Python type hint’lerinden otomatik JSON schema üretimi
• Sürdürülmesi kolay, okunabilir kod
• Pydantic üzerinden yerleşik parametre validation
• Manuel schema yazmaya kıyasla az boilerplate
• Geliştirme için type safety ve IDE desteği

MCP Python SDK, eskiden karmaşık olan tool tanımı yazma sürecini Python developer’lar için doğal hissettiren bir şeye dönüştürür. Siz iş mantığına odaklanırsınız; SDK protokol detaylarını halleder.

Temel çıkarımlar

• FastMCP ile tek satırda MCP server başlatabilirsiniz
• @mcp.tool decorator’ı JSON schema’yı otomatik üretir
• Pydantic Field açıklamaları, Claude’un parametreleri anlamasına yardımcı olur
• Hata yönetimi için tool’lar ValueError fırlatabilir
• Type hint odaklı yaklaşım, manuel JSON schema’ya göre çok daha az kod ister