Ini adalah seri 10 bagian yang menceritakan bagaimana Apidog mengembangkan Apidog CLI, sebuah alat baris perintah untuk pengujian API dan manajemen siklus hidup API. Bacalah secara berurutan atau langsung ke pos mana pun yang menarik minat Anda:
| Judul | Fokus | |
|---|---|---|
| 1 | Kami Membangun 126 Alat MCP. Tapi Itu Bukan Solusi Terbaik untuk Agen | Penemuan masalah |
| 2 | Mengapa Kami Mengembangkan Apidog CLI yang Baru | Pengembangan arsitektur |
| 3 | Aturan Emas: CLI Menghasilkan Fakta, Model Bertindak Berdasarkan Fakta | Filosofi inti |
| 4 | agentHints: Mengajari CLI untuk Berbicara dengan Agen |
Output terstruktur |
| 5 | SKILL: Mengirimkan Pengalaman Operasional sebagai Kode | Pengalaman operasional |
| 6 | Angka Tidak Bohong: 30% Lebih Sedikit Panggilan Alat, 25% Lebih Sedikit Token | Hasil kuantitatif |
| 7 | Dari PRD hingga Loop Pengujian: Alur Kerja Agen Lengkap dengan Apidog CLI | Tutorial praktis |
| 8 | Mengapa Kompatibilitas CI/CD Tidak Dapat Dinegosiasikan untuk Alat Agen | Perspektif DevOps |
| 9 | Cabang AI: Perubahan Proyek yang Lebih Aman dengan Agen AI | Lapisan keamanan |
| 10 | Spec-First Adalah Masa Lalu. Selamat Datang di Skill-First. | Visi & masa depan |
Ketika MCP menjadi sorotan industri, kami membangun Server MCP lengkap dengan 126 alat yang dihasilkan. Berikut adalah apa yang salah—dan mengapa lebih banyak alat tidak berarti pemberdayaan Agen yang lebih baik.
MCP: Sensasi yang Hype
Pada awal 2025, MCP (Model Context Protocol) menjadi sorotan industri.
Anthropic mempromosikan protokol tersebut. Cursor, Claude Code, Antigravity, berbagai IDE Agen, dan banyak produk SaaS dengan cepat mengikutinya. Protokol tersebut menjanjikan cara standar bagi Agen AI untuk terhubung ke alat eksternal dan sumber data.
Selama periode itu, hampir setiap produk dengan API ditanyai pertanyaan yang sama:
"Apakah Anda memiliki MCP?"
Bagi Apidog, pilihan ini terasa sangat alami.
Mengapa MCP Tampak Seperti Jawaban
Apidog sendiri telah mengumpulkan serangkaian kemampuan pengembangan API yang komprehensif:
- Dokumentasi API
- Definisi skema
- Server mock
- Kasus uji
- Skenario uji
- Rangkaian uji
- Laporan uji
- Alur kerja impor/ekspor
- Kolaborasi cabang
- Dan banyak lagi
Jika Agen akan menjadi titik masuk perangkat lunak yang baru—cara baru pengguna berinteraksi dengan produk—maka mengekspos kemampuan ini melalui MCP tampaknya merupakan tiket yang diperlukan.
Kami percaya bahwa jika kami dapat mengemas kemampuan kami sebagai alat MCP, Agen akan dapat:
- Mengajukan pertanyaan pada dokumentasi API
- Membuat kasus uji
- Menjalankan skenario uji
- Mengimpor/mengekspor data proyek
- Mengelola lingkungan dan variabel
- Berkoordinasi antar cabang
Logikanya sederhana: semakin banyak kemampuan yang terekspos = semakin baik pemberdayaan Agen.
Apa yang Sebenarnya Kami Bangun
Kami tidak menganggap ini enteng.
Apidog MCP bukanlah demo sederhana dengan beberapa titik akhir yang ditulis tangan. Itu adalah Server MCP lengkap:
Sistem Sesi
Klien MCP pertama-tama menginisialisasi sesi. Server menghasilkan sessionId dan menyimpan status sesi melalui Redis. Permintaan selanjutnya terus mengakses dengan sessionId.
Dengan kata lain, itu bukan panggilan HTTP satu kali, melainkan sistem sesi tingkat protokol.
Kategori Alat
Lapisan alat juga tidak ditulis tangan dengan beberapa titik akhir tetap. Kami membagi alat Apidog ke dalam beberapa kategori:
| Kategori | Deskripsi | Contoh |
|---|---|---|
| Alat proyek asli | Dibangun untuk operasi tingkat proyek | Ringkasan proyek, struktur folder, detail sumber daya |
| Alat domain bawaan | Fungsionalitas inti Apidog | Impor/ekspor, detail titik akhir, kasus uji, skenario uji |
| Alat OpenAPI yang dihasilkan | Secara otomatis dikonversi dari definisi OpenAPI | 126 alat dengan pengidentifikasi unik, jalur, metode HTTP, Skema masukan |
Kategori terakhir: 126 alat yang dihasilkan.
Setiap alat yang dihasilkan memiliki:
- Pengidentifikasi unik
- Jalur API tertentu
- Metode HTTP (GET, POST, PUT, DELETE, dll.)
- Skema masukan lengkap dengan deskripsi bidang, jenis, dan nilai enum
- Struktur pengembalian yang ditentukan
Pengungkapan Progresif
Untuk mengurangi tekanan eksposur alat, kami juga membangun lapisan penemuan dinamis:
Agen dapat:
- Pertama mencari alat titik akhir yang tersedia (
listOpenApiEndpoints) - Kemudian mendapatkan detail OpenAPI dari alat tertentu (
getOpenApiDetails) - Akhirnya mengeksekusi panggilan HTTP aktual berdasarkan ID alat (
executeOpenApi)
Ini adalah upaya kami untuk pengungkapan progresif. Kami tidak hanya mengekspos semua titik akhir yang mendasari secara langsung dan eksplisit. Kami berharap Agen akan mencari terlebih dahulu, kemudian mendapatkan detail, dan akhirnya mengeksekusi.
Dinding Alat Acak
Namun ketika memasuki tugas-tugas nyata, masalah dengan cepat muncul.
Pertimbangkan permintaan pengguna yang sederhana:
"Bantu saya menambahkan tes untuk titik akhir ini dan jalankan verifikasi."
Dari perspektif implementasi, ini adalah permintaan yang masuk akal. Apidog memiliki kemampuan untuk:
- Menemukan titik akhir
- Membuat kasus uji
- Menjalankan skenario uji
- Menghasilkan laporan
Namun dari perspektif Agen, permintaan sederhana ini sebenarnya memicu serangkaian penilaian berkelanjutan:
| Titik Keputusan | Opsi | Ketidakpastian |
|---|---|---|
| Mulai dari mana? | Temukan proyek terlebih dahulu? Temukan titik akhir terlebih dahulu? | Tidak ada panduan yang jelas |
| Apa yang harus dibaca? | Baca detail titik akhir? Daftar kasus uji yang ada? | Keduanya tampak valid |
| Bagaimana cara membuat? | Gunakan createTestCase secara langsung? Temukan grup kasus terlebih dahulu? |
Persyaratan tidak diketahui |
| Bagaimana cara memperbarui? | Panggil alat update secara langsung? Impor langkah-langkah lalu baca kembali? |
Alur kerja tersembunyi |
Agen tidak hanya perlu menemukan alat yang tepat. Ia perlu menyelesaikan masalah "alat mana yang akan digunakan" terlebih dahulu, sebelum ia bahkan dapat mulai menyelesaikan masalah pengguna.
Dari perspektif implementasi, semua masalah ini dapat diselesaikan melalui alat. Dari perspektif pengalaman Agen, masalah-masalah ini membentuk dinding alat acak.
Empat Masalah Struktural
Melalui pengujian dunia nyata dan umpan balik internal, kami mengidentifikasi empat masalah struktural dengan pendekatan MCP.
Masalah 1: Biaya Penemuan Alat Meningkat dengan Cepat
Apidog bukanlah produk yang dapat dijelaskan hanya dengan selusin titik akhir.
| Modul | Rincian |
|---|---|
| Titik akhir | Daftar, dapatkan, buat, perbarui, hapus |
| Skema | Daftar, dapatkan, buat, perbarui, hapus |
| Lingkungan | Daftar, dapatkan, buat, perbarui, hapus, variabel |
| Mock | Konfigurasi, aktifkan, nonaktifkan |
| Kasus uji | Daftar, dapatkan, buat, perbarui, hapus, duplikat |
| Skenario uji | Daftar, dapatkan, buat, perbarui, hapus, impor langkah-langkah, jalankan |
| Rangkaian uji | Daftar, dapatkan, buat, perbarui, hapus |
| Laporan | Daftar, dapatkan, hasilkan, unduh |
| Impor/ekspor | Beberapa format, opsi |
| Cabang | Daftar, buat, gabungkan, hapus |
Ketika alat tumbuh dari selusin menjadi puluhan atau ratusan, Agen perlu menyelesaikan masalah "alat mana yang akan digunakan" sebelum dapat mulai menyelesaikan masalah pengguna.
Kami mencoba menulis alur kerja ke dalam description alat (bidang yang digunakan untuk mengekspos alat ke Agen AI). Misalnya, deskripsi alat akan secara eksplisit menyatakan:
"Sebelum mengkueri data titik akhir, Anda perlu mengkonfirmasi proyek melalui alat lain terlebih dahulu, kemudian mendapatkan metadata proyek melalui alat ketiga, dan akhirnya memanggil alat saat ini."
Metode ini berfungsi dalam kumpulan alat berskala kecil. Namun dalam dinding alat yang masif, description itu sendiri bersaing untuk perhatian model.
Semakin banyak panduan yang kami tulis dalam deskripsi, semakin banyak token yang dikonsumsi—dan semakin kecil kemungkinan Agen akan benar-benar membaca dan mengikutinya.
Masalah 2: Skema Bisnis Menginvasi Konteks
Setiap alat MCP bukan hanya nama alat.
Di balik setiap alat ada:
description(apa yang dilakukan alat)input schema(parameter, jenis, wajib/opsional)- Penjelasan bidang (struktur bersarang, batasan)
- Nilai enum (opsi yang diizinkan)
- Struktur pengembalian (format respons, penanganan kesalahan)
Mari kita lakukan perkiraan konservatif:
| Faktor | Nilai |
|---|---|
| Jumlah alat | 100+ |
| Rata-rata token per alat | ~500 |
| Total token deskripsi alat | ~50.000 |
Pertanyaan pengguna mungkin hanya 50 karakter. Tetapi model dipaksa untuk terlebih dahulu memperkenalkan 50.000 token deskripsi alat—hanya untuk satu server MCP.
Ini bukan teori. Data industri mendukungnya.
Postingan blog resmi Cursor "Dynamic Context Discovery" memberikan data referensi yang berharga: dengan mengonversi deskripsi alat MCP, sesi terminal, dan percakapan panjang menjadi konteks yang dapat dimuat sesuai permintaan, konsumsi token saat runtime berkurang sebesar 46,9%.
Pendekatan Trae lebih langsung: membatasi jumlah alat MCP dan panjang deskripsi alat tunggal:
- Batas atas jumlah alat: 40
- Batas deskripsi alat tunggal: 8000 karakter
Faktanya, selama pengujian internal awal, banyak tim melaporkan bahwa Apidog MCP memiliki masalah dengan beberapa alat yang tidak dapat dipanggil di Trae. Agen terpaksa membuat trade-off karena konteks model yang terbatas, dan alat eksternal adalah yang pertama "dipotong."
Solusi-solusi ini semua menunjukkan fakta yang sama:
Deskripsi alat tidak dapat secara tak terbatas masuk ke dalam konteks model.
Masalah 3: Sesi Protokol Membuat Rantai Eksekusi Lebih Berat
Server Apidog MCP perlu menangani:
| Status Protokol | Deskripsi |
|---|---|
| MCP inisialisasi | Jabat tangan antara klien dan server |
| Generasi sessionId | Pengidentifikasi unik untuk sesi |
| Penyimpanan sesi Redis | Persistensi status |
| Transportasi sambungkan/putus | Manajemen koneksi |
| Sesi disentuh | Mekanisme keep-alive |
| Hapus sesi | Pembersihan setelah selesai |
| Respons JSON atau konfigurasi SSE | Opsi format keluaran |
Untuk panggilan alat sederhana, biaya ini dapat diterima. Untuk tugas Agen dengan jumlah panggilan yang besar dan eksplorasi yang sering, persyaratan manajemen status ini meningkatkan kompleksitas baik di sisi server maupun klien.
Saat mengimplementasikan Apidog MCP, tim menghabiskan energi yang signifikan untuk memecahkan masalah dan beradaptasi dengan berbagai klien Agen (Cursor, Claude Code, Antigravity, Trae, dll.). Namun, masalah kompatibilitas protokol tetap ada, dan protokol MCP resmi terus diperbaiki dengan versi baru.
Semua pihak sangat menderita.
Masalah 4: Alat Atomik Tidak Dapat Mengekspresikan Semantik Produk Secara Alami
Dalam skenario uji Apidog, ini bukan hanya ekspresi array steps yang sederhana.
Skenario uji melibatkan:
| Komponen | Kompleksitas |
|---|---|
| Impor | Langkah-langkah dari titik akhir atau kasus yang ada |
| Baca-balik | Mendapatkan struktur lengkap setelah impor |
| Kasus internal | Permintaan HTTP yang disematkan dalam langkah-langkah |
| Pra/pasca prosesor | Skrip sebelum/sesudah permintaan |
| Asersi | Aturan validasi respons |
| Ekstraksi variabel | Mengambil nilai dari respons |
| Lingkungan runtime | Pemilihan lingkungan, variabel |
| Verifikasi laporan | Memeriksa hasil tes |
Setelah memecah ini menjadi beberapa alat MCP, Agen masih harus melakukan pekerjaan orkestrasi pengujian itu sendiri.
Semakin atomik alat-alatnya, semakin model perlu memahami semantik internal produk:
- Mengapa impor membutuhkan baca-balik?
- Mengapa kasus internal memiliki penanda pembaruan yang berbeda?
- Mengapa asersi membutuhkan komparator tertentu?
- Mengapa ekstraksi variabel memiliki batasan tipe?
Ini jelas di luar jangkauan kemampuan model.
Hal ini memaksa tim Apidog untuk secara proaktif melakukan penyesuaian rekayasa teknis untuk semantik produk internal. Titik akhir atomik secara pasif menambahkan lapisan konversi, hanya untuk beradaptasi dengan satu pengiriman lapisan alat MCP.
Tantangan rekayasa dan biaya pasca-pemeliharaan tidak diragukan lagi sangat sulit.
Akar Masalah
Akar masalah dari keempat masalah ini adalah hal yang sama:
MCP lebih baik dalam menghubungkan alat, tetapi tugas R&D yang kompleks membutuhkan lebih dari sekadar koneksi alat—mereka membutuhkan proses rekayasa yang dapat dieksekusi.
| Kekuatan MCP | Keterbatasan MCP |
|---|---|
| Koneksi terstandardisasi | Tidak dapat mengekspresikan alur kerja |
| Protokol terpadu | Tidak dapat memandu urutan |
| Eksposur alat | Tidak dapat menegakkan validasi |
| Penemuan dinamis | Tidak dapat memberikan penilaian |
Untuk produk sederhana dengan selusin operasi yang terdefinisi dengan baik, MCP bekerja dengan baik. Agen dapat secara wajar menebak alat yang tepat, memanggilnya, dan mendapatkan hasil.
Untuk produk seperti Apidog—dengan puluhan modul, ratusan operasi, struktur bersarang, alur kerja tersembunyi, dan semantik spesifik produk—MCP saja menciptakan dinding alat acak yang sulit dinavigasi oleh Agen.
Apa yang Kami Pelajari
| Pelajaran | Implikasi |
|---|---|
| Lebih banyak alat ≠ pemberdayaan Agen yang lebih baik | Jumlah alat adalah biaya, bukan keuntungan |
| Deskripsi alat bersaing untuk konteks | 500 token per alat × 100 alat = beban 50.000 token |
| Protokol sesi menambah overhead eksekusi | Setiap panggilan membawa manajemen status protokol |
| Alat atomik membutuhkan pengetahuan produk | Agen harus memahami internal untuk mengorkestrasi |
| Koneksi ≠ eksekusi | MCP menghubungkan; CLI + SKILL mengeksekusi |
Pergeseran Strategi
Kesadaran ini membuat kami mengajukan pertanyaan yang berbeda:
Jika MCP bukan jawaban untuk pemberdayaan agen, lalu apa?
Kami tidak meninggalkan nilai MCP—ini menyediakan koneksi standar, yang penting untuk ekosistem. Tetapi kami membutuhkan sesuatu yang dapat:
- Mengekspresikan alur kerja, bukan hanya alat
- Memandu Agen melalui urutan
- Memvalidasi sebelum menulis
- Menegakkan gerbang kualitas rekayasa
- Menyerap kompleksitas ke dalam sistem
Jawaban yang kami temukan: CLI + SKILL.
Dalam postingan berikutnya, Mengapa Kami Mengembangkan Apidog CLI yang Baru , kami akan menjelajahi pergeseran arsitektur—di mana kompleksitas berpindah dari konteks model ke sistem rekayasa, dan mengapa itu mengubah segalanya untuk pemberdayaan Agen.
Poin-Poin Utama
- MCP menjadi jawaban industri untuk "bagaimana Agen terhubung ke alat"
- Kami membangun 126 alat MCP, berpikir lebih banyak alat = pemberdayaan yang lebih baik
- Tugas nyata mengungkapkan empat masalah struktural: biaya penemuan, invasi konteks, overhead sesi, semantik produk
- Akar masalah: MCP menghubungkan alat, tetapi tugas kompleks membutuhkan proses yang dapat dieksekusi
- Lebih banyak alat adalah biaya, bukan keuntungan, ketika deskripsi alat mengkonsumsi konteks
Unduh Apidog untuk mendesain, membuat mock, menguji, dan mendokumentasikan API dalam satu ruang kerja. Pelajari lebih lanjut tentang Apidog CLI untuk pengujian API baris perintah, otomatisasi CI, dan alur kerja Agen AI.