Tiplenmiş MCP çıktısı: neden 600+ araç outputSchema'ye sahip

MCP-aracı her şeyi döndürebilir - protokol yanıt biçimini tanımlamayı gerektirmez. Bu yüzden çoğu sunucu ajana çıplak JSON verir ve model metinden yapıyı tahmin eder. Bu, bozulana kadar çalışır: ajan olmayan bir alan alır ya da iç içeliği yanlış yorumlar.

Biz katı bir yol izledik: 600’den fazla MCP-aracımız outputSchema yayınlıyor - aynı OpenAPI sözleşmesinden üretilen, REST API ile aynı olan makine yanıt şeması.

Araç çıkış şemasını ilan ettiğinde, istemci çağrıdan önce yanıt biçimini bilir. Ajan tahmin etmez - chart.houses.ascendant var ve tipinin «sayı, ekvatorial uzunluk derece cinsinden» olduğunu görür. Yapı hakkında daha az hayal gücü, daha doğru çağrı zinciri, yanıtı istemci tarafında doğrulama imkanı.

Katalog aşama aşama büyüdü: başlangıçta 285 araç, ardından 624, şu anda 630’dan fazla - ve tiplenmiş çıktı neredeyse tam kapsama ulaştı (630+‘dan 600’den fazla). Şemalar elle yazılmaz: jeneratör canlı /v1/openapi.json dosyasını derleme sırasında okur, bu yüzden REST ve MCP arasında kayma (drift) yapı itibarıyla mümkün değildir.

Sıkılık bir bedel alır. Araç closed şema (listelenen alanların dışına hiç alan yok) ilan ettiğinde ve yanıt ek metadata içerdiğinde, strict-mode istemci bunu reddeder. chart-family araçlarında tam da bunu yakaladık:

McpError: MCP error -32602: Structured content does not match
the tool's output schema: data must NOT have additional properties

Sebep: oluşturulan Zod şemaları closed biçimdeydi ve backend’in gerçek yanıtı şemada ilan edilmemiş birkaç hizmet metadata alanı taşıyordu. İstemci structuredContent’i strict modda şemaya karşı doğruluyor ve -32602 hatasını fırlatıyordu.

İlginç bir detay: Claude Desktop ve Cursor hatası gösterilmiyordu - onlar loose modda ve ek alanları atlıyor. Tam olarak strict-mode SDK istemcileri düşüyordu, çünkü sıkı doğrulama yapıyorlardı. Yani sorun en popüler istemcilerde görünmezdi ve sadece MCP SDK üzerine kendi entegrasyonlarınızda ortaya çıkıyordu.

Çözüm - tiplemeyi atmak değil, şemaları açık yapmak. Araç jeneratöründe çıkış ZodObject şemaları passthrough biçimine dönüştürülür: ilan edilen alanlar zorunlu ve tipli kalır, ek hizmet alanları doğrulamadan geçer, çağrıyı bozmaz.

Hosted katalog için ayrı bir yedek seçenek uygulanıyor - outputSchema’yı, doğrulamanın zaten kırıldığı araçların kaydından kaldırmak, böylece şemalar tamamen açılana kadar strict istemciler düşmesin. Uzlaşı bilinçli: istemci doğrulaması olmadan doğru bir çağrı, sıkı bir hata almaktan daha iyidir.

Basit bir ders: tiplenmiş MCP çıktısı faydalı, ancak yanıt şeması ek alanlara açık olmalı. API evrimleşiyor, metadata ortaya çıkıyor ve closed şema her eklemeyi strict istemciler için kırıcı bir değişiklik haline getiriyor.

Tiplenmiş katalog her iki yolla da erişilebilir:

// hosted, без установки
{
  "mcpServers": {
    "astroway": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": { "Authorization": "Bearer aw_live_..." }
    }
  }
}

Veya ASTROWAY_API_KEY anahtarıyla stdio paketi npx -y @astroway/mcp. İkisi de aynı tiplenmiş katalogu verir; istemciler hakkında tam rehber /agent-setup/.