Satu patch kecil di plane-mcp biar mau ngobrol sama Plane Community Edition

Saya lagi nyoba hubungkan dua work item lewat tool MCP. Perintah jalan, lalu yang muncul cuma satu baris error: 404 Not Found. Nggak ada pesan tambahan, nggak ada petunjuk konfigurasi salah. Kosong.

Dugaan pertama saya: 404 berarti item yang dicari nggak ada. Saya habiskan waktu ngecek ulang ID work item, cari typo, bahkan restart server lokal. Ternyata item-nya ada dan valid.

Bukan salah data, tapi rute yang hilang

Setelah gali lebih dalam, masalahnya bukan di data tapi di rute endpoint. Saya nemu issue #185 di repo plane-mcp-server yang persis menggambarkan situasi ini. SDK resmi memanggil endpoint /dependencies/ buat membuat relasi, dan rute itu 404 di Community Edition self-hosted. Pelapornya bahkan lampirkan output curl yang menunjukkan rute lama /relations/ di instance yang sama balas 201 Created dengan mulus.

Bedanya cuma satu: struktur body. Rute lama pakai kunci issues, bukan work_item_ids seperti rute cloud terbaru. Issue yang sama juga mencatat akar masalahnya: SDK menarget rute cloud yang belum turun ke CE, pola yang sama dengan keluarga issue -lite sebelumnya. Ada satu detail yang bikin ini lebih parah: docstring tool list_work_item_relation_definitions menyuruh memanggil definisi dulu sebelum membuat relasi, padahal endpoint definisi itu sendiri 404 di CE. Alur kerja yang didokumentasikan langsung patah di langkah pertama.

Fallback berbasis bentuk respons

Solusi saya di commit a9769dd (perubahan +140/-32 baris di workitem_relation.py) sederhana prinsipnya: jangan nebak, bedakan 404-nya. Fungsi _endpoint_missing() memeriksa apakah 404 itu berarti "Page not found" (rute memang nggak ada di edisi ini) atau "item not found" (rute ada, datanya kosong). Dua kasus ini butuh perlakuan beda: yang pertama masuk akal di-fallback, yang kedua harus tetap dilaporkan sebagai data nggak ketemu.

Kalau terdeteksi rute absen, panggilan beralih ke _ce_relations_path(), URL dengan bentuk sama seperti yang dirakit SDK, cuma segmen terakhirnya beda. List relasi mengembalikan satu GET tergrouping dengan flag ce_fallback: true plus catatan bahwa entri membawa issue_id, bukan work item utuh. Create mengirim {"relation_type", "issues"}. Definisi relasi yang nggak punya endpoint di CE dijawab dengan daftar built-in statis, dan delete relasi di CE yang cuma bisa lewat UI dijawab tool dengan error yang menjelaskan itu, bukan gagal diam-diam.

Kenapa nggak fork berat

Bisa saja saya fork penuh plane-mcp-server dan hapus semua jalur cloud. Tapi kode upstream di repo saya ini vendored utuh supaya gampang di-upgrade, dan fork berat berarti tiap rilis upstream jadi konflik merge. Deteksi berbasis bentuk respons membiarkan kode upstream tetap utuh; fallback cuma nempel di titik di mana CE beda. Ini juga berlaku di luar relasi: CE tidak mendukung PQL, endpoint Pages, issue-types, dan custom-properties juga absen di self-hosted. Semua deviasi dicatat di CE-COMPAT.md supaya keputusan patch punya jejak tertulis, bukan pengetahuan tribal.

Ritual pemeliharaannya

Konsekuensi pola ini: tiap mengganti plane_mcp/ dengan tag upstream baru, blok fallback harus diterapkan ulang. Prosedurnya sudah saya turunkan jadi langkah mekanis: grep CE-FALLBACK di tree lama, salin blok-bloknya ke tree baru, lalu jalankan smoke test.

Smoke test-nya bukan tes mock. Dia men-drive server MCP asli lewat HTTP: initialize dengan header auth, membuat dua work item buangan lewat tool workitem, memanggil list_definitions, list, sampai create relasi antara keduanya, lalu membersihkannya. Kalau semua langkah itu lolos, fallback benar-benar jalan di edisi yang benar.

Terdengar seperti kerjaan ekstra. Tapi dibanding menunggu rute cloud turun ke CE tanpa kepastian tanggal, jembatan kecil yang terukur ini satu-satunya jalur yang bikin agen AI tetap bisa memakai relasi work item di self-hosted hari ini.