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 Brand-new 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, Apidog 126 generated tool içeren full MCP Server build etti. Sonuç: daha fazla tool, her zaman daha iyi Agent enablement anlamına gelmiyor.
MCP Hype
2025 başında MCP (Model Context Protocol) hızla industry hotspot oldu.
Anthropic protocol'ü öne çıkardı. Cursor, Claude Code, Antigravity, çeşitli Agent IDE'leri ve birçok SaaS product kısa sürede takip etti. MCP'nin vaadi netti: AI Agent'ların external tools ve data sources ile connect olmasını standardize etmek.
API sunan her product aynı soruyla karşılaştı:
"MCP'niz var mı?"
Apidog için bu cevap başlangıçta doğal görünüyordu.
Neden MCP Mantıklı Göründü?
Apidog zaten kapsamlı API development capabilities içeriyordu:
- API documentation
- Schema definitions
- Mock servers
- Test cases
- Test scenarios
- Test suites
- Test reports
- Import/export workflows
- Branch collaboration
- Ve daha fazlası
Eğer Agent'lar software interaction için yeni entry point olacaksa, bu capabilities'i MCP üzerinden expose etmek mantıklı görünüyordu.
Plan basitti:
- Apidog capabilities'i MCP tools olarak paketle.
- Agent'ların bu tools üzerinden API docs okumasını sağla.
- Test case ve scenario oluşturmayı mümkün kıl.
- Import/export, environment, variable ve branch operations'ı expose et.
İlk varsayım şuydu:
More capabilities exposed = more Agent enablement.
Pratikte bu varsayım kırıldı.
Ne Build Ettik?
Bu yalnızca birkaç demo endpoint'ten oluşan basit bir MCP denemesi değildi.
Apidog MCP, complete MCP Server olarak tasarlandı.
1. Session System
MCP client önce session initialize eder.
Server:
-
sessionIdgenerate eder. - Session state'i Redis'e kaydeder.
- Sonraki requests için
sessionIdüzerinden state'i devam ettirir.
Yani flow basit bir one-time HTTP call değil, protocol-level session system idi.
2. Tool Categories
Tool layer birkaç hand-written endpoint'ten oluşmuyordu. Tools üç ana kategoriye ayrıldı:
| Category | Description | Examples |
|---|---|---|
| Native project tools | Project-level operations için build edildi | Project summaries, folder structures, resource details |
| Built-in domain tools | Core Apidog functionality | Import/export, endpoint details, test cases, test scenarios |
| Generated OpenAPI tools | OpenAPI definitions üzerinden otomatik convert edildi | 126 tools with unique identifiers, paths, HTTP methods, input Schema |
Özellikle son kategori kritikti: 126 generated tools.
Her generated tool şunları içeriyordu:
- Unique identifier
- Specific API path
- HTTP method (
GET,POST,PUT,DELETE, etc.) - Complete input Schema
- Field descriptions
- Types
- Enum values
- Defined return structure
3. Progressive Disclosure
Tool exposure pressure'ı azaltmak için dynamic discovery layer eklendi.
Beklenen Agent flow'u şöyleydi:
1. listOpenApiEndpoints
→ Available endpoint tools'u ara
2. getOpenApiDetails
→ Specific tool için OpenAPI details al
3. executeOpenApi
→ Tool id ile actual HTTP call çalıştır
Amaç, tüm endpoints'i doğrudan Agent context'ine yığmak yerine, Agent'ın önce araması, sonra detay alması, en sonunda execute etmesiydi.
Bu progressive disclosure approach kağıt üzerinde doğru görünüyordu. Gerçek tasks içinde ise farklı bir sonuç verdi.
Problem: Wall of Random Tools
Basit bir user request düşünün:
"Bu endpoint için test add et ve verification run et."
Bir developer için bu istek makul görünür. Apidog tarafında capabilities zaten var:
- Endpoint bul
- Test case oluştur
- Test scenario çalıştır
- Report üret
Ama Agent açısından bu request, arka arkaya karar noktaları üretir.
| Decision Point | Options | Uncertainty |
|---|---|---|
| Nereden başlayacak? | Önce project mi bulunacak? Endpoint mi bulunacak? | Clear guidance yok |
| Ne okuyacak? | Endpoint details mi? Existing test cases mi? | İkisi de valid görünüyor |
| Nasıl create edecek? |
createTestCase direkt mi? Önce case group mu? |
Hidden requirement var |
| Nasıl update edecek? |
update tool mu? Import steps + read-back mi? |
Workflow tool'dan anlaşılmıyor |
Agent sadece "right tool" bulmak zorunda kalmıyor. Kullanıcının problemini çözmeden önce, hangi tool sequence'in doğru olduğunu çözmek zorunda kalıyor.
Implementation açısından tüm parçalar vardı. Agent experience açısından ortaya çıkan şey şuydu:
Wall of random tools.
Dört Structural Problem
Internal testing ve real-world feedback sonucunda MCP approach içinde dört temel problem netleşti.
Problem 1: Tool Discovery Cost Hızla Artıyor
Apidog birkaç endpoint'le tanımlanabilecek bir product değil.
| Module | Breakdown |
|---|---|
| Endpoints | List, get, create, update, delete |
| Schemas | List, get, create, update, delete |
| Environments | List, get, create, update, delete, variables |
| Mocks | Configure, enable, disable |
| Test cases | List, get, create, update, delete, duplicate |
| Test scenarios | List, get, create, update, delete, import steps, run |
| Test suites | List, get, create, update, delete |
| Reports | List, get, generate, download |
| Import/export | Multiple formats, options |
| Branches | List, create, merge, delete |
Tools sayısı onlarca veya yüzlerce olduğunda Agent'ın işi değişiyor:
User problem:
"Bu endpoint için test ekle"
Agent'ın gerçek problemi:
1. Hangi module?
2. Hangi tool?
3. Hangi input schema?
4. Hangi call order?
5. Hangi validation?
Tool description içine workflow yazmayı denedik. Örneğin:
"Endpoint data query before, project another tool through confirm need, project metadata third tool through get, finally current tool call."
Bu küçük tool set'lerinde işe yarayabilir. Ama büyük tool wall içinde description alanı da model attention için yarışmaya başlar.
Daha fazla guidance yazdıkça:
- Daha fazla token tüketildi.
- Modelin hepsini okuma ihtimali azaldı.
- Tool selection daha da pahalı hale geldi.
Problem 2: Business Schema Context'i İşgal Ediyor
Her MCP tool sadece bir name değildir.
Her tool ile birlikte şunlar da context'e girer:
descriptioninput schema- Parameters
- Required / optional fields
- Nested field explanations
- Enum values
- Return structures
- Error handling details
Conservative estimate:
| Factor | Value |
|---|---|
| Tool count | 100+ |
| Average tokens per tool | ~500 |
| Total tool description tokens | ~50,000 |
Kullanıcı sorusu 50 karakter olabilir. Ama model, sadece tek bir MCP server için önce yaklaşık 50,000 token tool description ile karşılaşabilir.
Bu sadece theoretical problem değil.
Cursor'ın official blog yazısı Dynamic Context Discovery, MCP tool descriptions, terminal sessions ve long conversations gibi context'leri on-demand loadable hale getirerek runtime token consumption'ı 46.9% azalttığını paylaştı.
Trae'nin yaklaşımı daha direkt:
- Tool count upper limit: 40
- Single tool description limit: 8000 characters
Internal testing sırasında birçok ekip, Apidog MCP'nin Trae'de bazı tools'u invoke edemediğini raporladı. Bunun nedeni, Agent'ın limited model context içinde trade-off yapmak zorunda kalmasıydı. İlk cut edilenler genellikle external tools oldu.
Pratik ders:
Tool descriptions model context'e sonsuz şekilde giremez.
Problem 3: Protocol Sessions Execution Chain'i Ağırlaştırıyor
Apidog MCP server şu protocol state'leri yönetmek zorundaydı:
| Protocol State | Description |
|---|---|
| MCP initialize | Client ve server arasında handshake |
| sessionId generation | Session için unique identifier |
| Redis session storage | State persistence |
| Transport connect/close | Connection management |
| Session touch | Keep-alive mechanism |
| DELETE session | Cleanup when done |
| JSON response or SSE configuration | Output format options |
Basit tool call için bu overhead kabul edilebilir.
Ama Agent tasks genellikle şu pattern'i izler:
explore → inspect → retry → validate → adjust → run again
Bu da çok sayıda call ve sık discovery anlamına gelir. Her call protocol state yönetimi taşıdığında hem server hem client tarafında complexity artar.
Apidog MCP implement edilirken ekip, Cursor, Claude Code, Antigravity ve Trae gibi farklı Agent clients ile compatibility için ciddi efor harcadı. Buna rağmen protocol compatibility issues devam etti ve MCP protocol yeni versiyonlarla patch edilmeye devam etti.
Sonuç:
Tool call basit görünür. Execution chain ağırdır.
Problem 4: Atomic Tools Product Semantics'i Taşıyamıyor
Apidog test scenarios basit bir steps array değildir.
Bir test scenario şunları içerebilir:
| Component | Complexity |
|---|---|
| Import | Endpoints veya existing cases üzerinden steps alma |
| Read-back | Import sonrası full structure okuma |
| Internal cases | Steps içinde embedded HTTP requests |
| Pre/post processors | Request öncesi/sonrası scripts |
| Assertions | Response validation rules |
| Variable extraction | Responses üzerinden value capture |
| Runtime environment | Environment selection, variables |
| Report verification | Test results kontrolü |
Bunları atomic MCP tools'a böldüğünüzde orchestration problemi ortadan kalkmaz. Sadece Agent'a taşınır.
Agent'ın bilmesi gereken product semantics şunlara dönüşür:
- Import sonrası neden read-back gerekiyor?
- Internal case update markers neden farklı?
- Assertions hangi comparator formatını kullanmalı?
- Variable extraction hangi type constraints'e sahip?
- Test run sonrası report nasıl verify edilmeli?
Bu bilgiler tool schema'da tam olarak ifade edilmez. Modelin Apidog internal semantics'i anlaması beklenir.
Bu sürdürülebilir bir boundary değildi.
Root Cause
Dört problemin kökü aynıydı:
MCP tools connecting işini iyi yapar. Ama complex R&D tasks sadece connection değil, executable engineering process ister.
| MCP Strength | MCP Limitation |
|---|---|
| Standardized connection | Workflow ifade edemez |
| Unified protocol | Sequence guide edemez |
| Tool exposure | Validation enforce edemez |
| Dynamic discovery | Engineering judgment sağlayamaz |
Basit products için MCP iyi çalışabilir. Eğer operasyon sayısı azsa ve workflow açıkça anlaşılabiliyorsa Agent doğru tool'u tahmin edip result alabilir.
Ama Apidog gibi products'ta durum farklıdır:
- Dozens of modules
- Hundreds of operations
- Nested structures
- Hidden workflows
- Product-specific semantics
- Validation requirements
Bu ortamda MCP alone, Agent için navigasyonu zor bir wall of random tools üretir.
Implementation Checklist: MCP Tool Set Tasarlarken Ne Kontrol Edilmeli?
Eğer kendi product'ınız için MCP tool set tasarlıyorsanız, sadece "kaç tool expose edebiliriz?" diye sormayın.
Şu checklist daha faydalı:
[ ] Tool sayısı 40+ olduğunda discovery strategy var mı?
[ ] Tool descriptions toplam token budget içinde kalıyor mu?
[ ] Agent'ın doğru call order'ı bilmesi gerekiyor mu?
[ ] Workflow tool descriptions'a mı gömülüyor?
[ ] Validation model judgment'a mı bırakılıyor?
[ ] Atomic tools product semantics gerektiriyor mu?
[ ] Session/state overhead real tasks altında ölçüldü mü?
[ ] Aynı task farklı Agent clients üzerinde test edildi mi?
Bir task'ı şu şekilde modelleyin:
User intent:
"Endpoint için test ekle ve çalıştır"
Required process:
1. Project context bul
2. Endpoint details oku
3. Existing test structure kontrol et
4. Test case oluştur veya update et
5. Scenario'ya import et
6. Read-back yap
7. Assertions ekle
8. Environment seç
9. Run et
10. Report verify et
Eğer bu process'i Agent'ın kendisi keşfetmek zorundaysa, sorun tool eksikliği değil, workflow boundary problemidir.
What We Learned
| Lesson | Implication |
|---|---|
| More tools ≠ better Agent enablement | Tool count benefit değil, cost olabilir |
| Tool descriptions context için yarışır | 500 tokens × 100 tools = 50,000 token burden |
| Session protocols execution overhead ekler | Her call protocol state management taşır |
| Atomic tools product knowledge ister | Agent internal semantics bilmek zorunda kalır |
| Connection ≠ execution | MCP connects; CLI + SKILL executes |
The Pivot
Bu farkındalık bizi farklı bir soruya götürdü:
MCP tek başına Agent enablement answer değilse, ne?
MCP'nin değerini terk etmedik. Standardized connection hâlâ ecosystem için önemli.
Ama complex API workflows için şunlara ihtiyaç vardı:
- Tools değil workflows express etmek
- Agent'ı sequence içinde guide etmek
- Write operation öncesi validate etmek
- Engineering quality gates enforce etmek
- Product complexity'yi model context yerine engineering system içine almak
Bu yüzden geldiğimiz cevap:
CLI + SKILL
Bir sonraki yazıda, Neden Brand-new Apidog CLI Geliştirdik, bu architectural shift'i inceliyoruz: complexity model context'ten engineering system'a nasıl taşındı ve bu Agent enablement için neden kritik?
Key Takeaways
- MCP, "Agent'lar tools'a nasıl connect olur?" sorusuna industry answer oldu.
- Apidog 126 MCP tool build etti; ilk varsayım more tools = better enablement idi.
- Real tasks dört structural problem gösterdi: discovery cost, context invasion, session overhead, product semantics.
- Root cause: MCP connects tools, ama complex tasks executable processes ister.
- Tool descriptions context tükettiğinde daha fazla tool benefit değil, cost olur.
Apidog ile API'leri tek workspace içinde design, mock, test ve document edin. Command-line API testing, CI automation ve AI Agent workflows için Apidog CLI hakkında daha fazla bilgi alın.
Top comments (0)