Açık Aracı SDK ile MCP Entegrasyonu: Uygulama Rehberi

MCP (Model Context Protocol), yapay zeka araçlarının harici sistemlere bağlanmasını standartlaştıran açık bir protokoldür. Open Agent SDK, MCP entegrasyonu sayesinde üçüncü parti araçları kolayca projelere dahil etmenize olanak tanır. Bu rehberde, MCP’nin temel prensiplerini ve SDK’nin farklı entegrasyon yöntemlerini detaylı olarak inceleyeceğiz.

MCP Protokolü Nedir ve Neden Gereklidir?

MCP, Anthropic tarafından tasarlanmış bir protokoldür ve yapay zeka uygulamalarının harici araçlar ve veri kaynaklarıyla iletişim kurmasını sağlar. Protokolün iki ana bileşeni bulunur:

• MCP Sunucusu (Tool Side): Dosya okuma/yazma, kod arama veya veri tabanı sorgulama gibi araçları standart bir şekilde sunar. Her aracın adı, açıklaması ve girdi şeması tanımlanır.

• MCP İstemcisi (Calling Side): Bu araçları keşfeder, çağırır ve sonuçları JSON-RPC tabanlı iletişimle alır. Protokol, taşıma katmanı olarak stdio, HTTP veya SSE gibi farklı yöntemleri destekler.

Açık Aracı SDK’nın yerleşik araçları çoğu senaryoyu kapsasa da, özel sistemlere entegrasyon gerektiğinde MCP devreye girer. Örneğin, özel bir API’ye bağlanmak veya özel bir veri tabanını sorgulamak istediğinizde, MCP sunucuları sayesinde herhangi bir kod değişikliği yapmadan bu araçları kullanabilirsiniz. Bu esneklik, SDK’nın genişletilebilirliğini önemli ölçüde artırır.

Open Agent SDK’da MCP Entegrasyon Yöntemleri

Open Agent SDK, MCP entegrasyonunu iki farklı şekilde sunar: harici MCP sunucuları ve dahili MCP sunucuları. Her yöntemin avantajları ve kullanım senaryoları bulunmaktadır.

1. Harici MCP Sunucuları: Stdio, HTTP ve SSE

Harici MCP sunucuları, üçüncü parti geliştiriciler tarafından oluşturulan ve standart protokolü destekleyen araçlardır. SDK, bu sunuculara farklı taşıma katmanları üzerinden bağlanabilir:

• Stdio (Standart Girdi/Çıktı): En yaygın kullanılan yöntemdir. SDK, bir alt süreç başlatarak JSON-RPC mesajlarını stdin/stdout üzerinden iletir. Bu yöntem, Node.js veya Python gibi dillerde yazılmış MCP sunucuları için idealdir.

  let servers: [String: McpServerConfig] = [
      "dosya-sistemi": .stdio(McpStdioConfig(
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
      )),
      "git": .stdio(McpStdioConfig(
          command: "uvx",
          args: ["mcp-server-git"],
          env: ["GIT_REPO_PATH": "/my/repo"]
      ))
  ]

Stdio taşıma katmanı, Foundation’un Process sınıfını kullanır ve JSON-RPC mesajlarını yeni satır karakterleriyle ayırır. Güvenlik açısından, SDK tarafından tanımlanan ortam değişkenleri (örneğin CODEANY_API_KEY) varsayılan olarak alt süreçlere aktarılmaz.

• HTTP ve SSE: Uzaktaki MCP sunucularına bağlanmak için kullanılır. HTTP, basit istek-yanıt senaryoları için uygundurken, SSE (Server-Sent Events) sürekli veri akışı gerektiren durumlar için tercih edilir.

  let sseServer: [String: McpServerConfig] = [
      "uzak-araclar": .sse(McpTransportConfig(
          url: "
          headers: ["Authorization": "Bearer token123"]
      ))
  ]

Her iki yöntem de HTTPClientTransport üzerinden çalışır ve taşıma katmanı farklılıkları yalnızca streaming parametresiyle belirlenir.

2. Dahili MCP Sunucuları: Sıfır Ağ İşlem Gideri

Dahili MCP sunucuları, SDK’nın yerleşik araçlarını doğrudan MCP protokolüyle sarmalar. Bu yöntem, herhangi bir ağ işlemi gerektirmediği için gecikme ve karmaşıklığı en aza indirir. Örneğin, SDK’nın yerleşik dosya okuma aracını MCP sunucusu olarak kaydedebilir ve doğrudan kullanabilirsiniz.

let inProcessServer = InProcessMCPServer()
inProcessServer.registerTool(fileReadTool)

Dahili sunucular, özellikle performansın kritik olduğu senaryolarda tercih edilir.

MCP Bağlantı Süreci: Araç Havuzunun Oluşturulması

Open Agent SDK, MCP araçlarını ana araç havuzuna dahil etmek için üç aşamalı bir süreci takip eder:

1. Yapılandırmanın Ayırılması: SDK yapılandırması ile harici sunucular ayrıştırılır. SDK araçları doğrudan yerleşik olarak eklenirken, harici sunucular MCPClientManager tarafından yönetilir.

1. Harici Sunuculara Bağlanma: MCPClientManager, tüm harici sunuculara bağlantı kurar ve araç listesini toplar. Bu süreç, görev grupları kullanılarak eşzamanlı olarak gerçekleştirilir.

1. Araçların Birleştirilmesi: Toplanan tüm araçlar (yerleşik, SDK ve harici MCP araçları) ana araç havuzuna entegre edilir. Bu havuz, SDK’nın çekirdek ve uzman araçlarıyla birleştirilerek nihai kullanıcı arayüzünde sunulur.

Bu süreç, hem basit hem de karmaşık projelerde tutarlı bir araç yönetimi sağlar.

Uygulama Önerileri ve En İyi Uygulamalar

MCP entegrasyonunu projelerinizde verimli bir şekilde kullanmak için aşağıdaki önerilere dikkat edin:

• Güvenlik: Harici MCP sunucularına gönderilen ortam değişkenlerini dikkatli seçin. Özel anahtarlar veya hassas veriler yalnızca gerektiğinde aktarılmalıdır.

• Hata Yönetimi: Bağlantı hatalarına karşı yeniden deneme mekanizmaları kullanın. SDK, varsayılan olarak 2 yeniden deneme ve üstel geri çekilme (1 saniye ile 10 saniye arasında) uygular.

• Performans: Dahili MCP sunucuları, ağ gecikmesini ortadan kaldırdığı için performans gerektiren uygulamalarda tercih edilmelidir.

• Araç Keşfi: MCP sunucularının sunduğu araçları keşfetmek için SDK’nın araç listesi sorgulama yöntemlerini kullanın. Bu, entegre edilen araçların kullanılabilirliğini doğrulamaya yardımcı olur.

MCP entegrasyonu, yapay zeka projelerinizi daha esnek ve güçlü hale getiren önemli bir adımdır. Open Agent SDK’nın sunduğu bu özellikler sayesinde, projelerinizi özel ihtiyaçlarınıza göre kolayca genişletebilirsiniz.