Technical Tutorials

Yapay zeka entegrasyonu alanı hızla evriliyor. OpenAPI, REST API'lerini belgeleme için uzun süredir altın standart olarak kabul edilirken, Model Bağlam Protokolü (MCP), yapay zeka ajanlarının araçlar ve veri kaynaklarıyla etkileşime geçmesini sağlayan fiili standart olarak öne çıkıyor. Ancak birçok kuruluş bir zorlukla karşı karşıya: Kapsamlı OpenAPI spesifikasyonlarına sahip olmalarına rağmen, bu yetenekleri LLM'ler aracılığıyla MCP üzerinden açmaları gerekiyor. Bu gönderi, bu iki spesifikasyonun nasıl karşılaştırıldığını ve protokol arası etkileşim için bunları nasıl etkili bir şekilde köprüleyebileceğimizi inceliyor.

Temel Farkları Anlama

Temelinde hem MCP hem de OpenAPI, JSON Şeması tabanlı tanımlardır, ancak tasarım felsefeleri önemli ölçüde farklıdır. OpenAPI, insan okunabilir API belgeleri ve sıkı istek/yanıt sözleşmeleri için tasarlanmıştır. HTTP yöntemlerine, yollarına ve güvenlik şemalarına odaklanır. MCP ise makine-makine iletişimi için, özellikle LLM'lerin araçları keşfetmesi ve çağırmak için tasarlanmıştır. HTTP detaylarını soyutlar ve modellerin niyeti ve kullanımı anlamasına yardımcı olan anlamsal tanımlara odaklanır.

Temel farklar şunları içerir:

Ulaşım Katmanı: OpenAPI, HTTP/HTTPS varsayar. MCP ulaşım bağımsızdır, genellikle stdio veya Akışlanabilir HTTP kullanır.
Şema Granülerliği: OpenAPI, tüm istek gövdeleri için sıkı tiplemeyi gerektirir. MCP genellikle esnek girdileri kabul eder ve doğal dil argümanlarını yapılandırılmış veriye dönüştürmek için modele güvenir.
Tanım Amacı: OpenAPI tanımları, geliştiricilerin istemcileri uygulamasına yardımcı olur. MCP tanımları, LLM'lerin bir aracı ne zaman ve nasıl kullanacaklarına karar vermesine yardımcı olur.

Araç Tanımlarını Karşılaştırma

Bir OpenAPI "işlemi", bir MCP "aracına" eşlenir. Pratik bir örneğe bakalım. Varsayalım basit bir veritabanı arama işlevimiz var.

OpenAPI 3.0 Tanımı:


openapi: 3.0.0
info:
  title: Search API
  version: 1.0.0
paths:
  /search:
    post:
      operationId: searchItems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: The search term
              required:
                - query
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object

MCP Araç Tanımı:


{
  "name": "search_items",
  "description": "Searches the product database for items matching the provided query. Returns a list of products with name and price.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The keyword or phrase to search for in product names or descriptions."
      }
    },
    "required": ["query"]
  }
}

MCP tanımının daha betimleyici bir "description" alanı içerdiğine dikkat edin. Bu kritik öneme sahiptir çünkü LLM'ler aracın işlevselliğini anlamak için bu metne güvenir. OpenAPI spesifikasyonu, modelin eylemler hakkında akıl yürütmeye çalışırken daha az sezgisel olan `operationId` ve yol yapısına dayanır.

Etkileşim Stratejileri

OpenAPI'yi MCP'ye veya tersine dönüştürürken, basit bir 1:1 JSON dönüşümüne güvenmemelisiniz. Bunun yerine, aşağıdaki stratejileri göz önünde bulundurun:

Anlamsal Zenginleştirme: OpenAPI spesifikasyonuna dayalı olarak MCP araçları için geliştirilmiş tanımlar üretmek için bir LLM kullanın. Orijinal belge "Kullanıcı ID'sini Al" diyebilir, ancak MCP araç tanımı "Mevcut kimlik doğrulaması yapılmış kullanıcının benzersiz tanımlayıcısını alır" demelidir. Bu bağlam, modelin aracı doğru kullanmasına yardımcı olur.
Parametreleri Düzleştirme: OpenAPI, istek gövdelerinde genellikle iç içe geçmiş nesneler kullanır. MCP, düz ve basit girdi şemalarıyla en iyi şekilde çalışır. LLM için belirsizliği azaltmak için iç içe geçmiş JSON yapılarını mümkün olan yerlerde bireysel parametrelere dönüştürün.
Hata Yönetimi Soyutlaması: OpenAPI, HTTP durum kodlarını tanımlar. MCP araçları genellikle tek bir sonuç nesnesi döndürür. MCP sunucu uygulamanız, alttaki OpenAPI API'sinden gelen HTTP hatalarını yakalamalı ve bunları ham 404'leri modele açmak yerine MCP yanıtı içinde anlamlı hata mesajlarına dönüştürmelidir.

Uygulama En İyi Uygulamaları

Dayanıklı bir köprü oluşturmak için OpenAPI istemcinizi MCP sunucunuzun içinde sarmalayın. MCP sunucu bir adaptör olarak çalışır. LLM'den gelen araç çağrısını alır, OpenAPI spesifikasyonunda tanımlanan HTTP isteğini oluşturur, onu çalıştırır ve yanıtı MCP uyumlu bir sonuca dönüştürür.


// Pseudo-code for an MCP Server handler
async function handleSearchTool(args) {
  // 1. Validate args against MCP inputSchema
  if (!args.query) throw new McpError("Missing query");

  // 2. Construct HTTP request based on OpenAPI logic
  const response = await fetch("https://api.example.com/search", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: args.query })
  });

  // 3. Handle errors
  if (!response.ok) {
    return { content: [{ type: "text", text: `Search failed: ${response.statusText}` }] };
  }

  // 4. Format success response for MCP
  const data = await response.json();
  return {
    content: [{
      type: "text",
      text: `Found ${data.length} items: ${data.map(i => i.name).join(", ")}`
    }]
  };
}

Sonuç

OpenAPI ve MCP rakipler değil, tamamlayıcı standartlardır. OpenAPI, API'nizin davranışı için sözleşmeyi tanımlarken, MCP, yapay zeka ajanlarının bu davranışı nasıl algılayıp etkileşime gireceğini tanımlar. Şema granülerliğindeki ve betimleyici niyetteki farkları anlayarak, mevcut REST API'lerinizi yapay zeka ajanları dünyasına açan etkili adaptörler oluşturabilirsiniz. MCP benimsenmesi arttıkça, OpenAPI spesifikasyonlarınız ile MCP araç tanımları arasında net bir eşleme sürdürmek, ölçeklenebilir yapay zeka destekli uygulamalar geliştiren herkes için temel olacaktır.