Unleash

Server MCP Unleash

Server Model Context Protocol (MCP) yang dirancang khusus untuk mengelola fitur flag Unleash. Server ini memungkinkan asisten coding berbasis LLM untuk membuat dan mengelola fitur flag sesuai praktik terbaik Unleash.

Untuk berbagi masukan, bergabunglah dengan Slack komunitas kami atau buka issue di GitHub.

Ringkasan

Server MCP ini menyediakan alat yang terintegrasi dengan Unleash Admin API, memungkinkan asisten coding AI untuk:

• Membuat fitur flag dengan validasi dan pengetikan yang tepat.
• Mendeteksi flag yang sudah ada untuk mencegah duplikasi atau mendorong penggunaan ulang.
• Mengevaluasi perubahan untuk memutuskan kapan fitur flag diperlukan.
• Mengalirkan progres untuk visibilitas selama operasi.
• Menangani kesalahan dengan baik serta memberikan petunjuk yang bermanfaat.
• Mengikuti praktik terbaik dari dokumentasi Unleash.

Alat yang tersedia

Server MCP mengekspos alat-alat berikut:

• create_flag: Membuat fitur flag di Unleash.
• evaluate_change: Memberi skor risiko dan merekomendasikan penggunaan fitur flag.
• detect_flag: Menemukan fitur flag yang sudah ada untuk menghindari duplikasi.
• wrap_change: Memberikan panduan tentang cara membungkus perubahan dalam fitur flag.
• set_flag_rollout: Mengonfigurasi strategi peluncuran untuk fitur flag (tidak mengaktifkan flag).
• get_flag_state: Menampilkan metadata fitur flag dan strategi aktivasi.
• list_flags: Menampilkan semua fitur flag dalam sebuah proyek, dengan paginasi dan urutan opsional.
• list_projects: Menampilkan proyek Unleash yang tersedia untuk token yang dikonfigurasi, dengan paginasi opsional.
• toggle_flag_environment: Mengaktifkan atau menonaktifkan fitur flag di lingkungan tertentu.
• remove_flag_strategy: Menghapus strategi fitur flag dari lingkungan tertentu.
• cleanup_flag: Menghasilkan instruksi untuk menghapus jalur kode yang di-flag dengan aman.

Alur kerja inti

Alur kerja inti untuk asisten AI dirancang sebagai berikut:

1. evaluate_change: Pertama, nilai perubahan kode untuk melihat apakah flag diperlukan.
2. detect_flag: Ini sering dipanggil secara otomatis oleh evaluate_change untuk mencegah pembuatan flag duplikat.
3. create_flag: Jika flag baru diperlukan, alat ini membuatnya di Unleash.
4. wrap_change: Terakhir, alat ini menyediakan kode khusus bahasa untuk mengimplementasikan flag baru.

Lihat informasi lebih lanjut tentang alat alur kerja inti di bagian Referensi alat.

Prasyarat

Sebelum menjalankan server, Anda memerlukan hal-hal berikut:

• Node.js 22 atau lebih tinggi
• Manajer paket pnpm atau npm
• Instance Unleash (hosting atau self-hosted)
• Token akses pribadi dengan izin untuk membuat fitur flag

Memulai

Bagian ini mencakup berbagai cara untuk menginstal dan menjalankan server MCP Unleash. Anda dapat mengikuti pengaturan untuk agen (seperti Claude Code dan Codex), menjalankan MCP sebagai proses mandiri menggunakan npx, atau menggunakan pengaturan pengembangan lokal.

Pengaturan agen

Anda dapat menambahkan server MCP langsung ke Claude Code atau Codex. Konfigurasi agen bersifat spesifik terhadap jalur. Anda harus menjalankan perintah berikut dari direktori root proyek tempat Anda ingin menggunakan MCP.

Untuk Claude Code:

claude mcp add unleash \
    --env UNLEASH_BASE_URL={{your-instance-url}} \
    --env UNLEASH_PAT={{your-personal-access-token}} \
    -- npx -y @unleash/mcp@latest --log-level error

Untuk Codex:

codex mcp add unleash \
    --env UNLEASH_BASE_URL={{your-instance-url}} \
    --env UNLEASH_PAT={{your-personal-access-token}} \
    -- npx -y @unleash/mcp@latest --log-level error

Pengaturan agen jarak jauh (eksperimental)

Alih-alih menjalankan server MCP secara lokal, Anda dapat terhubung langsung ke server MCP jarak jauh bawaan instance Unleash Anda melalui HTTP. Ini menggunakan transport HTTP Streamable — tanpa proses lokal yang diperlukan.

Catatan: MCP jarak jauh adalah fitur eksperimental yang harus diaktifkan di instance Unleash Anda. Hubungi tim Unleash untuk mengaktifkannya.

OAuth

Alur OAuth membuka browser Anda, memungkinkan Anda masuk ke Unleash, dan secara otomatis menyediakan PAT berumur pendek. Tidak perlu pengelolaan token manual.

Untuk Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

Untuk Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

Pada penggunaan pertama, klien akan otomatis membuka browser Anda untuk login. Setelah autentikasi dengan Unleash, PAT dibuat dan digunakan untuk semua permintaan berikutnya.

PAT kedaluwarsa setelah 24 jam secara default.

Token Akses Pribadi (PAT)

Gunakan metode ini jika Anda sudah memiliki PAT atau memerlukan akses headless/non-interaktif (pipeline CI, lingkungan pengembang bersama, klien yang tidak mendukung OAuth).

Untuk membuat PAT: masuk ke instance Unleash Anda, buka Profil > Token Akses Pribadi, dan buat token baru.

Untuk Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

Untuk Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

Bendera --header mengirim PAT secara langsung, melewati alur OAuth sepenuhnya.

Memulai cepat dengan npx

Anda dapat menjalankan server MCP sebagai proses mandiri tanpa mengkloning repositori menggunakan npx. Berikan konfigurasi melalui variabel lingkungan atau file .env lokal di direktori tempat Anda menjalankan perintah:

UNLEASH_BASE_URL={{your-instance-url}} \
UNLEASH_PAT={{your-personal-access-token}} \
UNLEASH_DEFAULT_PROJECT={{default_project_id}} \
npx @unleash/mcp@latest --log-level debug

CLI mendukung bendera yang sama dengan build lokal (misalnya, --dry-run, --log-level).

Pengaturan pengembangan lokal

Ikuti langkah-langkah berikut untuk menyiapkan proyek untuk pengembangan lokal.

1. Instal dependensi

Kloning repositori dan instal dependensi menggunakan pnpm. Corepack menjaga semua orang pada versi pnpm yang sama:

git clone https://github.com/Unleash/unleash-mcp.git
cd unleash-mcp

# Enable Corepack once per machine, then prepare the pnpm this repo expects
corepack enable
corepack prepare pnpm@11.0.8 --activate

pnpm install

2. Jalankan dalam mode dev langsung dari Claude atau Codex

Hindari output npm run dan banner tsx watch karena stdout tambahan apa pun akan merusak jabat tangan MCP. Dua opsi yang tenang:

A) Gunakan JS yang dikompilasi (paling andal)

npm run build
# or keep it hot in another terminal: npm run build:watch

claude mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node "$(pwd)/dist/index.js"

codex mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node "$(pwd)/dist/index.js"

B) Gunakan TypeScript secara langsung (tanpa build)

claude mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node --no-warnings --import tsx "$(pwd)/src/index.ts"

codex mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node --no-warnings --import tsx "$(pwd)/src/index.ts"

Catatan:

• node --import tsx tenang (tanpa output siklus hidup npm) dan menjalankan TS secara langsung; gunakan ini saat Anda ingin menghindari build.
• node dist/index.js adalah pilihan paling aman; pasangkan dengan npm run build:watch untuk membangun ulang saat ada perubahan sementara perintah agen tetap stabil.
• Log tetap di root repositori (app.log, mcp-stdio.log), keduanya diabaikan oleh git.

Kontrol logging

• LOG_LEVEL (disarankan): mengontrol verbositas logging aplikasi (debug, info, warn, error). Default ke error saat tidak diatur.
• Bendera CLI --log-level: penimpaan opsional untuk LOG_LEVEL saat Anda menginginkan perubahan satu kali.
• APP_LOG_FILE (opsional): jika diatur, log aplikasi ditulis ke file ini (bukan stdout). Jika tidak diatur, log masuk ke stderr.
• MCP_STDIO_LOG_FILE (opsional): jika diatur, stdin/stdout/stderr MCP di-tee ke file tunggal ini dengan prefiks saluran. Pesan protokol tetap mengalir melalui stdout secara normal.

Atribusi klien

Saat klien MCP mengirim clientInfo selama inisialisasi (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro, dan klien lain yang sesuai), server memperkaya header User-Agent pada panggilan keluar Unleash Admin API:

User-Agent: unleash-mcp/<version> (MCP Server; client=claude-code/1.2.3)

Ini membuat log peristiwa Unleash menjawab "alat AI mana yang membuat atau mengalihkan flag ini" tanpa perubahan sisi server. Nilai atribusi disanitasi sehingga tidak dapat merusak header User-Agent.

Setel UNLEASH_MCP_CLIENT_ATTRIBUTION=off untuk menonaktifkan pengayaan dan kembali ke unleash-mcp/<version> (MCP Server). Default: diaktifkan.

Referensi alat

Bagian ini menjelaskan setiap alat inti secara rinci, termasuk tujuan, parameter, dan keluarannya.

Buat flag

Alat create_flag membuat fitur flag baru di Unleash dengan validasi komprehensif dan pelacakan progres.

Kapan digunakan

Gunakan alat ini ketika Anda telah menentukan bahwa fitur flag diperlukan (misalnya, setelah menjalankan evaluate_change) dan Anda siap membuatnya dengan tipe dan metadata yang benar.

Parameter

Alat menerima parameter berikut:

• name (wajib): Nama fitur flag unik dalam proyek.
• type (wajib): Tipe fitur flag yang menunjukkan siklus hidup dan tujuan.
  • release: Peluncuran fitur bertahap ke pengguna.
  • experiment: Pengujian A/B dan eksperimen.
  • operational: Perilaku sistem dan sakelar operasional.
  • kill-switch: Penghentian darurat atau pemutus sirkuit.
  • permission: Mengontrol akses fitur berdasarkan peran pengguna atau hak akses.
• description (wajib): Penjelasan jelas tentang apa yang dikendalikan flag dan mengapa flag itu ada.
• projectId (opsional): Proyek target (default ke UNLEASH_DEFAULT_PROJECT).
• impressionData (opsional): Aktifkan pelacakan analitik (default false).

Contoh penggunaan

Prompt agen

Use create_flag with:
- name: "new-checkout-flow"
- type: "release"
- description: "Gradual rollout of the redesigned checkout experience"
- projectId: "ecommerce"

Payload alat

{
  "name": "new-checkout-flow",
  "type": "release",
  "description": "Gradual rollout of the redesigned checkout experience with improved conversion tracking",
  "projectId": "ecommerce",
  "impressionData": true
}

Keluaran alat

Saat berhasil, alat mengembalikan objek JSON yang berisi URL fitur flag baru di UI Admin Unleash, tautan sumber daya MCP untuk akses terprogram, stempel waktu pembuatan, dan detail konfigurasi.

Evaluasi perubahan

Alat evaluate_change mengevaluasi apakah perubahan kode harus berada di belakang fitur flag. Alat ini memeriksa struktur, konteks, dan potensi risiko perubahan serta mengembalikan rekomendasi dengan penjelasan dan langkah selanjutnya.

Kapan digunakan

Gunakan evaluate_change di awal fitur atau modifikasi ketika Anda ingin memahami apakah pekerjaan tersebut memerlukan fitur flag. Alat ini juga membantu ketika Anda tidak yakin tipe flag mana yang digunakan atau menginginkan panduan tentang perencanaan peluncuran.

Cara kerjanya

Alat mengembalikan panduan terperinci berformat markdown untuk asisten LLM berdasarkan praktik terbaik Unleash.

Panduan mencakup:

• Deteksi flag induk: Memeriksa apakah kode sudah dilindungi oleh flag yang ada.
• Penilaian risiko: Menganalisis pola kode untuk mengidentifikasi operasi berisiko.
• Evaluasi tipe kode: Mengklasifikasikan perubahan (misalnya, pengujian, konfigurasi, fitur, atau perbaikan bug).
• Rekomendasi: Menyarankan apakah akan membuat flag, menggunakan flag yang ada, atau melewati flag.
• Tindakan selanjutnya: Memberikan instruksi spesifik tentang apa yang harus dilakukan selanjutnya.

Saat evaluate_change menentukan bahwa flag diperlukan, alat ini memberikan instruksi eksplisit untuk:

1. Memanggil alat create_flag untuk membuat fitur flag.
2. Memanggil alat wrap_change untuk mendapatkan panduan pembungkusan kode khusus bahasa.
3. Mengimplementasikan kode yang dibungkus mengikuti pola yang terdeteksi.

Proses evaluasi

Alat mengikuti proses evaluasi yang jelas:

Step 1: Gather code changes (git diff, read files)
        ↓
Step 2: Check for parent flags (avoiding nesting)
        ↓
Step 3: Assess code type (test? config? feature?)
        ↓
Step 4: Evaluate risk (auth? payments? API changes?)
        ↓
Step 5: Calculate risk score
        ↓
Step 6: Make recommendation
        ↓
Step 7: Take action (create flag or proceed without)

Penilaian risiko

Alat menggunakan pola yang tidak bergantung bahasa untuk memberi skor risiko:

• Risiko kritis (Skor +5): Misalnya, autentikasi, pembayaran, keamanan, dan operasi basis data.
• Risiko tinggi (Skor +3): Misalnya, perubahan API, layanan eksternal, atau kelas baru.
• Risiko sedang (Skor +2): Misalnya, operasi asinkron atau manajemen status.
• Risiko rendah (Skor +1): Misalnya, perbaikan bug, refaktor, atau perubahan kecil.

Skor terakumulasi di seluruh kategori yang cocok. Total dipetakan ke tingkat risiko:

• Kritis: Skor ≥ 5
• Tinggi: Skor ≥ 3
• Sedang: Skor ≥ 2
• Rendah: Skor < 2

Keluaran mencakup skor confidence (0-1) yang mewakili kepastian penilaian diri LLM, yang meningkat dengan lebih banyak konteks yang diberikan.

Kategori dikecualikan mencakup file yang tidak memerlukan fitur flag apa pun kontennya: file pengujian (*.test.ts, *_test.go, dll.), file konfigurasi (*.config.js, .env, *.yaml), dan file dokumentasi (*.md, docs/**). Perubahan yang terbatas pada file yang dikecualikan tidak akan memicu rekomendasi flag.

Definisi pola lengkap, termasuk kata kunci per kategori, glob file, pola kode, dan alasan, ada di src/evaluation/riskPatterns.ts.

Deteksi flag induk

Alat mencari pola umum di berbagai bahasa, seperti:

• Kondisional: if (isEnabled('flag')), if client.is_enabled('flag'):
• Penugasan: const enabled = useFlag('flag')
• Hook: const enabled = useFlag('flag') → {enabled && <Component />}
• Penjaga: if (!isEnabled('flag')) return;
• Pembungkus: withFeatureFlag('flag', () => {...})

Parameter

Semua parameter bersifat opsional, tetapi semakin banyak konteks yang diberikan, semakin baik rekomendasinya:

• repository (string): Nama repositori atau jalur.
• branch (string): Nama cabang saat ini.
• files (array): Daftar file yang sedang diubah.
• description (string): Deskripsi perubahan.
• riskLevel (enum): low, medium, high, atau critical, sesuai penilaian pengguna.
• codeContext (string): Kode di sekitarnya untuk deteksi flag induk.

Contoh penggunaan

Prompt agen

Penggunaan sederhana di mana Anda membiarkan agen mengumpulkan konteks:

Use evaluate_change to help me determine if I need a feature flag

Instruksi eksplisit:

Use evaluate_change with:
- description: "Add Stripe payment processing"
- riskLevel: "high"

Payload alat

{
  "repository": "my-app",
  "branch": "feature/stripe-integration",
  "files": ["src/payments/stripe.ts"],
  "description": "Add Stripe payment processing",
  "riskLevel": "high",
  "codeContext": "surrounding code for parent flag detection"
}

Output alat

Mengembalikan objek JSON dengan hasil evaluasi, termasuk boolean needsFlag, recommendation (misalnya, "create_new"), nama flag yang disarankan, tingkat risiko, dan explanation yang terperinci.

{
  "needsFlag": true,
  "reason": "new_feature",
  "recommendation": "create_new",
  "suggestedFlag": "stripe-payment-integration",
  "riskLevel": "critical",
  "riskScore": 5,
  "explanation": "This change integrates Stripe payments, which is critical risk...",
  "confidence": 0.9
}

Deteksi flag

Alat detect_flag menemukan fitur flag yang sudah ada di codebase sehingga Anda dapat menggunakannya kembali alih-alih membuat duplikat. Alat ini terintegrasi secara otomatis ke dalam alur kerja evaluate_change tetapi juga dapat digunakan secara manual.

Kapan digunakan

Gunakan alat ini sebelum membuat fitur flag baru atau selama evaluasi kode untuk memeriksa flag yang sudah ada yang mungkin sudah mencakup kasus penggunaan Anda. Ini membantu mencegah duplikasi flag.

Cara kerjanya

Alat ini mengembalikan instruksi pencarian yang komprehensif dan menggunakan beberapa strategi deteksi:

• Deteksi berbasis file: Cari di file yang sedang Anda ubah untuk flag yang sudah ada.
• Analisis riwayat Git: Cari flag yang baru ditambahkan dalam riwayat commit.
• Pencocokan nama semantik: Cocokkan deskripsi dengan nama flag yang sudah ada.
• Analisis konteks kode: Periksa kode di sekitar perubahan.

Alat ini kemudian mengikuti proses penilaian:

Step 1: Execute file-based search (grep for flag patterns in target files)
        ↓
Step 2: Search git history for recent flag additions
        ↓
Step 3: Perform semantic matching (description → flag names)
        ↓
Step 4: Analyze code context (if provided)
        ↓
Step 5: Combine scores from all methods
        ↓
Step 6: Return best candidate with confidence score

Tingkat keyakinan

Alat ini mengembalikan kandidat dengan skor keyakinan:

• ≥0.7 tinggi: Kecocokan kuat; penggunaan ulang disarankan.
• 0.4-0.7 sedang: Kemungkinan cocok; tinjau secara manual.
• <0.4 rendah: Kecocokan lemah; kemungkinan buat flag baru.

Parameter

• description (wajib): Deskripsi perubahan atau fitur. Misalnya, "payment processing with Stripe", "new checkout flow".
• files (opsional): File yang sedang dimodifikasi. Misalnya, ["src/payments/stripe.ts", "src/checkout/flow.ts"].
• codeContext (opsional): Kode di dekatnya untuk dipindai mencari flag.

Contoh penggunaan

Prompt agen

Periksa flag yang sudah ada sebelum membuat flag:

Use detect_flag with description "payment processing with Stripe"

Terintegrasi secara otomatis dalam evaluasi:

Use evaluate_change - automatically searches for existing flags

Payload alat

{
  "description": "payment processing with Stripe",
  "files": ["src/payments/stripe.ts"]
}

Output alat

Mengembalikan objek JSON yang menunjukkan apakah flag ditemukan. Jika flagFound bernilai true, objek tersebut menyertakan objek candidate dengan nama flag, lokasi, skor keyakinan, dan alasan kecocokan.

Kecocokan ditemukan:

{
  "flagFound": true,
  "candidate": {
    "name": "stripe-payment-integration",
    "location": "src/payments/stripe.ts:42",
    "context": "if (client.isEnabled('stripe-payment-integration')) {",
    "confidence": 0.85,
    "reasoning": "Found in same file you're modifying, added 2 days ago",
    "detectionMethod": "file-based"
  }
}

Tidak ada kecocokan ditemukan:

{
  "flagFound": false,
  "candidate": null
}

Bungkus perubahan

Alat wrap_change menghasilkan cuplikan kode dan panduan khusus bahasa untuk membungkus kode dengan fitur flag. Ini membantu LLM dan pengembang mengikuti pola yang ada di codebase dan menggunakan flag dengan benar.

Kapan digunakan

Gunakan alat ini setelah Anda membuat fitur flag (dengan create_flag) dan perlu mengimplementasikannya dalam kode Anda. Ini sangat berguna ketika Anda ingin memastikan bahwa Anda mengikuti pola codebase yang ada atau memerlukan contoh khusus kerangka kerja (misalnya, React, Django).

Cara kerjanya

Alat ini adalah langkah terakhir dalam alur kerja evaluate_change → create_flag → wrap_change.

Alat ini memberikan panduan berikut dalam responsnya:

1. Instruksi pencarian: Panduan langkah demi langkah untuk menemukan pola flag yang ada di codebase Anda menggunakan grep.
2. Deteksi pola: Mengidentifikasi pola umum (misalnya, impor, nama variabel klien, nama metode, atau gaya pembungkusan).
3. Template default: Cuplikan kode cadangan jika tidak ada pola yang ditemukan.
4. Contoh khusus kerangka kerja: Pola khusus untuk React, Express, Django, dan lainnya.
5. Beberapa pola: Blok if, klausa penjaga, hook, dekorator, middleware, dan lainnya.

Bahasa dan kerangka kerja yang didukung:

• TypeScript/JavaScript: Node.js, React Hooks, Express middleware.
• Python: FastAPI, Django, Flask decorators.
• Go: Blok if standar, HTTP middleware.
• Ruby: Rails controllers.
• PHP: Laravel controllers.
• C#: .NET/ASP.NET controllers.
• Java: Spring Boot.
• Rust: Actix/Rocket handlers.

Parameter

• flagName (wajib): Nama fitur flag untuk membungkus kode. Misalnya: "new-checkout-flow", atau "stripe-integration".
• language (opsional): Bahasa pemrograman (terdeteksi otomatis dari fileName jika tidak diberikan). Didukung: typescript, javascript, python, go, ruby, php, csharp, java, rust
• fileName (opsional): Nama file yang sedang dimodifikasi (membantu mendeteksi bahasa). Misalnya: "checkout.ts", "payment.py", atau "handler.go".
• codeContext (opsional): Kode di sekitarnya untuk membantu mendeteksi pola yang ada.
• frameworkHint (opsional): Kerangka kerja untuk template khusus. Misalnya, "React", "Express", "Django", "Rails", atau "Spring Boot".

Contoh penggunaan

Prompt agen

Use wrap_change with:
- flagName: "new-checkout-flow"
- fileName: "src/components/checkout.ts"
- frameworkHint: "React"

Payload alat

{
  "flagName": "new-checkout-flow",
  "fileName": "checkout.ts",
  "frameworkHint": "React"
}

Output alat

Mengembalikan string berformat markdown yang komprehensif yang memandu pengguna tentang cara membungkus kode mereka. Ini mencakup panduan memulai cepat, instruksi pencarian, instruksi pembungkusan dengan placeholder, semua template yang tersedia untuk bahasa tersebut, dan tautan ke dokumentasi SDK.

# Feature Flag Wrapping Guide: "new-checkout-flow"

**Language:** TypeScript
**Framework:** React

## Quick Start
[Recommended pattern with import and usage]

## How to Search for Existing Flag Patterns
[Step-by-step Grep instructions]

## How to Wrap Code with Feature Flag
[Wrapping instructions with examples]

## All Available Templates
[If-block, guard clause, hooks, ternary, etc.]

Atur peluncuran flag

Alat set_flag_rollout mengonfigurasi strategi flexibleRollout pada lingkungan fitur flag. Ini mengatur persentase peluncuran, stickiness, dan varian tingkat strategi opsional. Ini tidak mengaktifkan flag; gunakan toggle_flag_environment untuk mengaktifkannya.

Kapan digunakan

Gunakan alat ini setelah membuat flag dengan create_flag untuk mengonfigurasi bagaimana lalu lintas didistribusikan sebelum mengaktifkannya. Juga gunakan untuk memperbarui persentase peluncuran yang ada atau menambahkan varian.

Parameter

• featureName (wajib): Nama fitur flag.
• environment (wajib): Lingkungan target (misalnya, "production", "development").
• rolloutPercentage (wajib): Persentase lalu lintas yang menerima fitur (0-100).
• projectId (opsional): ID proyek (default ke UNLEASH_DEFAULT_PROJECT).
• groupId (opsional): Kunci bucketing stickiness (default ke nama fitur).
• stickiness (opsional): Bidang stickiness (default ke "default").
• title (opsional): Judul deskriptif untuk strategi.
• disabled (opsional): Buat strategi dalam keadaan dinonaktifkan (default ke false).
• variants (opsional): Daftar varian tingkat strategi, masing-masing dengan name, weight (0-1000), weightType opsional ("variable" atau "fix"), stickiness, dan payload ({type, value}).

Contoh penggunaan

Prompt agen

Use set_flag_rollout with:
- featureName: "new-checkout-flow"
- environment: "production"
- rolloutPercentage: 25

Payload alat

{
  "featureName": "new-checkout-flow",
  "environment": "production",
  "rolloutPercentage": 25,
  "projectId": "ecommerce",
  "stickiness": "userId"
}

Output alat

Mengembalikan konfirmasi dengan persentase yang dikonfigurasi, tautan ke flag di UI Admin Unleash, URL strategi Admin API, dan tautan sumber daya MCP untuk flag tersebut.

Dapatkan status flag

Alat get_flag_state mengambil metadata fitur flag saat ini dan strategi lingkungan dari Unleash Admin API. Ini mengembalikan jenis flag, status aktif/diarsipkan, pengaturan data impresi, dan ringkasan per lingkungan dari strategi dan varian aktif.

Kapan digunakan

Gunakan alat ini untuk memeriksa flag sebelum memodifikasinya, untuk memeriksa berapa banyak strategi yang aktif di seluruh lingkungan, atau untuk menemukan ID strategi sebelum memanggil remove_flag_strategy.

Parameter

• featureName (wajib): Nama fitur flag.
• projectId (opsional): ID proyek (default ke UNLEASH_DEFAULT_PROJECT).
• environment (opsional): Filter hasil ke satu lingkungan (tidak peka huruf besar/kecil).

Contoh penggunaan

Prompt agen

Use get_flag_state with:
- featureName: "new-checkout-flow"
- environment: "production"

Payload alat

{
  "featureName": "new-checkout-flow",
  "projectId": "ecommerce",
  "environment": "production"
}

Output alat

Mengembalikan ringkasan teks flag (jenis, aktif/diarsipkan/data impresi, proyek, ringkasan lingkungan dengan jumlah strategi) beserta tautan UI dan API. Output terstruktur mencakup objek fitur lengkap dengan semua lingkungan dan detail strategi.

Daftar flag

Alat list_flags menghitung fitur flag dalam sebuah proyek dan mengembalikan inventaris terstruktur dengan paginasi dan urutan pengurutan. Flag aktif dan diarsipkan dikembalikan secara terpisah: panggil sekali dengan archived: false (default) dan sekali dengan archived: true untuk menyusun inventaris lengkap untuk alur kerja audit.

Kapan digunakan

Gunakan alat ini ketika agen perlu menemukan flag mana yang sudah ada, misalnya untuk mengaudit proyek, menemukan kandidat untuk pembersihan, atau membangun konteks sebelum membuat atau membungkus flag. Ini adalah padanan yang dapat dipanggil agen dari sumber daya unleash://projects/{projectId}/feature-flags (lihat sumber daya MCP).

Parameter

• projectId (opsional): Proyek untuk membuat daftar flag (default ke UNLEASH_DEFAULT_PROJECT; diselesaikan otomatis ketika hanya ada satu proyek).
• archived (opsional): true untuk membuat daftar flag yang diarsipkan alih-alih yang aktif. Default ke false. Flag aktif dan diarsipkan tidak dapat dikembalikan dalam respons yang sama.
• limit (opsional): Jumlah maksimum flag per halaman (default: ukuran halaman server, biasanya 50).
• order (opsional): Urutan pengurutan berdasarkan nama flag, asc atau desc (default: asc).
• offset (opsional): Jumlah flag yang dilewati untuk paginasi (default: 0).

Contoh penggunaan

Prompt agen

Use list_flags with:
- projectId: "ecommerce"
- archived: false

Payload alat

{
  "projectId": "ecommerce",
  "archived": false,
  "limit": 50,
  "order": "asc"
}

Output alat

Mengembalikan ringkasan teks plus konten terstruktur dengan projectId, archived, order, limit, offset, nextOffset, totalFlags, dan array flags (masing-masing dengan nama, jenis, proyek, status diarsipkan, dan tautan). Gunakan nextOffset untuk menelusuri proyek besar.

Daftar proyek

Alat list_projects menghitung proyek Unleash yang tersedia untuk token yang dikonfigurasi, dengan paginasi dan urutan pengurutan.

Kapan digunakan

Gunakan alat ini ketika proyek target tidak diketahui, atau ketika agen perlu memilih proyek sebelum membuat daftar atau membuat flag. Ini adalah padanan yang dapat dipanggil agen dari sumber daya unleash://projects (lihat sumber daya MCP).

Parameter

• limit (opsional): Jumlah maksimum proyek per halaman (default: ukuran halaman server, biasanya 20).
• order (opsional): Urutan pengurutan berdasarkan waktu pembuatan proyek, asc atau desc (default: desc, terbaru terlebih dahulu).
• offset (opsional): Jumlah proyek yang dilewati untuk paginasi (default: 0).

Contoh penggunaan

Prompt agen

Use list_projects to see which projects are available.

Payload alat

{
  "limit": 20,
  "order": "desc"
}

Output alat

Mengembalikan ringkasan teks plus konten terstruktur dengan order, limit, offset, nextOffset, totalProjects, dan array projects (masing-masing dengan id, nama, deskripsi, mode, waktu pembuatan, dan URL).

Alihkan lingkungan flag

Alat toggle_flag_environment mengaktifkan atau menonaktifkan fitur flag di lingkungan tertentu. Untuk peluncuran bertahap, konfigurasikan strategi dengan set_flag_rollout sebelum mengaktifkan.

Kapan digunakan

Gunakan alat ini untuk mengaktifkan flag setelah mengonfigurasi strategi peluncuran, atau untuk menonaktifkan flag selama insiden atau setelah menyelesaikan peluncuran.

Parameter

• featureName (wajib): Nama fitur flag.
• environment (wajib): Lingkungan yang akan diubah (contohnya, "production").
• enabled (wajib): true untuk mengaktifkan, false untuk menonaktifkan.
• projectId (opsional): ID Proyek (default ke UNLEASH_DEFAULT_PROJECT).

Contoh penggunaan

Prompt Agen

Use toggle_flag_environment with:
- featureName: "new-checkout-flow"
- environment: "production"
- enabled: true

Payload Alat

{
  "featureName": "new-checkout-flow",
  "environment": "production",
  "enabled": true,
  "projectId": "ecommerce"
}

Output Alat

Mengembalikan konfirmasi status baru, ringkasan lingkungan (aktif/nonaktif, jumlah strategi), dan tautan ke flag di UI Admin Unleash dan Admin API.

Hapus strategi flag

Alat remove_flag_strategy menghapus konfigurasi strategi dari lingkungan fitur flag. Gunakan get_flag_state terlebih dahulu untuk menemukan ID strategi.

Kapan digunakan

Gunakan alat ini untuk membersihkan strategi yang sudah usang, atau untuk mengganti strategi yang ada dengan menghapus yang lama dan mengonfigurasi yang baru dengan set_flag_rollout.

Parameter

• featureName (wajib): Nama fitur flag.
• environment (wajib): Lingkungan tempat strategi akan dihapus.
• strategyId (wajib): ID strategi yang akan dihapus (temukan melalui get_flag_state).
• projectId (opsional): ID Proyek (default ke UNLEASH_DEFAULT_PROJECT).

Contoh penggunaan

Prompt Agen

Use get_flag_state to find strategy IDs for "new-checkout-flow" in production,
then use remove_flag_strategy to delete the old strategy.

Payload Alat

{
  "featureName": "new-checkout-flow",
  "environment": "production",
  "strategyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "projectId": "ecommerce"
}

Output Alat

Mengembalikan konfirmasi penghapusan, jumlah strategi yang tersisa di lingkungan, dan tautan ke flag di UI Admin Unleash dan Admin API.

Membersihkan flag

Alat cleanup_flag menghasilkan instruksi langkah demi langkah untuk menghapus kode fitur flag dengan aman dari codebase sambil mempertahankan jalur kode yang diinginkan.

Kapan digunakan

Gunakan alat ini ketika fitur flag telah menyelesaikan siklus hidupnya:

• Setelah peluncuran mencapai 100% dan flag tidak lagi diperlukan.
• Saat menghentikan fitur eksperimental (pertahankan jalur nonaktif).
• Saat menghapus kill switch yang tidak lagi diperlukan.
• Selama pembersihan utang teknis dari flag lama.

Cara kerjanya

Alat ini mengembalikan instruksi pembersihan yang komprehensif yang memandu LLM melalui:

1. Menemukan semua kemunculan flag menggunakan pola grep.
2. Mengidentifikasi pola penggunaan (blok if-else, ekspresi ternary, guard clause, hook, dekorator, middleware).
3. Menghapus pemeriksaan flag sambil mempertahankan jalur kode yang benar.
4. Membersihkan impor yang tidak digunakan dengan panduan khusus bahasa.
5. Memverifikasi perubahan dengan pencarian pasca-pembersihan dan langkah pengujian.

Jika preservePath tidak diberikan, alat mengembalikan instruksi untuk menanyakan pengguna jalur mana yang akan dipertahankan sebelum melanjutkan.

Parameter

• flagName (wajib): Nama fitur flag yang akan dihapus (contohnya, "new-checkout-flow").
• preservePath (opsional): "enabled" untuk mempertahankan jalur kode flag aktif (umum untuk peluncuran yang selesai), atau "disabled" untuk mempertahankan jalur flag nonaktif (untuk eksperimen yang dihapus). Jika dihilangkan, alat akan meminta Anda untuk bertanya kepada pengguna.
• files (opsional): File spesifik yang akan dibersihkan. Jika dihilangkan, mencari seluruh codebase.
• language (opsional): Bahasa pemrograman untuk panduan pembersihan impor khusus (contohnya, "typescript", "python"). Terdeteksi otomatis dari files jika tidak diberikan.

Contoh penggunaan

Prompt Agen

Use cleanup_flag with:
- flagName: "new-checkout-flow"
- preservePath: "enabled"

Payload Alat

{
  "flagName": "new-checkout-flow",
  "preservePath": "enabled",
  "files": ["src/components/checkout.tsx", "src/api/checkout.ts"],
  "language": "typescript"
}

Output Alat

Mengembalikan panduan markdown yang mencakup cakupan pembersihan dan jalur yang dipertahankan, perintah grep untuk menemukan semua kemunculan, instruksi penghapusan per pola, pembersihan impor khusus bahasa, dan langkah verifikasi pasca-pembersihan (pencarian ulang, menjalankan tes, tinjauan manual).

Sumber daya MCP

Server mendaftarkan sumber daya MCP untuk membaca data proyek dan fitur flag. Semua sumber daya mengembalikan JSON dan di-cache selama 60 detik.

Templat URI	Deskripsi
unleash://projects{?limit,order,offset}	Daftar proyek. Ukuran halaman default: 20, diurutkan berdasarkan waktu pembuatan (terbaru pertama).
unleash://projects/{projectId}/feature-flags{?limit,order,offset}	Daftar flag dalam proyek. Ukuran halaman default: 50, diurutkan secara alfabetis.
unleash://projects/{projectId}/feature-flags/{flagName}	Metadata fitur flag tunggal.

Dua templat pertama menerima parameter kueri opsional: limit (ukuran halaman), order (asc atau desc), dan offset (awal paginasi). Respons menyertakan bidang fetchedAt, cached, totalProjects atau totalFlags, dan nextOffset.

Sumber daya vs. alat: Sumber daya MCP dikendalikan aplikasi, sehingga banyak klien hanya menampilkannya melalui UI yang digerakkan pengguna (misalnya sebutan #) dan tidak mengizinkan agen memanggil resources/read sendiri. Ketika agen perlu menghitung proyek atau flag secara terprogram, gunakan alat list_projects dan list_flags, yang mengembalikan data yang sama melalui antarmuka alat. Analisis inventaris detect_flag dirutekan melalui jalur yang sama.

Contoh pembacaan sumber daya

Read unleash://projects/ecommerce/feature-flags?limit=10&order=asc

Mengembalikan 10 fitur flag pertama dalam proyek ecommerce, diurutkan secara alfabetis, dengan metadata paginasi.

Arsitektur

Server mengikuti desain yang fokus dan digerakkan oleh tujuan.

Struktur

src/
├── index.ts                     # Stdio CLI entry point
├── server.ts                    # Transport-agnostic server factory
├── remote.ts                    # HTTP request handler for embedded mode
├── config.ts                    # Configuration loading and validation
├── context.ts                   # Shared runtime context
├── version.ts                   # Version constant
├── unleash/
│   └── client.ts                # Unleash Admin API client
├── tools/
│   ├── types.ts                 # Shared ToolDefinition type
│   ├── createFlag.ts            # create_flag tool
│   ├── evaluateChange.ts        # evaluate_change tool
│   ├── detectFlag.ts            # detect_flag tool
│   ├── wrapChange.ts            # wrap_change tool
│   ├── cleanupFlag.ts           # cleanup_flag tool
│   ├── setFlagRollout.ts        # set_flag_rollout tool
│   ├── getFlagState.ts          # get_flag_state tool
│   ├── toggleFlagEnvironment.ts # toggle_flag_environment tool
│   └── removeFlagStrategy.ts    # remove_flag_strategy tool
├── resources/
│   └── unleashResources.ts      # MCP resource handlers (projects, flags)
├── prompts/
│   └── promptBuilder.ts         # Markdown formatting utilities
├── evaluation/
│   ├── riskPatterns.ts          # Risk assessment patterns
│   └── flagDetectionPatterns.ts # Parent flag detection patterns
├── detection/
│   ├── flagDiscovery.ts         # Flag discovery strategies
│   └── flagScoring.ts           # Scoring and ranking logic
├── knowledge/
│   └── unleashBestPractices.ts  # Best practices knowledge base
├── templates/
│   ├── languages.ts             # Language detection and metadata
│   ├── wrapperTemplates.ts      # Code wrapping templates
│   ├── searchGuidance.ts        # Pattern search instructions
│   └── cleanupGuidance.ts       # Flag cleanup instructions
└── utils/
    ├── errors.ts                # Error normalization
    ├── streaming.ts             # Progress notifications
    └── stdioLogging.ts          # Stdio protocol traffic logging

Prinsip desain

• Permukaan tipis: Hanya endpoint yang diperlukan untuk kemampuan inti.
• Digerakkan oleh tujuan: Setiap modul melayani tujuan spesifik dan terdefinisi dengan baik.
• Validasi eksplisit: Skema Zod memvalidasi semua input sebelum panggilan API.
• Normalisasi kesalahan: Semua kesalahan dikonversi ke format {code, message, hint}.
• Streaming progres: Operasi berjalan lama memberikan visibilitas.
• Integrasi praktik terbaik: Panduan dari dokumentasi Unleash tertanam dalam deskripsi alat.

Konfigurasi

Bagian ini menyediakan referensi cepat untuk semua opsi konfigurasi.

Variabel lingkungan:

• UNLEASH_BASE_URL: URL instance Unleash Anda (wajib). Baik https://your-instance.getunleash.io dan https://your-instance.getunleash.io/api diterima — server menormalkan /api di akhir jika ada, sehingga Anda dapat menempelkan nilai yang sama yang diharapkan sebagian besar SDK Unleash.
• UNLEASH_PAT: Token akses pribadi (wajib).
• UNLEASH_DEFAULT_PROJECT: ID proyek default yang harus digunakan MCP (opsional).

Flag CLI:

• --dry-run: Simulasikan operasi tanpa melakukan panggilan API yang sebenarnya.
• --log-level: Atur verbositas logging (debug, info, warn, error).

Praktik terbaik

Server ini mendorong praktik terbaik Unleash dari dokumentasi resmi:

Siklus hidup flag

1. Buat dengan tujuan: Pilih jenis flag yang tepat untuk menandakan tujuan.
2. Dokumentasikan dengan jelas: Tulis deskripsi yang menjelaskan "mengapa".
3. Rencanakan pembersihan: Fitur flag bersifat sementara; rencanakan penghapusannya.
4. Pantau penggunaan: Aktifkan data impresi untuk flag penting.

Jenis flag

• Flag rilis: Untuk peluncuran fitur bertahap (hapus setelah peluncuran penuh).
• Flag eksperimen: Untuk pengujian A/B (hapus setelah analisis).
• Flag operasional: Untuk perilaku sistem (berumur lebih panjang, tinjau secara berkala).
• Kill switch: Untuk kontrol darurat (pertahankan hingga fitur stabil).
• Flag izin: Untuk kontrol akses (berumur lebih panjang, tinjau izin).

Konvensi penamaan

• Gunakan kebab-case: new-checkout-flow
• Bersikap deskriptif: enable-ai-recommendations bukan flag1.
• Sertakan cakupan saat diperlukan: mobile-push-notifications.

Referensi API

Server ini menggunakan Unleash Admin API. Untuk dokumentasi API lengkap, lihat:

• Spesifikasi OpenAPI Unleash Admin API
• Dokumentasi API Unleash

Endpoint yang digunakan

• GET /api/admin/projects - Daftar proyek
• GET /api/admin/projects/{projectId}/features - Daftar fitur flag
• POST /api/admin/projects/{projectId}/features - Buat fitur flag
• GET /api/admin/projects/{projectId}/features/{featureName} - Dapatkan detail flag
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - Tambahkan strategi peluncuran
• DELETE /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies/{strategyId} - Hapus strategi
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/on - Aktifkan flag
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - Nonaktifkan flag

Pemecahan masalah

Masalah konfigurasi

Kesalahan: "UNLEASH_BASE_URL harus berupa URL yang valid": Pastikan URL dasar Anda lengkap, termasuk protokol. Misalnya, https://app.unleash-hosted.com/instance. Hapus garis miring di akhir.

Kesalahan: "UNLEASH_PAT diperlukan": Periksa bahwa file .env Anda ada dan berisi UNLEASH_PAT={{your-personal-access-token}}. Verifikasi bahwa token valid di Unleash.

Masalah API

Kesalahan: "HTTP_401": Token akses pribadi Anda mungkin tidak valid atau kedaluwarsa. Buat token baru di bawah Profil > Lihat pengaturan profil > Token API pribadi > Token baru.

Kesalahan: "HTTP_403": Token Anda tidak memiliki izin untuk membuat flag di proyek ini. Tinjau peran dan izin Anda di Unleash.

Kesalahan: "HTTP_404": ID proyek tidak ada. Konfirmasi ID proyek di UI Admin Unleash.

Kesalahan: "HTTP_409": Flag dengan nama ini sudah ada di proyek. Gunakan nama yang berbeda atau gunakan kembali flag yang ada.

Lisensi

MIT

Kontribusi

Ini adalah proyek yang digerakkan oleh tujuan dengan cakupan yang fokus. Kontribusi harus:

• Selaras dengan permukaan alat yang ada dan model sumber daya MCP.
• Mempertahankan arsitektur tipis dan digerakkan oleh tujuan.
• Mengikuti praktik terbaik Unleash.
• Menyertakan dokumentasi yang jelas.