Araç şeması tasarlamak ve MCP sunucusu yayımlamak

Araç sınırını çizen sizsiniz ve bu sınır modelin karar uzayını belirliyor. Tek bir "islem_yap(kip=...)" aracı yazmak seçim hatasını ortadan kaldırmaz, yalnızca yerini değiştirir: model artık yanlış aracı değil yanlış kipi seçer ve bunu araç adından, yetki katmanından veya ölçümden ayırt edemezsiniz.

Sınırı çizerken ölçüt işin konusu değil geri alınabilirliğidir: okumayı yazmayla, geri alınabilir yazmayı geri alınamaz işlemle aynı araçta toplamayın. Bu ayrım sonradan yapılamaz, çünkü yetki ve onay katmanları araç adına bağlanır.

Şema, modelin gördüğü tek biçimsel belgedir. Serbest metin bıraktığınız her alanda model makul görünen ama geçersiz bir değer üretebilir; enum, desen ve sınır koyduğunuz her alanda bu ihtimali baştan kapatırsınız. Kısıt aynı zamanda bir belgeleme biçimidir: kabul edilen değerler listesi, açıklamanın yapamadığı işi yapar.

{
  "ad": "siparis_durumu_guncelle",
  "aciklama": "Sipariş numarası bilinen TEK bir siparişin durumunu günceller. Numara elde yoksa önce siparis_ara çağrılır. İade ve ödeme işlemleri için kullanılmaz.",
  "girdi_semasi": {
    "type": "object",
    "required": ["siparis_no", "yeni_durum"],
    "additionalProperties": false,
    "properties": {
      "siparis_no": { "type": "string", "pattern": "^SP-[0-9]{8}$" },
      "yeni_durum": {
        "type": "string",
        "enum": ["hazirlaniyor", "kargoda", "teslim", "iptal"]
      },
      "not": { "type": "string", "maxLength": 200 }
    }
  }
}

• Sabit bir kümeden gelen her alan enum olsun; "durum: string" modelin yaratıcılığına açık kapı bırakır.
• Kimlik alanlarına desen koyun; biçimi tutmayan uydurma bir numara şemada reddedilir.
• additionalProperties alanını kapatın; şemada olmayan bir alan sessizce yutulmasın.
• Zorunlu alanları gerçekten zorunlu tutun; "opsiyonel ama olmazsa hata" en kötü sözleşmedir.
• Serbest metin kalacaksa uzunluk sınırı koyun ve ne beklendiğini açıklamada yazın.
• Tekillik anahtarını modele gösterilen şemaya koymayın; onu istemci katmanı, çağrı döndükten sonra ekler.

Araç açıklaması dokümantasyon değil seçim yönergesidir. Model onu bir insanın API belgesi okuması gibi değil, karar anında bir etiket gibi okur. Bu yüzden açıklamada işlevin tarifi kadar sınırı da bulunmalı: ne zaman bu araç, ne zaman öteki, hangi ön koşul sağlanmadan hiç çağrılmaz.

ZAYIF
"Sipariş bilgisi döndürür."

GÜÇLÜ
"Sipariş numarası bilinen TEK bir siparişin güncel durumunu döndürür.
Sipariş numarası elde yoksa önce siparis_ara kullanılır.
Bir müşterinin tüm siparişlerini listelemek için kullanılmaz.
Döndürdüğü alanlar müşteriye gösterilebilir; maliyet alanı hariç."

Doğrulama adımı: birbirine en çok benzeyen iki aracın açıklamasını yan yana koyup "hangisi ne zaman" sorusunu bir meslektaşınıza sorun. O ayıramıyorsa model de ayıramaz. Ayrımı açıklamaya yazmadan araç kümesini yayımlamayın.

Bir ajan aynı aracı beklediğinizden çok daha sık iki kez çağırır: zaman aşımından sonra yeniden dener, yanıtı görmeden planını günceller, hatayı yanlış yorumlar. Yan etkisi olan araçlar bu gerçeğe göre yazılmalı. Tekillik anahtarı, "aynı işlem iki kez istendiğinde ne olur" sorusunu çalışma anına bırakmayan tek mekanizmadır.

{
  "calistirilan_cagri": {
    "arac": "siparis_durumu_guncelle",
    "model_argumanlari": {
      "siparis_no": "SP-10428317",
      "yeni_durum": "kargoda"
    },
    "istemcinin_ekledigi": {
      "tekillik_anahtari": "8f2c1b90-5a3d-4c77-9f61-0a2e4d6b8c11"
    }
  },
  "yanit": {
    "durum": "tamam",
    "uygulandi": false,
    "aciklama": "Bu tekillik anahtarı daha önce işlendi; kayıt yeniden güncellenmedi.",
    "siparis_durumu": "kargoda"
  }
}

Hata yanıtı, modelin bir sonraki turda ne yapacağını belirleyen en önemli metindir. "Bir hata oluştu" yazan bir araç modele tek bir seçenek bırakır: aynı çağrıyı tekrarlamak. Hata sözleşmesi bu yüzden başarı sözleşmesi kadar tasarlanmalı ve her hata sınıfı için beklenen model davranışı önceden yazılmalı.

{
  "durum": "hata",
  "kod": "GECERSIZ_PARAMETRE",
  "alan": "yeni_durum",
  "mesaj": "Kabul edilen değerler: hazirlaniyor, kargoda, teslim, iptal.",
  "yeniden_denenebilir": false
}

Araç çıktısı bağlamın en hızlı büyüyen parçası ve çoğu zaman en az okunanıdır. Ham yanıtı olduğu gibi döndürmek iki maliyet üretir: bağlam dolar ve karar için gereken alan kalabalığın içinde kaybolur. Çıktı tasarımı, girdi şeması kadar bir sözleşme meselesidir.

• Yalnızca bir sonraki kararın gerektirdiği alanları döndürün; "ileride lazım olur" diye alan taşımayın.
• Liste dönen araçlarda sayfa boyutunu aracın kendisi sınırlasın; toplam sayı ve sürdürme imleci ayrı alanlarda dönsün.
• Uzun metinleri kırpın ve kırpıldığını açıkça belirtin; sessiz kırpma modeli yanlış sonuca götürür.
• Alan adlarını sabit tutun; her sürümde değişen alan adı hem istemi hem değerlendirmeyi bozar.

MCP (Model Context Protocol), araç ve kaynak yüzeylerini istemciden bağımsız bir protokole taşır: sunucu araçlarını ve şemalarını listeler, istemci bu listeyi alıp modele sunar. Kazanç, aynı araç kümesini her istemcide yeniden yazmaktan kurtulmak; bedeli, ayrı bir süreç ve ayrı bir yetki yüzeyi.

1. 1Sunucu iskeletini kur

   Araçları tek bir kayıt noktasında toplayın; her araç ad, açıklama ve girdi şemasıyla kaydedilsin.

2. 2Şemayı tek kaynaktan üret

   Girdi şemasını koddaki tip tanımından üretin; elle yazılan ikinci bir kopya kaçınılmaz olarak sapar.

3. 3Yetkiyi sunucuda uygula

   Kimlik ve kapsam denetimi araç gövdesinde çalışsın; istemciden gelen hiçbir alan yetki kaynağı sayılmasın.

4. 4İstemciye bağla ve listelemeyi sına

   Bağladıktan sonra araç listesini ve bir örnek çağrıyı istemci üzerinden deneyin; şema hataları burada görünür.

5. 5Sürüm politikasını yaz

   Hangi sürümün hangi araçları taşıdığı ve geriye dönük uyumun ne kadar süreceği yazılı olsun.

Ne zaman değmez: tek bir uygulamanın kendi içindeki üç aracı protokole taşımak, kazanç sağlamadan bir süreç, bir taşıma katmanı ve bir yetki sınırı ekler. Ölçüt araç sayısı değil istemci sayısıdır — küme ikinci bir istemci tarafından kullanılacaksa protokol kendini ödetir.

Araç şeması bir arayüz sözleşmesidir ve sessizce değiştiğinde kırılan şey modeldir. Şema değişikliğini iç bir kod değişikliği gibi değil, yayımlanmış bir API değişikliği gibi ele alın: kırıcı değişiklik sürüm açar.

• Her araç için şemaya uyan ve uymayan birer girdi testi yazın; uymayan girdi net bir hata kodu döndürmeli.
• Yazma araçları için aynı tekillik anahtarıyla iki çağrı testi yazın; ikinci çağrı yeni kayıt açmamalı.
• Alan silmek veya enum daraltmak kırıcı değişikliktir; yeni sürüm açın, eskisini bir süre birlikte çalıştırın.
• Açıklama metnini de sürümleyin; açıklama değişikliği model davranışını şema değişikliği kadar etkiler.

Doğrulama adımı: sahte bir istemciyle araç listesini çekin, her aracı en az bir geçerli ve bir geçersiz girdiyle çağırın, dönen hata kodunu kontrol edin. Bu testin kırmızıya düştüğü gün, ajanın da bozulacağı gündür.