Unleash MCP Server

Unleash MCP Server

Server Model Context Protocol (MCP) yang berorientasi tujuan untuk mengelola feature flag Unleash. Server ini memungkinkan asisten coding berbasis LLM untuk membuat dan mengelola feature flag mengikuti praktik terbaik Unleash.

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

Gambaran Umum

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

• Membuat feature flag dengan validasi dan penentuan tipe yang tepat.
• Mendeteksi flag yang sudah ada untuk mencegah duplikasi atau mendorong penggunaan kembali.
• Mengevaluasi perubahan untuk memutuskan kapan feature flag diperlukan.
• Mengalirkan progres untuk visibilitas selama operasi.
• Menangani error dengan baik disertai petunjuk bermanfaat.
• Mengikuti praktik terbaik dari dokumentasi Unleash.

Alat yang tersedia

Server MCP menyediakan alat-alat berikut:

• create_flag: Membuat feature flag di Unleash.
• evaluate_change: Menilai risiko dan merekomendasikan penggunaan feature flag.
• detect_flag: Menemukan feature flag yang sudah ada untuk menghindari duplikasi.
• wrap_change: Memberikan panduan tentang cara membungkus perubahan dalam feature flag.
• set_flag_rollout: Mengonfigurasi strategi peluncuran untuk feature flag (tidak mengaktifkan flag).
• get_flag_state: Menampilkan metadata feature flag dan strategi aktivasinya.
• list_flags: Mencantumkan semua feature flag dalam sebuah proyek, dengan paginasi dan urutan opsional.
• list_projects: Mencantumkan proyek Unleash yang tersedia untuk token yang dikonfigurasi, dengan paginasi opsional.
• toggle_flag_environment: Mengaktifkan atau menonaktifkan feature flag di suatu environment.
• remove_flag_strategy: Menghapus strategi feature flag dari suatu environment.
• cleanup_flag: Menghasilkan instruksi untuk menghapus jalur kode yang ditandai 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 spesifik bahasa untuk mengimplementasikan flag baru.

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

Prasyarat

Sebelum Anda dapat menjalankan server, Anda memerlukan yang berikut:

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

Memulai

Bagian ini mencakup berbagai cara untuk menginstal dan menjalankan server Unleash MCP. 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 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 — tidak diperlukan proses lokal.

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 diperlukan 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 secara otomatis membuka browser Anda untuk login. Setelah mengautentikasi dengan Unleash, PAT dibuat dan digunakan untuk semua permintaan selanjutnya.

PAT kedaluwarsa setelah 24 jam secara default.

Token Akses Pribadi (PAT)

Gunakan metode ini ketika 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}}"

Flag --header mengirimkan PAT secara langsung, melewati alur OAuth sepenuhnya.

Mulai cepat dengan npx

Anda dapat menjalankan server MCP sebagai proses mandiri tanpa mengkloning repositori menggunakan npx. Berikan konfigurasi melalui variabel environment 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 --log-level debug

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

Pengaturan pengembangan lokal

Ikuti langkah-langkah ini 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 [email protected] --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 handshake MCP. Dua opsi senyap:

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 senyap (tidak ada output siklus hidup npm) dan menjalankan TS secara langsung; gunakan ini ketika Anda ingin menghindari build.
• node dist/index.js adalah pilihan teraman; pasangkan dengan npm run build:watch untuk membangun ulang saat ada perubahan sementara perintah agen tetap stabil.
• Log tetap berada di root repo (app.log, mcp-stdio.log), keduanya di-gitignore.

Kontrol logging

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

Atribusi klien

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

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 masing-masing alat inti secara rinci, termasuk tujuannya, parameter, dan output.

Buat flag

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

Kapan menggunakan

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

Parameter

Alat ini menerima parameter berikut:

• name (wajib): Nama feature flag unik dalam proyek.
• type (wajib): Tipe feature flag yang menunjukkan siklus hidup dan maksud.
  • release: Peluncuran fitur bertahap ke pengguna.
  • experiment: Pengujian A/B dan eksperimen.
  • operational: Perilaku sistem dan tombol operasional.
  • kill-switch: Penghentian darurat atau pemutus sirkuit.
  • permission: Mengontrol akses fitur berdasarkan peran atau hak pengguna.
• 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 ke 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
}

Output alat

Jika berhasil, alat mengembalikan objek JSON yang berisi URL feature 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 feature flag. Alat ini memeriksa struktur, konteks, dan potensi risiko perubahan dan mengembalikan rekomendasi dengan penjelasan dan langkah selanjutnya.

Kapan menggunakan

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

Cara kerjanya

Alat ini mengembalikan panduan terformat markdown yang terperinci untuk asisten LLM berdasarkan praktik terbaik Unleash.

Panduan ini 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 melewatkan flag.
• Tindakan selanjutnya: Memberikan instruksi spesifik tentang apa yang harus dilakukan selanjutnya.

Ketika evaluate_change menentukan bahwa flag diperlukan, ia memberikan instruksi eksplisit untuk:

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

Proses evaluasi

Alat ini 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 ini menggunakan pola agnostik bahasa untuk menilai risiko:

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

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

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

Outputnya mencakup skor confidence (0-1) yang mewakili kepastian yang dinilai sendiri oleh LLM, yang meningkat dengan lebih banyak konteks yang disediakan.

Kategori dikecualikan mencakup file yang tidak memerlukan feature flag terlepas dari 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 ini 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 />}
• Guard: if (!isEnabled('flag')) return;
• Wrapper: withFeatureFlag('flag', () => {...})

Parameter

Semua parameter bersifat opsional, tetapi lebih banyak konteks menghasilkan rekomendasi yang lebih baik:

• repository (string): Nama atau jalur repositori.
• branch (string): Nama branch saat ini.
• files (array): Daftar file yang diubah.
• description (string): Deskripsi perubahan.
• riskLevel (enum): low, medium, high, atau critical, sebagaimana dinilai oleh 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 (mis., "create_new"), nama flag yang disarankan, tingkat risiko, dan explanation 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 feature flag yang ada di basis kode sehingga Anda dapat menggunakannya kembali alih-alih membuat duplikat. Alat ini secara otomatis terintegrasi ke dalam alur kerja evaluate_change tetapi juga dapat digunakan secara manual.

Kapan menggunakan

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

Cara kerjanya

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

• Deteksi berbasis file: Cari di file yang Anda modifikasi untuk flag yang ada.
• Analisis riwayat Git: Cari flag yang baru ditambahkan dalam riwayat commit.
• Pencocokan nama semantik: Cocokkan deskripsi dengan nama flag yang 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 kepercayaan

Alat ini mengembalikan kandidat dengan skor kepercayaan:

• Tinggi ≥0.7: Kecocokan kuat; penggunaan kembali direkomendasikan.
• Sedang 0.4-0.7: Kemungkinan cocok; tinjau secara manual.
• Rendah <0.4: 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 dimodifikasi. Misalnya, ["src/payments/stripe.ts", "src/checkout/flow.ts"].
• codeContext (opsional): Kode terdekat untuk dipindai flag.

Contoh penggunaan

Prompt agen

Periksa flag yang 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 true, itu termasuk objek candidate dengan nama flag, lokasi, skor kepercayaan, 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 potongan kode dan panduan spesifik bahasa untuk membungkus kode dengan feature flag. Ini membantu LLM dan pengembang mengikuti pola yang ada di basis kode dan menggunakan flag dengan benar.

Kapan menggunakan

Gunakan alat ini setelah Anda membuat feature flag (dengan create_flag) dan perlu mengimplementasikannya dalam kode Anda. Ini sangat berguna ketika Anda ingin memastikan Anda mengikuti pola basis kode yang ada atau memerlukan contoh spesifik framework (mis., 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 basis kode Anda menggunakan grep.
2. Deteksi pola: Mengidentifikasi pola umum (misalnya, impor, nama variabel klien, nama metode, atau gaya pembungkusan).
3. Template default: Potongan kode fallback jika tidak ada pola yang ditemukan.
4. Contoh spesifik framework: Pola khusus untuk React, Express, Django, dan lainnya.
5. Beberapa pola: Blok-if, klausa guard, hook, dekorator, middleware, dan lainnya.

Bahasa dan framework yang didukung:

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

Parameter

• flagName (wajib): Nama feature flag untuk membungkus kode. Misalnya: "new-checkout-flow", atau "stripe-integration".
• language (opsional): Bahasa pemrograman (terdeteksi otomatis dari fileName jika tidak disediakan). Didukung: typescript, javascript, python, go, ruby, php, csharp, java, rust
• fileName (opsional): Nama file yang 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): Framework 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 terformat markdown yang komprehensif yang memandu pengguna tentang cara membungkus kode mereka. Ini mencakup mulai 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 environment feature flag. Ini mengatur persentase peluncuran, stickiness, dan varian tingkat strategi opsional. Ini tidak mengaktifkan flag; gunakan toggle_flag_environment untuk menyalakannya.

Kapan menggunakan

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 feature flag.
• environment (wajib): Environment 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 terkini feature flag dan strategi environment dari Unleash Admin API. Ini mengembalikan tipe flag, status diaktifkan/diarsipkan, pengaturan data impresi, dan ringkasan per environment dari strategi dan varian aktif.

Kapan menggunakan

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

Parameter

• featureName (wajib): Nama feature flag.
• projectId (opsional): ID Proyek (default ke UNLEASH_DEFAULT_PROJECT).
• environment (opsional): Filter hasil ke satu environment (tidak sensitif 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 dari flag (tipe, diaktifkan/diarsipkan/data-impresi, proyek, ringkasan environment dengan jumlah strategi) bersama dengan tautan UI dan API. Output terstruktur mencakup objek fitur lengkap dengan semua environment dan detail strategi.

Daftar flag

Alat list_flags menghitung feature flag dalam sebuah proyek dan mengembalikan inventaris terstruktur dengan paginasi dan urutan. 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 menggunakan

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 setara yang dapat dipanggil agen dari sumber daya unleash://projects/{projectId}/feature-flags (lihat sumber daya MCP).

Parameter

• projectId (opsional): Proyek untuk mendaftarkan flag (default ke UNLEASH_DEFAULT_PROJECT; diselesaikan otomatis ketika satu proyek ada).
• archived (opsional): true untuk mendaftarkan flag yang diarsipkan alih-alih yang aktif. Default ke false. Flag aktif dan diarsipkan tidak dapat dikembalikan dalam respons yang sama.
• limit (opsional): Flag maksimum per halaman (default: ukuran halaman server, biasanya 50).
• order (opsional): Urutan 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, tipe, proyek, status diarsipkan, dan tautan). Gunakan nextOffset untuk berpindah halaman melalui proyek besar.

Daftar proyek

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

Kapan menggunakan

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

Parameter

• limit (opsional): Proyek maksimum per halaman (default: ukuran halaman server, biasanya 20).
• order (opsional): Urutan berdasarkan waktu pembuatan proyek, asc atau desc (default: desc, terbaru dulu).
• 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 environment flag

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

Kapan menggunakan

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

Parameter

• featureName (wajib): Nama feature flag.
• environment (wajib): Environment untuk dialihkan (misalnya, "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 environment (diaktifkan/dinonaktifkan, jumlah strategi), dan tautan ke flag di UI Admin Unleash dan Admin API.

Hapus strategi flag

Alat remove_flag_strategy menghapus konfigurasi strategi dari environment feature flag. Gunakan get_flag_state terlebih dahulu untuk menemukan ID strategi.

Kapan menggunakan

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

Parameter

• featureName (wajib): Nama feature flag.
• environment (wajib): Environment tempat strategi akan dihapus.
• strategyId (wajib): ID strategi yang akan dihapus (temukan ini 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 environment, dan tautan ke flag di UI Admin Unleash dan Admin API.

Bersihkan flag

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

Kapan menggunakan

Gunakan alat ini ketika feature flag telah menyelesaikan siklus hidupnya:

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

Cara kerjanya

Alat ini mengembalikan instruksi pembersihan komprehensif yang memandu LLM melalui:

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

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

Parameter

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

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 spesifik bahasa, dan langkah verifikasi pasca-pembersihan (cari ulang, jalankan pengujian, tinjau manual).

Sumber daya MCP

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

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

Dua template pertama menerima parameter kueri opsional: limit (ukuran halaman), order (asc atau desc), dan offset (awal paginasi). Respons mencakup 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 #-mentions) dan tidak membiarkan 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 melalui jalur yang sama.

Contoh pembacaan sumber daya

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

Mengembalikan 10 feature flag pertama di proyek ecommerce, diurutkan berdasarkan abjad, dengan metadata paginasi.

Arsitektur

Server mengikuti desain yang fokus dan berorientasi 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

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

Konfigurasi

Bagian ini menyediakan referensi cepat untuk semua opsi konfigurasi.

Variabel environment:

• UNLEASH_BASE_URL: URL instance Unleash Anda (wajib). Baik https://your-instance.getunleash.io maupun https://your-instance.getunleash.io/api diterima — server menormalkan /api di akhir jika ada, sehingga Anda dapat menempelkan nilai yang sama seperti yang diharapkan kebanyakan 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 membuat 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 maksud: Pilih tipe flag yang tepat untuk menandakan tujuan.
2. Dokumentasikan dengan jelas: Tulis deskripsi yang menjelaskan "mengapa".
3. Rencanakan pembersihan: Feature flag bersifat sementara; rencanakan penghapusannya.
4. Pantau penggunaan: Aktifkan data impresi untuk flag penting.

Tipe 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
• Bersikaplah deskriptif: enable-ai-recommendations bukan flag1.
• Sertakan cakupan bila 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 feature flag
• POST /api/admin/projects/{projectId}/features - Buat feature 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

Error: "UNLEASH_BASE_URL must be a valid URL": Pastikan URL dasar Anda lengkap, termasuk protokol. Misalnya, https://app.unleash-hosted.com/instance. Hapus semua garis miring di akhir.

Error: "UNLEASH_PAT is required": Periksa apakah file .env Anda ada dan berisi UNLEASH_PAT={{your-personal-access-token}}. Verifikasi bahwa token tersebut valid di Unleash.

Masalah API

Error: "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.

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

Error: "HTTP_404": ID proyek tidak ada. Konfirmasikan ID proyek di UI Admin Unleash.

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

Lisensi

MIT

Berkontribusi

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

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