FastMCP 4 genel kullanıma açıldı: sessizce derlenen kırıcı değişikliklerle

Python'da Model Context Protocol server ve client'ları geliştirmek için kullanılan framework olan FastMCP 4, artık genel kullanıma sunuldu. dev.to'da yayımlanan bir geçiş anlatımına göre görünür API yüzeyinin büyük bölümü 3.x'ten geçişte değişmeden kalıyor — FastMCP constructor'ı, @mcp.tool decorator'ı ve mcp.run(transport=...) eskisi gibi çalışıyor. Asıl tehlike, kendini hiç belli etmeyen değişikliklerde: kod derleniyor, import'lar çözülüyor, sonra runtime'da yanlış davranıyor.

Paket bölünmesi yerinde yükseltmeyi çıkmaza sokabiliyor

4.x'te fastmcp dağıtımı, asıl kodun artık bulunduğu fastmcp-slim[client,server]'a bağımlı ince bir meta-pakete dönüştü; anthropic, azure, gemini ve openai gibi seçenekleri kapsayan ek extras'lar da mevcut. Yeni kurulumlar etkilenmiyor. Ancak dev.to'daki yazar, 3.2.x bir ortamda pip install -U fastmcp çalıştırmanın bu temel extras'ları yeniden çözmediğini, import edilen ama hiçbir şey ortaya çıkarmayan bir paket ürettiğini bildiriyor — from fastmcp import Client, kod wheel içinde mevcut olsa bile ImportError veriyor. Çözüm, yeniden kurmadan önce hem fastmcp hem fastmcp-slim'i kaldırmak ya da virtual environment'ı yeniden oluşturmak. İlgili bir değişiklik daha: fastmcp artık version ifşa etmiyor, dolayısıyla buna dayanan her şey importlib.metadata.version("fastmcp")'a geçmeli.

httpx2 exception handler'ları sessizleştiriyor

FastMCP 4, httpx'i dahili olarak bırakıp yeni nesil bir fork olan httpx2'ye geçti. Düz httpx genellikle geçişli olarak kurulu kaldığından, bir FastMCP client çağrısını saran except httpx.ConnectError gibi bir handler hâlâ import ediliyor ve type-check'ten geçiyor — sadece runtime'da hiç eşleşmiyor. Yazar, bu handler'ları grep'leyip ya httpx2'ye geçmeyi ya da genellikle asıl amaç olan fastmcp.exceptions.ToolError yakalamayı öneriyor. FastMCP'ye verilen ve httpx üzerine kurulu her şey — özel bir client factory'si, bir transport'a geçirilen AsyncClient, bir Auth nesnesi — httpx2'ye taşınmalı; httpx bağımlılık olarak kaldığı sürece başka yerlerdeki doğrudan httpx kullanımı etkilenmiyor. İki dolaylı etki daha: TLS doğrulaması artık paketli certifi yerine truststore üzerinden OS güven deposunu kullanıyor (SSL_CERT_FILE ve SSL_CERT_DIR'ye uyuyor), bu da kurumsal CA'lar arkasında farklı davranabilir; ayrıca HTTP log kayıtları httpx/httpcore isim uzaylarından httpx2/httpcore2'ye taşındı, yani logging filtreleri güncellenmeli.

Varsayılan olarak oturumsuz client'lar

Client(...) artık varsayılan olarak mode="auto" kullanıyor ve oturumsuz olan modern 2026-07-28 protokol dönemini pazarlık ediyor. Bu, runtime davranışını görünmez biçimde değiştiriyor: oninitialize handshake'i çalışmıyor, yani ona bağlı middleware'ler veya init hook'ları hiç tetiklenmiyor; ctx.set_state() bir sonraki çağrıya kalıcı olmuyor; ve ctx.elicit(), modern dönemde server tarafından başlatılan bir geri kanal olmadığından hata veriyor. Düz tool çağrıları ve resource okumaları yapan client'ların değişikliğe ihtiyacı yok, ancak oturum durumuna veya elicitation'a bel bağlayan her şey mode="legacy"'ye sabitlemeli. StreamableHttpTransport ayrıca sse_read_timeout= parametresini bıraktı; yerine Client üzerinde bir timeout= argümanı geldi.

Kaldırmalar, import taşınmaları ve sürüm tabanları

Birkaç context metodu kaldırıldı ve AttributeError veriyor: ctx.sample(), ctx.sample_step() ve ctx.list_roots(). FastMCP(sampling_handler=...) seçeneği de onlarla birlikte kaldırıldı; çağıran tarafın modelini ödünç alan server'lar artık doğrudan bir LLM çağırmalı ya da 3.x'te kalmalı. Background task'lar bir extension'a taşındı — fastmcp[tasks] kurulup mcp.add_extension(TasksExtension()) kaydedilene kadar @mcp.tool(task=True) hiçbir şey yapmıyor, aksi halde startup hata veriyor — ve task= artık resource veya prompt'larda geçerli değil.

Import yolları da değişti: Tool ve ToolResult artık fastmcp.tools'tan, Resource fastmcp.resources'tan, TextContent gibi protokol tipleri mcp.types'tan geliyor. mcp.import_server(), mcp.mount()'a dönüştü (snapshot yerine canlı bileşim); as_proxy, fastmcp.server'dan create_proxy oldu ve tool dönüşümleri mcp.add_transform(ToolTransform(...)) üzerinden yapılıyor. Eski CachableToolResult yazım hatası alias olmadan CacheableToolResult olarak düzeltildi ve McpError artık code ve message'ı doğrudan alıyor. SDK v2, model alanlarını camelCase'ten snake_case'e yeniden adlandırdı; eski okumalar bir deprecation uyarısıyla köprülendi ve fastmcp.settings.mcp_camelcase_compat (env FASTMCP_MCP_CAMELCASE_COMPAT) false yapılırsa kalan camelCase okumaları sert hataya dönüşüyor, böylece şimdi temizlenebilirler. Bağımlılık tarafında pydantic >= 2.12 zorunlu bir gereklilik ve FastAPI extra'sı starlette >= 1.0.1 istiyor, yani FastAPI >= 0.133.0 gerekiyor.

Gözden geçirilmeye değer yeni varsayılanlar

dev.to yazısına göre üç ayar, upgrade guide'da tek satır olmadan varsayılan davranışını değiştirdi: telemetry_mode varsayılan olarak "native" ve MCP çağrıları için OpenTelemetry span'lerini otomatik ölçümlüyor (FASTMCP_TELEMETRY_MODE=off ile kapatılır); check_for_updates startup'ta PyPI'yi kontrol ediyor, CI ve container'larda kapatmaya değer; ve client_raise_first_exceptiongroup_error varsayılan olarak true, dolayısıyla client hataları bir ExceptionGroup yerine ilk temel exception olarak yüzeye çıkıyor — except* kullanan kod yeniden gözden geçirilmeli. stateless_http ve http_host_origin_protection gibi daha yeni ayarlar da settings sayfasında listeleniyor.

Neden önemli

MCP server'ları uygulamalarla modeller arasındaki standart tesisat hâline geliyor ve FastMCP, bunları Python'da geliştirmenin yaygın bir yolu. Bu sürümün belirleyici riski, kırıcı değişikliklerinin sessiz olması: CI'den geçen bir yükseltme yine de hiç yakalamayan exception handler'lar, hiç kalıcılaşmayan oturum durumu ve kimsenin istemediği halde veri göndermeye başlayan telemetri ile çıkabilir. Ekipler uygulamalar için fastmcp==4.0.x'e sabitlemeli, kütüphanelerde tabanı fastmcp>=4.0.0 olarak koymalı, yerinde yükseltmeden önce kaldırmalı ve dağıtımdan önce değişen varsayılanları denetlemeli.