Bu, Apidog'un Apidog CLI'yi nasıl geliştirdiğini paylaşan 10 bölümlük bir seridir—API testi ve API yaşam döngüsü yönetimi için bir komut satırı aracı. Sırayla okuyun veya ilginizi çeken herhangi bir yazıya atlayın:
| Başlık | Odak | |
|---|---|---|
| 1 | 126 MCP Tool Build Edtik. Ama Agent için En İyi Çözüm Değil | Sorun keşfi |
| 2 | Neden Yepyeni Apidog CLI Geliştirdik | Architecture development |
| 3 | Altın Kural: CLI Facts Üretir, Model Facts Üzerine Hareket Eder | Core philosophy |
| 4 | agentHints: CLIs'e Agentlarla Konuşmayı Öğretmek |
Structured output |
| 5 | SKILL: Operational Experience'ı Code olarak Shipleme | Operational experience |
| 6 | Sayılar Yalan Söylemez: 30% Daha Az Tool Call, 25% Daha Az Token | Quantitative results |
| 7 | PRD'den Test Loop'a: Apidog CLI ile Tam Bir Agent Workflow | Practical tutorial |
| 8 | Agent Tools için CI/CD Compatibility Neden Tartışılır Değil | DevOps perspective |
| 9 | AI Branch: AI Agents ile Daha Güvenli Project Changes | Security layer |
| 10 | Spec-First Geçen Gün. Skill-First'e Hoş Geldiniz. | Vision & future |
MCP industry hotspot haline geldiğinde, 126 generated tool ile full MCP Server build etti. Yanlış giden şeyler—ve neden daha fazla tool daha iyi Agent enablement anlamına gelmiyor.
MCP Hype
2025'in başlarında MCP (Model Context Protocol) sektörün odak noktası haline geldi.
Anthropic protokolü destekledi. Cursor, Claude Code, Antigravity, çeşitli Agent IDE'ler ve birçok SaaS ürünü hızla aynı yolu izledi. Protokol, AI Agentların dış araçlara ve veri kaynaklarına bağlanması için standart bir yol vaat etti.
Bu dönemde, API'si olan her ürün aynı soruyla karşılaştı:
"MCP'niz var mı?"
Apidog için bu seçim özellikle doğal görünüyordu.
MCP Neden Cevap Gibi Göründü
Apidog kendisi API geliştirme yeteneklerinin kapsamlı bir setini biriktirmişti:
- API dokümantasyonu
- Schema tanımları
- Mock sunucular
- Test senaryaları
- Test senaryoları
- Test suitleri
- Test raporları
- Import/export iş akışları
- Branch işbirliği
- Ve daha pek çoğu
Agentlar yeni yazılım giriş noktası haline gelecekse—kullanıcıların ürünlerle etkileşim kurmanın yeni bir yolu—bu yetenekleri MCP üzerinden açmak gerekli bir bilet gibi görünüyordu.
Yeteneklerimizi MCP araçları olarak paketleyebileceğimize inandık, Agentlar şunları yapabilecekti:
- API dokümantasyonunu sorgulama
- Test senaryaları oluşturma
- Test senaryolarını çalıştırma
- Proje verilerini import/export
- Ortamları ve değişkenleri yönetme
- Branchler arasında işbirliği
Mantık basit: açılan yetenekler arttıkça = daha fazla Agent etkinleştirmesi.
Gerçekte Ne Oluşturduk
Bu işi hafife almadık.
Apidog MCP birkaç elle yazılmış endpoint ile basit bir demo değildi. Tam bir MCP Server idi:
Session Sistemi
MCP client önce bir session başlatır. Server bir sessionId oluşturur ve session durumunu Redis üzerinden kaydeder. Sonraki istekler sessionId ile erişime devam eder.
Başka bir deyişle, tek seferlik bir HTTP çağrısı değil, protokol düzeyinde bir session sistemi idi.
Araç Kategorileri
Araç katmanı da birkaç sabit endpoint ile elle yazılmadı. Apidog'un araçlarını birkaç kategoriye ayırdık:
| Kategori | Açıklama | Örnekler |
|---|---|---|
| Native proje araçları | Proje düzeyinde işlemler için oluşturuldu | Proje özetleri, klasör yapıları, kaynak detayları |
| Built-in domain araçları | Temel Apidog işlevselliği | Import/export, endpoint detayları, test senaryaları, test senaryoları |
| Üretilmiş OpenAPI araçları | OpenAPI tanımlarından otomatik dönüştürüldü | Benzersiz tanımlayıcılar, pathler, HTTP metodları, input Schema ile 126 araç |
Son kategori: 126 üretilmiş araç.
Her üretilmiş araç:
- Benzersiz bir tanımlayıcı
- Belirli bir API path
- HTTP metodu (GET, POST, PUT, DELETE, vb.)
- Alan açıklamaları, türleri ve enum değerleri ile tam bir input Schema
- Tanımlanmış bir return yapısı
Progressive Disclosure
Araç açığa çıkarma baskısını azaltmak için dinamik bir keşif katmanı da oluşturduk:
Agent şunları yapabilir:
- Önce mevcut endpoint araçlarını arama (
listOpenApiEndpoints) - Sonra belirli bir araç için OpenAPI detaylarını alma (
getOpenApiDetails) - Son olarak araç id ile gerçek HTTP çağrısını çalıştırma (
executeOpenApi)
Bu, progressive disclosure denememizdi. Temel endpointlerin tümünü doğrudan ve açıkça açmadık. Agentların önce arama yapacağını, sonra detayları alacağını ve son olarak çalıştıracağını umduk.
Rastgele Araçlar Duvarı
Ancak gerçek işlere girdiğimizde, sorunlar hızla ortaya çıktı.
Basit bir kullanıcı isteğini düşünün:
"Bu endpoint için bir test eklememe yardım et ve doğrulamayı çalıştır."
Uygulama perspektifinden, bu mantıklı bir istek. Apidog şunları yapabilir:
- Endpointleri bul
- Test senaryaları oluştur
- Test senaryolarını çalıştır
- Raporları oluştur
Ancak Agent perspektifinden, bu basit istek bir dizi sürekli kararları tetikler:
| Karar Noktası | Seçenekler | Belirsizlik |
|---|---|---|
| Nereden başlayacağım? | Önce proje bul? Önce endpoint bul? | Net bir rehberlik yok |
| Ne okuyacağım? | Endpoint detaylarını oku? Mevcut test senaryalarını liste? | Her iki görünüşte geçerli |
| Nasıl oluşturacağım? | Doğrudan createTestCase kullan? Önce case grup bul? |
Bilinmeyen gereksinim |
| Nasıl güncelleyeceğim? | Doğrudan update araç çağır? Steps import sonra geri oku? |
Gizli iş akışı |
Agent sadece doğru araç bulmak değil. Kullanıcının sorununu çözmeden önce önce "hangi araç kullanılacak" sorununu çözmesi gerek.
Uygulama perspektifinden, bu sorunların tümü araçlarla çözülebilir. Agent deneyimi perspektifinden, rastgele araçlar duvarı oluştururlar.
Dört Yapısal Sorun
Gerçek dünya testleri ve iç geri bildirimler ile MCP yaklaşımının dört yapısal sorunu belirledik.
Sorun 1: Araç Keşfi Maliyetleri Hızla Artıyor
Apidog sadece birkaç düzine endpoint ile açıklanabilecek bir ürün değil.
| Modül | Detay |
|---|---|
| Endpointler | Liste, get, oluştur, güncelle, sil |
| Schemalar | Liste, get, oluştur, güncelle, sil |
| Ortamlar | Liste, get, oluştur, güncelle, sil, değişkenler |
| Mocks | Yapılandır, etkinleştir, devre dışı bırak |
| Test senaryaları | Liste, get, oluştur, güncelle, sil, kopya |
| Test senaryoları | Liste, get, oluştur, güncelle, sil, steps import, çalıştır |
| Test suitleri | Liste, get, oluştur, güncelle, sil |
| Raporlar | Liste, get, oluştur, indir |
| Import/export | Birden fazla format, seçenek |
| Branchler | Liste, oluştur, birleştir, sil |
Araçlar birkaç düzineden düzine veya yüzlerce büyüdüğünde, Agent kullanıcı sorunlarını çözmeden önce "hangi araç kullanılacak" sorunu çözmesi gerek.
İş akışlarını araç description'a (AI Agentlara araçları açığa çıkarmak için kullanılan alan) yazmaya denedik. Örneğin, bir araç açıklaması açıkça şöyle derdi:
"Endpoint verisini sorgulamadan önce, önce başka bir araçla projeyi doğrulamanız, sonra üçüncü bir araçla proje metadata almanız ve son olarak mevcut araç çağırmanız gerek."
Bu yöntem küçük ölçekli araç setlerinde çalışır. Ancak büyük bir araç duvarında, description kendisi model dikkatini rekabet eder.
Açıklamalara ne kadar çok rehberlik yazarsak, tüketilen token'lar artar—ve Agent'ın gerçekten okuyup takip etme olasılığı azalır.
Sorun 2: İş Schema'sı Context'i İşgal Eder
Her MCP araç sadece bir araç adı değil.
Her araç arkasında:
description(araç ne yapar)input schema(parametreler, türler, zorunlu/isteğe bağlı)- Alan açıklamaları (nested yapılar, kısıtlamalar)
- Enum değerleri (izin verilen seçenekler)
- Return yapıları (response format, hata işleme)
En ihtiyatlı tahmini yapalım:
| Faktör | Değer |
|---|---|
| Araç sayısı | 100+ |
| Araç için ortalama token | ~500 |
| Toplam araç açıklama token'ları | ~50,000 |
Bir kullanıcı sorusu sadece 50 karakter olabilir. Ancak model önce 50,000 token araç açıklaması getirmek zorunda—sadece bir MCP server için.
Bu teorik değil. Sektör verileri bunu destekler.
Cursor'ın resmi blog post "Dynamic Context Discovery" değerli referans veriler sağladı: MCP araç açıklamalarını, terminal sessionlarını ve uzun konuşmaları talep üzerine yüklenen context'e dönüştürerek, runtime token tüketimi 46.9% azaltıldı.
Trae'nin yaklaşımı daha direkt: MCP araç sayısını ve tek araç açıklama uzunluğunu sınırlama:
- Araç sayısı üst limit: 40
- Tek araç açıklama limiti: 8000 karakter
Gerçekten, erken iç testlerde, birçok ekip Apidog MCP'nin Trae'de bazı araçların çağrılabilir olmadığı sorunları rapor etti. Agent sınırlı model context nedeniyle taviz vermek zorunda kaldı ve dış araçlar ilk "kesilen" oldu.
Bu çözümler aynı gerçeği gösteriyor:
Araç açıklamaları sonsuza kadar model context'e giremez.
Sorun 3: Protokol Sessionları Execution Zincirlerini Daha Ağır Yapıyor
Apidog MCP server şunları handle etmek zorunda:
| Protokol Durumu | Açıklama |
|---|---|
| MCP initialize | Client ve server arası handshake |
| sessionId oluşturma | Session için benzersiz tanımlayıcı |
| Redis session storage | Durum kalıcılığı |
| Transport connect/close | Bağlantı yönetimi |
| Session touch | Keep-alive mekanizması |
| DELETE session | Bitince temizleme |
| JSON response or SSE configuration | Output format seçenekleri |
Basit bir araç çağrısı için, bu maliyetler kabul edilebilir. Büyük sayıda çağrı ve sık keşif ile Agent görevleri için, bu durum yönetimi gereksinimleri hem server hem client tarafında karmaşıklık artırır.
Apidog MCP uygulandığında, ekip farklı Agent client'ları (Cursor, Claude Code, Antigravity, Trae, vb.) troubleshooting ve uyum için önemli enerji tüketti. Ancak protokol uyumluluk sorunları devam etti ve resmi MCP protokol yeni sürümlerle patch'lenmeye devam etti.
Tüm taraflar büyük zarar gördü.
Sorun 4: Atomik Araçlar Ürün Semantiğini Doğal olarak İfade Edemez
Apidog'un test senaryolarında, basit bir steps array ifade değil.
Bir test senaryosu şunları içerir:
| Bileşen | Karmaşıklık |
|---|---|
| Import | Endpointler veya mevcut case'lerden steps |
| Read-back | Import sonra tam yapı alma |
| Internal cases | Steps içinde embedded HTTP requests |
| Pre/post processors | Request'ler önce/sonra script'ler |
| Assertions | Response doğrulama kuralları |
| Variable extraction | Response'lardan değer yakalama |
| Runtime environment | Ortam seçimi, değişkenler |
| Report verification | Test sonuçlarını kontrol |
Bunları birden fazla MCP araçlarına böldükten sonra, Agent test orchestration işini kendisi yapmak zorunda.
Araçlar daha atomik olduğunda, model daha fazla ürün iç semantiğini anlamak zorunda:
- Neden import read-back gerek?
- Neden internal case'ler farklı update marker'ları var?
- Neden assertion'lar belirli comparator'lar gerek?
- Neden variable extraction tip kısıtlamaları var?
Bu açıkça model yetenek aralığı dışında.
Apidog ekip iç ürün semantiği için proaktif teknik mühendislik ayarlamaları yapmaya zorlandı. Atomik endpointler passively MCP araç katman dispatch için uyum sağlamak için bir conversion layer ekledi.
Mühendislik zorlukları ve post-maintenance maliyetleri kuşkusuz zorlu.
Kök Neden
Bu dört sorunun kök nedeni aynı şey:
MCP araçları bağlamak için daha iyi, ancak karmaşık R&D görevleri araç bağlantısından daha fazlasına ihtiyaç duyar— executable mühendislik süreçlerine.
| MCP Güç | MCP Sınırlama |
|---|---|
| Standart bağlantı | İş akışı ifade edemez |
| Birleşik protokol | Sıra rehberlik edemez |
| Araç açığa çıkarma | Doğrulama zorlayamaz |
| Dinamik keşif | Karar sağlayamaz |
Birkaç düzine iyi tanımlanmış operasyon ile basit ürünler için MCP iyi çalışır. Agent doğru araç mantıklı tahmin edebilir, çağırabilir ve bir sonuç alabilir.
Apidog gibi ürünler için—düzine modüller, yüzlerce operasyonlar, nested yapılar, gizli iş akışları ve ürün-spesifik semantik ile—MCP tek başına Agentların navigate için struggled bir rastgele araçlar duvarı oluşturur.
Öğrendiklerimiz
| Ders | Anlam |
|---|---|
| Daha fazla araç ≠ daha iyi Agent etkinleştirmesi | Araç sayısı maliyet, fayda değil |
| Araç açıklamaları context rekabet eder | Araç için 500 token × 100 araç = 50,000 token burden |
| Session protokolleri execution overhead ekler | Her çağrı protokol durum yönetimi taşıyan |
| Atomik araçlar ürün bilgisi gerek | Agent orchestrate için internals anlamak zorunda |
| Bağlantı ≠ execution | MCP bağlar; CLI + SKILL çalıştırır |
Pivot
Bu farkındalık bizi farklı bir soru sormaya yöneltti:
MCP agent etkinleştirme için cevap değilse, nedir?
MCP'nin değerini abandon etmedik—standart bağlantılar sağlar, ecosystem için önemli. Ancak şunları yapabilecek bir şey gerek:
- İş akışlarını ifade etmek, sadece araç değil
- Agentları sıralar boyunca rehberlik
- Yazmadan önce doğrulama
- Mühendislik quality gates zorlama
- Karmaşıklığı sistem absorb
Cevabımız: CLI + SKILL
Sonraki postta, MCP Server'dan CLI Runtime'a Neden Geçtik, mimari değişimi keşfedeceğiz—karmaşıklık model context'ten mühendislik sistemine taşındı ve bunun Agent etkinleştirme için her şeyi nasıl değiştirdiğini.
Anahtar Çıkarımlar
- MCP sektörün "Agentlar araçlara nasıl bağlanır" cevabı haline geldi
- 126 MCP araçları oluşturduk, daha fazla araç = daha iyi etkinleştirme düşündük
- Gerçek görevler dört yapısal sorun ortaya çıkardı: discovery maliyetleri, context işgal, session overhead, ürün semantiği
- Kök neden: MCP araçları bağlar, ancak karmaşık görevler executable süreçler gerek
- Araç açıklamaları context tüketdiğinde, daha fazla araç maliyet, fayda değil
Apidog'u indirerek bir workspace'te API'leri tasarlayın, debug yapın, test edin ve dokümante edin.
Apidog CLI hakkında daha fazla bilgi edinin: command-line API test, CI automation ve AI Agent iş akışları.