MCP SDK 2.x ve Gemini Interactions API değişiklikleri sürüm sabitlenmemiş Python MCP sunucularını bozuyor

Ne bozuldu

Bir dev.to yazısı, Google'ın Nano Banana 2 Lite'ını — Google'ın düşük gecikmeli görsel üretme ve düzenleme modeli olan Gemini 3.1 Flash-Lite Image'in takma adı — çalıştıran bir Python MCP sunucusunun, depoda hiçbir şey değişmemiş olmasına rağmen yeni kurulumlarda çalışmayı nasıl bıraktığını belgeliyor. Suçlu, sınırsız iki bağımlılık satırıydı: sürüm sınırları olmayan mcp ve google-genai içeren bir requirements.txt; ikisi de orijinal makale Temmuz'da yayımlandıktan sonra yeni ana sürümlere çözümlendi.

Eylül'deki takip yazısı migration sürecini adım adım anlatıyor, ardından güncellenmiş sunucuyu üç agent istemcisiyle — Claude Code, Codex ve Antigravity CLI — kaydediyor ve canlı API'ye karşı uçtan uca doğruluyor.

Interactions API şema değişikliği

İki kırılmanın büyüğü Google tarafından geldi. Sunucu interactions.create'i store=True ile çağırıyor ve google-genai 1.75.0 altında API, eski Interactions API şemasının artık desteklenmediğini belirten ve kullanıcıyı migration notlarına işaretle birlikte google-genai 2.0.0 veya daha yeni sürüme yükseltmeye yönlendiren bir 400 hatasıyla yanıt veriyor.

Yazara göre bu hata mesajı çözümü adıyla andığı için takdiri hak ediyor — ancak bir MCP sunucusunun içinde neredeyse görünmez. Her tool istisnayı yakalayıp string olarak döndürüyor, bu yüzden agent metnin içine gömülü SDK sürüm numarasıyla genel bir görsel-üretimi-başarısız mesajı gösteriyor.

google-genai 2.x'te yanıt, modelin çıktısının adım listesi olarak geldiği yeni bir şemayı izliyor; üretilen görsel, veri ve mime tipini taşıyan bir kolaylık özelliği olan interaction.output_image olarak açığa çıkıyor. server.py zaten output_image'ı savunmacı bir şekilde okuduğu için SDK'yı yükseltmek tüm çözüm oldu: hiçbir tool fonksiyonu değişmedi. Yazar, eski çıktı alanlarını elle dolaşan kodun, migration notlarının kapsadığı kısım olduğunu belirtiyor.

MCP 2.x yeniden adlandırması

MCP tarafındaki migration daha küçüktü. Import mcp.server.fastmcp.FastMCP'den mcp.server.mcpserver.MCPServer'a taşınıyor ve sunucu nesnesi yeni isimle oluşturuluyor. @mcp.tool() dekoratörü ve mcp.run() olduğu gibi kalıyor, tüm tool gövdeleri de öyle.

Depoda iki 2.x detayı ortaya çıktı. Birincisi, list_tools() artık MCPServer üzerinde async, dolayısıyla test özel bir _tool_manager niteliğine uzanmaktan herkese açık asyncio.run(mcp.list_tools()) çağrısına geçti. İkincisi, sürümsüz bir 2.x sunucu el sıkışmada boş string bildiriyor ve bu protokol testinde görünüyor.

Mock'lı testler kırılmayı neden kaçırdı

Birim testleri sunucu bozuk olduğu sürece geçmeye devam etti, çünkü istemci fabrikasını mock'luyorlar — SDK hiçbir zaman gerçek bir yanıt oluşturmuyor ve API hiç çağrılmıyor. Çözüm, SDK'nın kendi model doğrulaması üzerinden gerçek bir steps-şemalı Interaction oluşturan ve yanıtı response handler'dan geçiren bir test oldu. google-genai 1.x'te bu import mevcut olmadığından test, API sessizce başarısız olmak yerine sesli biçimde düşüyor. Kalan boşluğu gerçek endpoint'e karşı ayrı bir verify-live yeteneği kapatıyor.

Her iki ana sürümü sabitlemek

İki kırılma da sınırsız gereksinimlerden kaynaklandığı için her iki satır artık bir alt ve bir üst sınır taşıyor: google-genai>=2,<3 ve mcp>=2,<3. Alt sınır kodun neye ihtiyacı olduğunu belgeliyor; üst sınır ise bir sonraki ana sürümün rutin bir kurulum üzerinden değil, bilinçli olarak gelmesini sağlıyor. Yeni bir kurulum mcp 2.2.0 ve google-genai 2.22.0 bildirdi.

Güncelleme ayrıca tool yüzeyini dörtten beşe çıkarıyor ve edit_local_image_with_style ekliyor. Sunucu hâlâ Interactions API'nin oturum modeline yaslanıyor: her çağrı sunucu tarafında saklanıyor ve bir interaction ID döndürüyor; bu ID previous_interaction_id olarak geri geçiriliyor ki model, yeni bir prompt ile sıfırdan çizmek yerine zaten ürettiği görseli düzenlesin.

Neden önemli

Bu küçük bir depo, ama başarısızlık kalıbı genel. İki ana sürüm, yayımlandığında kusursuz çalışan bir projenin altına sessizce indi ve yerel hiçbir şey bunu işaretlemedi: mock'lı testler yeşil kalırken her canlı çağrı başarısız oldu ve agent istemcisi açıklayıcı bir API hatasını genel bir başarısızlık string'ine indirgedi. Onarım ucuzdu — bir import yeniden adlandırması, tesadüfen ileriye uyumlu olan savunmacı bir erişimci ve iki sabitlenmiş bağımlılık satırı — ama bunu bulmak, MCP katmanının gizlemek için çok uğraştığı bir hatayı okumak demekti. Eski tutorial'lardan üretilmiş MCP sunucuları bakımını yapan herkes için pratik çıkarımlar şunlar: ana sürümleri sabitleyin, mock yerine gerçek SDK tiplerini çalıştıran en az bir test bulundurun ve 1.x dönemi FastMCP örneklerinin artık yeni kurulumlarda başarısız olacağını bekleyin.