Technical Tutorials

Hızla değişen Yapay Zeka manzarasında, Büyük Dil Modelleri (LLM) güçlüdür ancak genellikle izole durumdadır. Önceden eğitilmiş bilgiye veya promptlar aracılığıyla enjekte edilen bağlama güvenirler; bu da sınırlı, statik veya token maliyetli olabilir. Model Bağlam Protokolü (MCP), bu sorunu çözmek için standart olarak ortaya çıkmıştır. Anthropic tarafından geliştirilen MCP, LLM uygulamalarının dış veri kaynaklarına, araçlara ve ortamlara güvenli bir şekilde bağlanmasını sağlayan açık bir standarttır.

MCP'yi "Yapay Zeka için USB-C" olarak düşünün. Tıpkı USB-C'nin farklı cihazlar arasında şarj ve veri aktarımı için evrensel bir arayüz sağlaması gibi, MCP de LLM'lerin dijital dünya ile etkileşime girmesi için evrensel bir arayüz sağlar. Bu rehberde, MCP mimarisini inceleyecek ve sıfırdan sağlam bir MCP sunucusu nasıl oluşturulacağını göstereceğiz.

MCP Mimarisini Anlama

MCP, istemci-sunucu mimarisi üzerinde çalışır. MCP Ana Makinesi (Claude Desktop veya özel bir uygulama gibi) bağlantıyı başlatır. Bir veya birden fazla MCP Sunucusu ile iletişim kuran bir MCP İstemcisi içerir. Bu sunucular köprü görevi görür ve belirli yetenekleri (Araçlar) veya verileri (Kaynaklar) LLM'e yapılandırılmış, JSON-RPC uyumlu bir formatta sunar.

Bu ayrıştırmanın temel faydası güvenlik ve modülerliktir. LLM'nin kendisi keyfi kod çalıştırmaz veya üçüncü taraf hizmetlere doğrudan API çağrıları yapmaz. Bunun yerine, MCP Sunucusu tarafından tanımlanan belirli eylemleri ister; sunucu bu eylemi kum havuzu (sandbox) ortamında çalıştırır ve sonucu döndürür.

Yetenekleri Tanımlama: Araçlar mı Kaynaklar mı?

Bir MCP sunucusu oluştururken, neyi ortaya koyduğunuza karar vermelisiniz. Genel olarak bunlar iki kategoriye ayrılır:

Araçlar (Tools): LLM'in çalıştırabileceği işlevler. Örneğin, "get_current_weather" (güncel hava durumunu al) veya "create_github_issue" (github sorunu oluştur). Bunlar, dünyayı değiştiren veya taze veri getiren durumlu eylemlerdir.
Kaynaklar (Resources): LLM'in alabileceği salt okunur veri yapıları. Örneğin, bir dosya sistemi yolu veya belirli bir veritabanı tablosu şeması. Bunlar genellikle bir işlev çağrısı gerektirmeden bağlam sağlamak için kullanılır.

TypeScript ile Basit Bir MCP Sunucusu Oluşturma

Bu örnekte, basit bir "Hesap Makinesi" aracı sunan bir sunucu oluşturmak için resmi MCP TypeScript SDK'sını kullanacağız. Bu sunucu, LLM'in temel aritmetik işlemler yapmasına olanak tanır.

Önce gerekli bağımlılıkları yükleyin:


npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript ts-node

Şimdi, sunucu dosyamızı oluşturalım: server.ts. Girdi parametrelerinin sıkı bir şekilde tiplemesini sağlamak için şema doğrulamasında zod kullanarak aracı tanımlayacağız.


import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// MCP Sunucusunu Başlat
const server = new McpServer({
  name: "calculator-server",
  version: "1.0.0",
});

// Bir Araç Tanımla: Hesapla
server.tool(
  "calculate",
  {
    expression: z
      .string()
      .describe("Değerlendirilecek matematiksel bir ifade, örn., '2 + 2'"),
  },
  async ({ expression }) => {
    try {
      // Basit güvenlik kontrolü: Sadece temel operatörlere izin ver
      if (!/^[\d+\-*/(). ]+$/.test(expression)) {
        return {
          content: [{ type: "text", text: "İfade içinde geçersiz karakterler var." }],
        };
      }

      // Not: Üretim ortamında güvenli bir matematik ayrıştırıcı kütüphanesi kullanın.
      // Kullanıcı girdisi üzerinde doğrudan eval() kullanmayın.
      const result = new Function(`return ${expression}`)();
      
      return {
        content: [{ type: "text", text: `Sonuç: ${result}` }],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Hata: ${error.message}` }],
        isError: true,
      };
    }
  }
);

// Bir Kaynak Tanımla: Güncel Zaman Damgası
server.resource(
  "current-time",
  "time://now",
  { title: "Güncel Sunucu Saati" },
  async (uri) => {
    return {
      contents: [
        {
          uri: uri.toString(),
          text: new Date().toISOString(),
        },
      ],
    };
  }
);

// Sunucuyu Çalıştır
const transport = new StdioServerTransport();
server.connect(transport).catch(console.error);

Temel Uygulama Detayları

Araç tanımında zod'un kullanımına dikkat edin. MCP, bir aracın ne beklediğini açıklamak için büyük ölçüde JSON Şemasına dayanır. describe metodu, LLM'e meta veri sağladığı için kritiktir. Açıklamanız belirsizse, LLM geçersiz girdiler uydurabilir veya aracı ne zaman kullanacağını anlamakta zorlanabilir. Açıklama yazımındaki hassasiyet, MCP geliştiricileri için kritik bir beceridir.

Ayrıca, hata yönetimi açıktır. isError: true ayarlayarak, MCP İstemcisine (ve dolayısıyla LLM'e) aracın çalıştırılmasının başarısız olduğunu bildirirsiniz. Bu, LLM'in farklı argümanlarla yeniden denemesine veya kullanıcıya hatayı zarif bir şekilde bildirmesine olanak tanır.

Claude Desktop'a Bağlanma

Sunucunuzu test etmek için MCP Ana Makinenizi yapılandırmanız gerekir. Claude Desktop için, claude_desktop_config.json dosyasını düzenlersiniz (macOS'ta ~/Library/Application Support/Claude/ veya Windows'ta %APPDATA%\Claude konumundadır).


{
  "mcpServers": {
    "calculator": {
      "command": "npx",
      "args": ["ts-node", "/path/to/your/server.ts"]
    }
  }
}

Claude Desktop'u yeniden başlatın. Artık "Hesap Makinesi" aracının geliştirici menüsünde mevcut olduğunu veya sohbet içinde doğrudan kullanılabilir olduğunu görmelisiniz. Claude'dan "15 * 3'ü hesapla" demesini isteyin ve arka planda sunucunuzu çağırdığını izleyin.

En İyi Uygulamalar ve Güvenlik Düşünceleri

En Az Yetki: MCP sunucunuz yalnızca gerekli minimum yetenekleri ortaya koymalıdır. Bir veritabanı bağlantı noktası oluşturuyorsanız, kaçınabiliyorsanız ham SQL çalıştırmayı ortaya koymayın. getUserById gibi belirli, güvenli işlevler sağlayın.
Girdi Doğrulama: Her zaman girdileri doğrulayın. LLM girdiyi üretse de hata yapabilir. Arka uç mantığınıza ulaşmadan önce bozuk verileri reddetmek için şema doğrulaması (Zod gibi) kullanın.
Güçsüzlük (Idempotency): Mümkün olan her yerde, araçları güçsüz olacak şekilde tasarlayın. Bir araç yarıda başarısız olursa, LLM yeniden denemeyi deneyebilir. Yeniden denemelerin, mükerrer ücretlendirme veya veri bozulması gibi yan etkilere neden olmamasını sağlayın.
Günlük Kaydı (Logging): Sunucunuzun içinde ayrıntılı günlük kaydı uygulayın. LLM bir aracı kullanmakta zorlandığında, günlükler hangi parametrelerin iletildiğini ve çağrının neden başarısız olabileceğine dair içgörü sağlayacaktır.

Gelecek Yönleri

MCP hâlâ genç bir protokoldür. Olgunlaştıkça şunları görmeyi bekleyin:

Kimlik Doğrulama Standartları: Korunan API'lere güvenli erişim için protokol spesifikasyonuna doğrudan entegre edilen daha sağlam OAuth2 akışları.
Akışlanabilir Kaynaklar: LLM'lerin borsa endeksleri veya sunucu günlükleri gibi canlı veri kaynaklarını izlemesine olanak tanıyan gerçek zamanlı veri akışları için daha iyi destek.
Çoklu Sunucu Orkestrasyonu: Bağlam penceresi şişkinliğini önlemek için akıllı yönlendirme ile ana makinelerin aynı anda onlarca MCP sunucusunu yönetmesi için geliştirilmiş yetenekler.

Sonuç

MCP sunucuları oluşturmak artık sadece teorik bir egzersiz değil; yapay zeka uygulamalarının yeteneklerini genişletmenin standart yolu haline geliyor. Mantığı modelden ayırarak daha güvenli, sürdürülebilir ve çok yönlü sistemler oluşturursunuz. Basit bir dosya okuyucu mu yoksa karmaşık bir kurumsal veri bağlantı noktası mı oluşturuyorsunuz, MCP size ihtiyaç duyduğunuz temeli sağlar.

Küçük başlayın. İş akışınızdaki belirli bir sorunu çözen tek bir araç oluşturun. Onu kapsamlı bir şekilde test edin. Sonra, genişletin. Ekosistem hızla büyüyor ve erken benimseyenler, LLM uygulamalarının kendi özel ortamlarında akıl yürütme ve eylemde bulunma yeteneklerinde önemli iyileşmeler görüyor.