MCP, istirahat, dan tidak ada alasan untuk tidak lagi menemukan dokumen kami

Semuanya berawal dari pertanyaan tentang Slack dari seorang rekan. “Apakah Anda tahu cara kami meningkatkan ukuran pelari CI kami? Saya tidak dapat menemukan dokumennya. »

Saya memiliki ingatan yang sangat jelas: seseorang telah mendokumentasikannya! Ukuran yang tersedia, prosedur perubahan, batasannya. Saya mungkin bahkan telah meninjau dokumen tersebut. Tapi aku tidak bisa mendapatkannya.

Saya mulai dengan tersangka biasa; mono-repo utama. Ada tiga dokumen teknis, namun tidak ada yang mencakup pelari. Saya membuka pencarian GitHub dan mengetik “ukuran pelari”, mendapatkan lusinan hasil yang tersebar di selusin repo – file Terraform, alur kerja, komentar dalam kode, dan di suatu tempat di tengah, tenggelam dalam kebisingan, dokumen saya. Itu ada di repositori infra.

Saya menghabiskan terlalu banyak waktu untuk mencari dokumen yang telah saya ulas sendiri. Sementara itu, rekan saya sedang menunggu.

Masalah sebenarnya: dokumentasi tersebar tapi rapi

Di tim kami, kami melakukan segala sesuatunya dengan benar. Dokumentasi kami disertakan dengan kode, disusun menurut kerangka Diátaxis: tutorial, panduan praktis, referensi teknis, dan penjelasan, masing-masing dalam direktori khusus. Kami menambahkan ADR (Catatan Keputusan Arsitektur) dan PRD (Dokumen Persyaratan Produk), yang juga memiliki versi. Setiap dokumen ditinjau dan digabungkan seperti kode. Ini adalah praktik yang baik.

Namun ketelitian ini mempunyai dampak buruk: dokumentasi diatur dengan baik dalam setiap repo, dan sama sekali tidak terlihat di seluruh organisasi. Tidak ada seorang pun yang memiliki pandangan cross-sectional. Setiap pengembang mengetahui dokumen repositori tempat dia bekerja, dan mengabaikan dokumen orang lain.

Kami membutuhkan jembatan antara agen kami dan dokumentasi kami yang tersebar.

Pengingat singkat: apa itu MCP?

Model Context Protocol adalah standar terbuka yang memungkinkan agen AI memanggil alat eksternal. Kami menulis ke server yang menyatakan: “Saya tahu cara mencari di dokumentasi, saya tahu cara mengambil dokumen lengkap, saya tahu cara membuat daftar repo”. Klien MCP mana pun kemudian dapat menggunakan alat ini.

Nuansa utamanya: agenlah yang memutuskan kapan harus memanggil suatu alat. Ini bukan saluran pipa yang berjalan di latar belakang. Agen berpikir, mencari, membaca hasil, menyempurnakan kuerinya, mengambil dokumen. Sama seperti seorang pengembang yang memahami, membaca, dan mengulangi.

Dalam praktiknya, alurnya seperti ini:

Apa yang kami bangun: server pencarian dokumen

Tiga alat, satu tujuan

Server memaparkan tiga alat kepada agen kami:

Pencarian teks lengkap — Agen mengirimkan kata kunci dan dapat memfilter berdasarkan repo atau jenis dokumen. Di bawah tenda, kami menggunakan GitHub Code Search API — mesin yang sama dengan bilah pencarian GitHub, tetapi dapat diakses secara terprogram. Hasilnya muncul dalam bentuk potongan teks sehingga agen dapat menilai relevansinya sebelum melangkah lebih jauh.

Pengambilan dokumen — Setelah hasil pencarian sesuai, agen dapat mengambil seluruh konten file penurunan harga. Ia mendapat teks biasa, jenis dokumen (disimpulkan dari jalur), repo sumber. Dia memiliki semua konteks untuk dijawab.

Penemuan repositori — Agen dapat membuat daftar semua repositori organisasi dengan inventaris dokumenternya: berapa banyak dokumen, jenis apa (ADR, PRD, spesifikasi, panduan, cara, referensi, penjelasan, dll.). Ini adalah pandangan melintang yang kami lewatkan.

Secara konkret, inilah yang terjadi saat Anda mencari ADR:

Klasifikasi dokumen secara otomatis

Ketika hasil pencarian muncul, server melihat jalur file dan menyimpulkan jenis dokumen. File di /adrs/ adalah ADR. File di /prds/ adalah PRD. README.md adalah readme. Sederhana, deterministik, dan sangat sesuai dengan konvensi penamaan kita.

Klasifikasi ini memungkinkan agen untuk memfilter pencariannya: “cari saya hanya di ADR” atau “tunjukkan spesifikasi teknis repo ini”. Pemfilteran dilakukan pada sisi permintaan GitHub, bukan pada pasca-pemrosesan — cepat dan tidak menggunakan token LLM secara tidak perlu.

Cache: jangan pernah menanyakan hal yang sama dua kali

Mengindeks repo terdiri dari mengambil file dokumentasi yang kami minati dan menyimpannya langsung di folder yang benar di cache lokal. Setiap repo memiliki cache sendiri, diindeks oleh SHA dari komit terakhir di main. Pada setiap panggilan, server memeriksa SHA repo saat ini melalui GitHub API: jika cocok, cache akan disajikan; jika tidak, repo ini sendiri akan diindeks ulang. Segera setelah pengembang memasukkan kode, cache repositori secara otomatis menjadi tidak valid.

Hasilnya: tidak ada panggilan API ketika tidak ada yang berubah, tidak ada konten yang usang. Tanpa TTL, tanpa pekerjaan pembersihan dan tanpa database.

Mengapa MCP, dan bukan yang lain?

Kita sering ditanya mengapa kita tidak menaruh semua ini di toko vektor. Jawaban singkatnya: dokumen kami sudah disusun dan diindeks oleh GitHub. Menambahkan saluran pipa RAG di atasnya akan menjadi infrastruktur yang sia-sia.

Tentu saja, hal ini memerlukan dokumen yang bersih. Itulah intinya: jika terlalu besar untuk ditemukan oleh MCP, berarti terlalu besar untuk tim Anda. RAG akan memberi Anda ilusi sebaliknya dalam beberapa bulan.

Lebih sedikit luas permukaan, lebih banyak kontrol

Pertanyaan pun muncul, mengapa tidak membungkus GitHub CLI saja. Ini akan berhasil, namun agen akan memiliki akses ke semua perintah Github — bahkan dengan token read-only, permukaan eksposur tetap besar. MCP membalikkan pendekatan ini: agen hanya melihat tiga alat yang diberikan padanya. Cakupannya tidak dibatasi oleh izin token, namun oleh kode server. Dan ketika CLI mengembalikan teks untuk diinterpretasikan oleh agen, MCP mengembalikan respons terstruktur untuk digunakan oleh agen.

Agen percontohan. Itu tidak menjalani konteks, ia mencari, membaca, menyempurnakan, persis seperti yang dilakukan pengembang.

Dokumentasi untuk kami? Benar-benar ?

Agen AI bebas konteks melakukan improvisasi. Dibutuhkan keputusan arsitektural yang telah diputuskan oleh ADR, mengabaikan konvensi yang dihormati oleh seluruh tim, atau menemukan kembali solusi ketika ada pola yang terbukti.

Dan masalahnya bukan pada kurangnya dokumentasi — melainkan ada di sana, tersimpan di setiap repo. Masalahnya adalah ruang lingkup. Agen yang mengerjakan repo hanya melihat dokumen dari repo tersebut. Ini mengabaikan spesifikasi proyek lain, pola bersama, keputusan lintas fungsi. Inilah permasalahan rekan saya yang sedang mencari dokumentasi pelari: informasinya ada, tetapi tidak terlihat dari konteks lain.

Server Dokumen MCP mengisi kesenjangan ini. Ini memberi agen pandangan lintas bagian dari keseluruhan basis dokumenter. Semakin baik kami mendokumentasikan, semakin dapat diandalkan agen tersebut. MCP adalah jembatan yang mewujudkan lingkaran kebajikan ini.

Membawa pergi

Mulailah dengan masalahnya. Kami tidak memilih MCP karena baru atau bergaya. Kami memilihnya karena seorang kolega sedang mencari dokter yang tidak dapat ditemukan dengan cukup cepat. Implementasinya dilakukan setelah diperlukan.

Infrastruktur terbaik adalah infrastruktur yang tidak kita miliki. Tidak ada database, tidak ada pipa pengindeksan.

Biarkan agen mengemudi. Kelebihan MCP adalah agen secara bertahap membangun pemahamannya. Ia tidak menerima segumpal konteks — ia mengeksplorasi, seperti yang dilakukan pengembang.

RAG bukanlah respons default. Jika sumber data sudah terstruktur dan diindeks, pembungkus MCP di sekitar API yang ada akan lebih sederhana, lebih andal, dan lebih murah.

Dokumentasi Anda memiliki audiens baru. Agen AI Anda telah menjadi pembaca pertama dokumen Anda. Jadikan mereka dapat diakses, dan seluruh rantai mendapat manfaat.