Unleash

官方

用於管理 Unleash 功能開關並自動化最佳實踐的 MCP 伺服器。

GitHub
22

你可以用 Unleash MCP 做什麼？

  • 評估程式碼變更 — 呼叫 evaluate_change 來評估風險，並建議程式碼變更是否需要功能旗標。
  • 建立功能旗標 — 使用 create_flag 佈建新旗標，包含類型、描述與專案目標設定。
  • 偵測既有旗標 — 執行 detect_flag 在程式碼或 Git 歷史紀錄中尋找可重複使用的旗標，避免重複建立。
  • 取得包覆指引 — 請求 wrap_change 提供特定語言的程式碼範本，以實作旗標。
  • 管理推出與狀態 — 設定 set_flag_rollout 的百分比，然後使用 toggle_flag_environment 啟用或停用旗標。
  • 檢查與列出旗標 — 使用 get_flag_state 或 list_flags 檢視旗標中繼資料、策略與專案清單。

文件

Unleash MCP Server

一個以目的驅動的 Model Context Protocol (MCP) 伺服器，用於管理 Unleash 功能旗標。此伺服器讓 LLM 驅動的程式碼輔助工具能夠依照 Unleash 最佳實務來建立與管理功能旗標。

若要分享意見回饋，請加入我們的 community Slack 或在 GitHub 上開啟 issue。

總覽

此 MCP 伺服器提供與 Unleash Admin API 整合的工具，讓 AI 程式碼輔助工具能夠：

  • 建立功能旗標，並具備適當的驗證與型別檢查。
  • 偵測既有旗標，以避免重複或鼓勵重用。
  • 評估變更，以決定何時需要功能旗標。
  • 串流進度，讓操作過程具有可視性。
  • 妥善處理錯誤，並提供實用的提示。
  • 遵循 Unleash 文件 中的最佳實務。

可用工具

MCP 伺服器提供以下工具：

  • create_flag：在 Unleash 中建立功能旗標。
  • evaluate_change：評估風險並建議是否使用功能旗標。
  • detect_flag：探索既有的功能旗標以避免重複。
  • wrap_change：提供如何以功能旗標包裝變更的指引。
  • set_flag_rollout：為功能旗標設定逐步推出策略（不會啟用旗標）。
  • get_flag_state：顯示功能旗標的中繼資料及其啟用策略。
  • list_flags：列出專案中的所有功能旗標，可選擇分頁與排序方式。
  • list_projects：列出設定 token 可存取的 Unleash 專案，可選擇分頁。
  • toggle_flag_environment：在環境中啟用或停用功能旗標。
  • remove_flag_strategy：從環境中刪除功能旗標的策略。
  • cleanup_flag：產生安全移除旗標保護程式碼路徑的指示。

核心工作流程

AI 輔助工具的核心工作流程設計如下：

  1. evaluate_change：首先，評估程式碼變更以判斷是否需要旗標。
  2. detect_flag：這通常會由 evaluate_change 自動呼叫，以防止建立重複的旗標。
  3. create_flag：如果需要新旗標，此工具會在 Unleash 中建立它。
  4. wrap_change：最後，此工具提供語言特定的程式碼來實作新旗標。

請參閱 Tool reference 一節以取得核心工作流程工具的更多資訊。

先決條件

在執行伺服器之前，您需要具備以下條件：

  • Node.js 22 或更高版本
  • pnpm 套件管理器或 npm
  • 一個 Unleash 實例（託管或自架）
  • 一個具有建立功能旗標權限的 personal access token

開始使用

本節涵蓋安裝與執行 Unleash MCP 伺服器的不同方式。您可以遵循 agents（例如 Claude Code 和 Codex）的設定、使用 npx 將 MCP 作為 standalone process 執行，或使用 local development 設定。

Agent 設定

您可以將 MCP 伺服器直接新增至 Claude Code 或 Codex。Agent 設定是路徑特定的。您必須在想要使用 MCP 的專案根目錄中執行以下命令。

適用於 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

適用於 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

遠端 Agent 設定（實驗性）

除了在本機執行 MCP 伺服器之外，您也可以直接透過 HTTP 連線到 Unleash 實例內建的遠端 MCP 伺服器。這使用 Streamable HTTP transport — 不需要本機程序。

注意： 遠端 MCP 是一項實驗性功能，必須在您的 Unleash 實例上啟用。請聯絡 Unleash 團隊以啟用此功能。

OAuth

OAuth 流程會開啟您的瀏覽器、讓您登入 Unleash，並自動佈建一個短期有效的 PAT。不需要手動管理 token。

適用於 Claude Code：

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

適用於 Codex：

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

首次使用時，用戶端會自動開啟您的瀏覽器進行登入。在透過 Unleash 驗證後，會建立一個 PAT，並用於所有後續請求。

PAT 預設會在 24 小時後過期。

Personal Access Token (PAT)

當您已經有 PAT 或需要無頭／非互動式存取（CI 管線、共享開發環境、不支援 OAuth 的用戶端）時，請使用此方法。

若要建立 PAT：登入您的 Unleash 實例，前往 Profile > Personal Access Tokens，然後建立新的 token。

適用於 Claude Code：

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

適用於 Codex：

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

--header 旗標會直接傳送 PAT，完全略過 OAuth 流程。

使用 npx 快速開始

您可以使用 npx 將 MCP 伺服器作為獨立程序執行，而無需複製儲存庫。請在執行命令的目錄中透過環境變數或本機 .env 檔案提供設定：

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 支援與本機建置相同的旗標（例如 --dry-run、--log-level）。

本機開發設定

請遵循以下步驟來設定專案以進行本機開發。

  1. 安裝相依套件

複製儲存庫並使用 pnpm 安裝相依套件。Corepack 可讓所有人使用相同的 pnpm 版本：

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
  1. 直接從 Claude 或 Codex 以開發模式執行

避免 npm run 輸出和 tsx watch 橫幅，因為任何額外的 stdout 都會破壞 MCP 交握。有兩個安靜的選項：

A) 使用編譯後的 JS（最可靠）

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) 直接使用 TypeScript（不需建置）

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"

注意事項：

  • node --import tsx 是安靜的（沒有 npm 生命週期輸出）並直接執行 TS；當您想要避免建置時請使用此選項。
  • node dist/index.js 是最安全的選擇；請搭配 npm run build:watch 在變更時重新建置，同時保持 agent 命令穩定。
  • 日誌會保留在儲存庫根目錄（app.log、mcp-stdio.log），兩者皆已加入 gitignore。

日誌控制

  • LOG_LEVEL（建議）：控制應用程式日誌的詳細程度（debug、info、warn、error）。未設定時預設為 error。
  • --log-level CLI 旗標：當您想要一次性變更時，可選擇性地覆寫 LOG_LEVEL。
  • APP_LOG_FILE（選用）：若設定，應用程式日誌會寫入此檔案（而非 stdout）。若未設定，日誌會寫入 stderr。
  • MCP_STDIO_LOG_FILE（選用）：若設定，MCP 的 stdin/stdout/stderr 會以通道前綴 tee 到這個單一檔案中。協定訊息仍會正常透過 stdout 傳送。

用戶端歸因

當 MCP 用戶端在初始化期間傳送 clientInfo（Claude Code、Cursor、Copilot、Windsurf、Codex、Kiro 及其他符合規範的用戶端）時，伺服器會在對外的 Unleash Admin API 呼叫中豐富 User-Agent 標頭：

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

這讓 Unleash 事件日誌可以回答「哪個 AI 工具建立或切換了此旗標」，而無需任何伺服器端變更。歸因值會經過清理，因此不會破壞 User-Agent 標頭。

設定 UNLEASH_MCP_CLIENT_ATTRIBUTION=off 以停用豐富化並還原為 unleash-mcp/<version> (MCP Server)。預設：啟用。

工具參考

本節詳細說明每個核心工具，包括其用途、參數和輸出。

建立旗標

create_flag 工具會在 Unleash 中建立新的功能旗標，並具備完整的驗證和進度追蹤。

使用時機

當您已確定需要功能旗標時（例如，在執行 evaluate_change 之後），且已準備好以正確的型別和中繼資料建立它時，請使用此工具。

參數

此工具接受以下參數：

  • name（必填）：專案內唯一的功能旗標名稱。
  • type（必填）：表示生命週期和意圖的功能旗標型別。
    • release：逐步向使用者推出功能。
    • experiment：A/B 測試和實驗。
    • operational：系統行為和操作切換。
    • kill-switch：緊急關閉或斷路器。
    • permission：根據使用者角色或權限控制功能存取。
  • description（必填）：清楚說明此旗標控制什麼以及為何存在。
  • projectId（選用）：目標專案（預設為 UNLEASH_DEFAULT_PROJECT）。
  • impressionData（選用）：啟用分析追蹤（預設為 false）。

使用範例

Agent 提示詞

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

工具負載

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

工具輸出

成功時，此工具會傳回一個 JSON 物件，其中包含新功能旗標在 Unleash Admin UI 中的 URL、用於程式化存取的 MCP 資源連結、建立時間戳記和設定詳細資料。

評估變更

evaluate_change 工具會評估程式碼變更是否應放在功能旗標後面。它會檢查變更的結構、內容和潛在風險，並傳回建議、說明和後續步驟。

使用時機

在功能或修改的開始階段使用 evaluate_change，當您想要了解該工作是否需要功能旗標時。當您不確定要使用哪種旗標型別或想要取得推出規劃的指引時，此工具也很有幫助。

運作方式

此工具會根據 Unleash 最佳實務 傳回詳細的、Markdown 格式的指引給 LLM 輔助工具。

指引包含：

  • 父旗標偵測：檢查程式碼是否已受既有旗標保護。
  • 風險評估：分析程式碼模式以識別高風險操作。
  • 程式碼型別評估：分類變更（例如，測試、設定、功能或錯誤修正）。
  • 建議：建議是否建立旗標、使用既有旗標或略過旗標。
  • 後續動作：提供接下來該做什麼的具體指示。

當 evaluate_change 判斷需要旗標時，它會提供明確指示：

  1. 呼叫 create_flag 工具以建立功能旗標。
  2. 呼叫 wrap_change 工具以取得語言特定的程式碼包裝指引。
  3. 依照偵測到的模式實作包裝後的程式碼。

評估流程

此工具遵循明確的評估流程：

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)

風險評估

此工具使用語言無關的模式來評分風險：

  • 重大風險（分數 +5）：例如，驗證、付款、安全和資料庫操作。
  • 高風險（分數 +3）：例如，API 變更、外部服務或新類別。
  • 中風險（分數 +2）：例如，非同步操作或狀態管理。
  • 低風險（分數 +1）：例如，錯誤修正、重構或小型變更。

分數會跨符合的類別累積。總分對應到風險等級：

  • 重大：分數 ≥ 5
  • 高：分數 ≥ 3
  • 中：分數 ≥ 2
  • 低：分數 < 2

輸出包含一個 confidence 分數（0-1），代表 LLM 自我評估的確定程度，會隨著提供更多內容而增加。

排除類別涵蓋無論內容為何都不需要功能旗標的檔案：測試檔案（*.test.ts、*_test.go 等）、設定檔案（*.config.js、.env、*.yaml）和文件檔案（*.md、docs/**）。僅限於排除檔案的變更不會觸發旗標建議。

完整的模式定義，包括每個類別的關鍵字、檔案 glob、程式碼模式和推理，位於 src/evaluation/riskPatterns.ts。

父旗標偵測

此工具會尋找跨語言的常見模式，例如：

  • 條件式：if (isEnabled('flag'))、if client.is_enabled('flag'):
  • 指派：const enabled = useFlag('flag')
  • 鉤子：const enabled = useFlag('flag') → {enabled && <Component />}
  • 守衛：if (!isEnabled('flag')) return;
  • 包裝器：withFeatureFlag('flag', () => {...})

參數

所有參數皆為選填，但提供更多上下文可獲得更好的建議：

  • repository（字串）：儲存庫名稱或路徑。
  • branch（字串）：目前分支名稱。
  • files（陣列）：正在變更的檔案清單。
  • description（字串）：變更的描述。
  • riskLevel（列舉）：low、medium、high 或 critical，由使用者評估。
  • codeContext（字串）：用於父旗標偵測的周圍程式碼。

使用範例

Agent 提示詞

簡單用法，讓 agent 自行收集上下文：

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

明確指示：

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

工具負載

{
  "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"
}

工具輸出

回傳包含評估結果的 JSON 物件，包括 needsFlag 布林值、recommendation（例如 "create_new"）、建議的旗標名稱、風險等級，以及詳細的 explanation。

{
  "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
}

偵測旗標

detect_flag 工具會在程式碼庫中尋找既有的功能旗標，以便重複使用而非建立重複項目。此工具已自動整合至 evaluate_change 工作流程，但也可手動使用。

使用時機

在建立新的功能旗標之前，或在程式碼評估期間使用此工具，檢查是否已有涵蓋您使用案例的既有旗標。這有助於避免旗標重複。

運作方式

此工具回傳全面的搜尋指示，並使用多種偵測策略：

  • 基於檔案的偵測：在您正在修改的檔案中搜尋既有旗標。
  • Git 歷史分析：在提交歷史中尋找近期新增的旗標。
  • 語意名稱比對：將描述與既有旗標名稱進行比對。
  • 程式碼上下文分析：檢查變更周圍的程式碼。

接著，工具會遵循評分流程：

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

信心等級

工具會回傳帶有信心分數的候選項目：

  • 高 ≥0.7：強烈相符；建議重複使用。
  • 中 0.4-0.7：可能相符；請手動審查。
  • 低 <0.4：微弱相符；可能需建立新旗標。

參數

  • description（必填）：變更或功能的描述。例如："payment processing with Stripe"、"new checkout flow"。
  • files（選填）：正在修改的檔案。例如：["src/payments/stripe.ts", "src/checkout/flow.ts"]。
  • codeContext（選填）：用於掃描旗標的鄰近程式碼。

使用範例

Agent 提示詞

建立旗標前檢查既有旗標：

Use detect_flag with description "payment processing with Stripe"

在評估中自動整合：

Use evaluate_change - automatically searches for existing flags

工具負載

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

工具輸出

回傳指示是否找到旗標的 JSON 物件。若 flagFound 為 true，則包含 candidate 物件，內含旗標名稱、位置、信心分數及相符原因。

找到相符項目：

{
  "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"
  }
}

未找到相符項目：

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

包裝變更

wrap_change 工具會產生語言特定的程式碼片段與指引，協助以功能旗標包裝程式碼。它幫助 LLM 和開發人員遵循程式碼庫中的既有模式，並正確使用旗標。

使用時機

在您已建立功能旗標（使用 create_flag）並需要在程式碼中實作時使用此工具。當您希望確保遵循既有程式碼庫模式，或需要特定框架的範例（例如 React、Django）時特別有用。

運作方式

此工具是 evaluate_change → create_flag → wrap_change 工作流程的最後一步。

工具在其回應中提供以下指引：

  1. 搜尋指示：使用 grep 在程式碼庫中尋找既有旗標模式的逐步指南。
  2. 模式偵測：識別常見模式（例如匯入、客戶端變數名稱、方法名稱或包裝風格）。
  3. 預設範本：若未找到模式時的備用程式碼片段。
  4. 框架特定範例：針對 React、Express、Django 等的專門模式。
  5. 多種模式：if 區塊、守衛子句、hooks、裝飾器、中介軟體等。

支援的語言與框架：

  • TypeScript/JavaScript：Node.js、React Hooks、Express 中介軟體。
  • Python：FastAPI、Django、Flask 裝飾器。
  • Go：標準 if 區塊、HTTP 中介軟體。
  • Ruby：Rails 控制器。
  • PHP：Laravel 控制器。
  • C#：.NET/ASP.NET 控制器。
  • Java：Spring Boot。
  • Rust：Actix/Rocket 處理器。

參數

  • flagName（必填）：用於包裝程式碼的功能旗標名稱。例如："new-checkout-flow" 或 "stripe-integration"。
  • language（選填）：程式語言（若未提供，會從 fileName 自動偵測）。支援：typescript、javascript、python、go、ruby、php、csharp、java、rust
  • fileName（選填）：正在修改的檔案名稱（有助於偵測語言）。例如："checkout.ts"、"payment.py" 或 "handler.go"。
  • codeContext（選填）：用於協助偵測既有模式的周圍程式碼。
  • frameworkHint（選填）：用於專門範本的框架。例如："React"、"Express"、"Django"、"Rails" 或 "Spring Boot"。

使用範例

Agent 提示詞

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

工具負載

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

工具輸出

回傳一份全面的 Markdown 格式字串，引導使用者如何包裝其程式碼。內容包括快速入門、搜尋指示、含佔位符的包裝指示、該語言的所有可用範本，以及 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.]

設定旗標逐步發布

set_flag_rollout 工具在功能旗標環境上設定 flexibleRollout 策略。它設定發布百分比、黏性及選用的策略層級變體。此操作不會啟用旗標；請使用 toggle_flag_environment 來開啟。

使用時機

在使用 create_flag 建立旗標後，使用此工具在啟用前設定流量分配方式。也可用於更新既有發布百分比或新增變體。

參數

  • featureName（必填）：功能旗標名稱。
  • environment（必填）：目標環境（例如 "production"、"development"）。
  • rolloutPercentage（必填）：接收該功能的流量百分比（0-100）。
  • projectId（選填）：專案 ID（預設為 UNLEASH_DEFAULT_PROJECT）。
  • groupId（選填）：黏性分桶鍵（預設為功能名稱）。
  • stickiness（選填）：黏性欄位（預設為 "default"）。
  • title（選填）：策略的描述性標題。
  • disabled（選填）：以停用狀態建立策略（預設為 false）。
  • variants（選填）：策略層級變體清單，每個包含 name、weight（0-1000）、選用的 weightType（"variable" 或 "fix"）、stickiness 及 payload（{type, value}）。

使用範例

Agent 提示詞

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

工具負載

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

工具輸出

回傳確認訊息，包含已設定的百分比、Unleash Admin UI 中的旗標連結、Admin API 策略 URL，以及該旗標的 MCP 資源連結。

取得旗標狀態

get_flag_state 工具從 Unleash Admin API 取得功能旗標目前的中繼資料與環境策略。它回傳旗標類型、啟用/封存狀態、印象資料設定，以及各環境中作用中策略與變體的摘要。

使用時機

在修改旗標前使用此工具進行檢查，查看各環境中有多少作用中策略，或在呼叫 remove_flag_strategy 前尋找策略 ID。

參數

  • featureName（必填）：功能旗標名稱。
  • projectId（選填）：專案 ID（預設為 UNLEASH_DEFAULT_PROJECT）。
  • environment（選填）：將結果篩選至單一環境（不區分大小寫）。

使用範例

Agent 提示詞

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

工具負載

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

工具輸出

回傳旗標的文字摘要（類型、啟用/封存/印象資料、專案、含策略計數的環境摘要），以及 UI 和 API 連結。結構化輸出包含完整的功能物件，含所有環境與策略詳細資料。

列出旗標

list_flags 工具列舉專案中的功能旗標，並回傳含分頁與排序順序的結構化清單。作用中與已封存旗標會分開回傳：以 archived: false（預設值）呼叫一次，再以 archived: true 呼叫一次，即可組合成完整的清單，用於稽核工作流程。

使用時機

當 agent 需要探索已存在的旗標時使用此工具，例如稽核專案、尋找清理候選項目，或在建立或包裝旗標前建立上下文。它是 unleash://projects/{projectId}/feature-flags 資源的 agent 可呼叫對應項目（參見 MCP 資源）。

參數

  • projectId（選填）：要列出旗標的專案（預設為 UNLEASH_DEFAULT_PROJECT；當僅有一個專案時自動解析）。
  • archived（選填）：true 用於列出已封存旗標而非作用中旗標。預設為 false。作用中與已封存旗標無法在同一回應中回傳。
  • limit（選填）：每頁最大旗標數（預設：伺服器頁面大小，通常為 50）。
  • order（選填）：依旗標名稱排序，asc 或 desc（預設：asc）。
  • offset（選填）：分頁時跳過的旗標數（預設：0）。

使用範例

Agent 提示詞

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

工具負載

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

工具輸出

回傳文字摘要及結構化內容，包含 projectId、archived、order、limit、offset、nextOffset、totalFlags 及 flags 陣列（每個包含名稱、類型、專案、封存狀態與連結）。使用 nextOffset 在大型專案中進行分頁。

列出專案

list_projects 工具列舉設定 token 可存取的 Unleash 專案，含分頁與排序順序。

使用時機

當目標專案未知，或 agent 需要在列出或建立旗標前選擇專案時使用此工具。它是 unleash://projects 資源的 agent 可呼叫對應項目（參見 MCP 資源）。

參數

  • limit（選填）：每頁最大專案數（預設：伺服器頁面大小，通常為 20）。
  • order（選填）：依專案建立時間排序，asc 或 desc（預設：desc，最新優先）。
  • offset（選填）：分頁時跳過的專案數（預設：0）。

使用範例

Agent 提示詞

Use list_projects to see which projects are available.

工具負載

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

工具輸出

回傳文字摘要及結構化內容，包含 order、limit、offset、nextOffset、totalProjects 及 projects 陣列（每個包含 id、名稱、描述、模式、建立時間與 URL）。

切換旗標環境

toggle_flag_environment 工具在特定環境中啟用或停用功能旗標。對於漸進式發布，請先使用 set_flag_rollout 設定策略，再啟用。

使用時機

在設定發布策略後使用此工具開啟旗標，或在事件期間或完成發布後停用旗標。

參數

  • featureName （必填）：功能旗標名稱。
  • environment （必填）：要切換的環境（例如 "production"）。
  • enabled （必填）：true 以啟用，false 以停用。
  • projectId （選填）：專案 ID（預設為 UNLEASH_DEFAULT_PROJECT）。

使用範例

Agent 提示詞

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

工具負載

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

工具輸出

回傳新狀態的確認、環境摘要（啟用/停用、策略數量），以及指向 Unleash Admin UI 和 Admin API 中該旗標的連結。

移除旗標策略

remove_flag_strategy 工具會從功能旗標環境中刪除策略設定。請先使用 get_flag_state 來找出策略 ID。

使用時機

使用此工具清理過時的策略，或透過移除舊策略並使用 set_flag_rollout 設定新策略來取代現有策略。

參數

  • featureName （必填）：功能旗標名稱。
  • environment （必填）：要從中移除策略的環境。
  • strategyId （必填）：要移除的策略 ID（可透過 get_flag_state 找到）。
  • projectId （選填）：專案 ID（預設為 UNLEASH_DEFAULT_PROJECT）。

使用範例

Agent 提示詞

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

工具負載

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

工具輸出

回傳移除確認、環境中剩餘策略的數量，以及指向 Unleash Admin UI 和 Admin API 中該旗標的連結。

清理旗標

cleanup_flag 工具會產生逐步指示，用於安全地從程式碼庫中移除功能旗標程式碼，同時保留所需的程式碼路徑。

使用時機

當功能旗標的生命週期結束時使用此工具：

  • 當推出達到 100% 且不再需要該旗標時。
  • 當淘汰實驗性功能時（保留停用路徑）。
  • 當移除不再需要的緊急開關時。
  • 在舊旗標的技術債清理期間。

運作方式

此工具回傳全面的清理指示，引導 LLM 完成以下步驟：

  1. 使用 grep 模式找出旗標的所有出現位置。
  2. 識別使用模式（if-else 區塊、三元表達式、守衛子句、hooks、裝飾器、中介軟體）。
  3. 移除旗標檢查，同時保留正確的程式碼路徑。
  4. 使用語言特定的指引清理未使用的匯入。
  5. 透過清理後的搜尋和測試步驟驗證變更。

如果未提供 preservePath，工具會回傳指示，要求在使用者繼續前詢問要保留哪條路徑。

參數

  • flagName （必填）：要移除的功能旗標名稱（例如 "new-checkout-flow"）。
  • preservePath （選填）："enabled" 以保留旗標開啟的程式碼路徑（適用於已完成的推出），或 "disabled" 以保留旗標關閉的路徑（適用於已移除的實驗）。如果省略，工具會提示您詢問使用者。
  • files （選填）：要清理的特定檔案。如果省略，會搜尋整個程式碼庫。
  • language （選填）：用於專門匯入清理指引的程式語言（例如 "typescript"、"python"）。如果未提供，會從 files 自動偵測。

使用範例

Agent 提示詞

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

工具負載

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

工具輸出

回傳一份 Markdown 指南，涵蓋清理範圍和保留路徑、用於找出所有出現位置的 grep 指令、各模式的移除指示、語言特定的匯入清理，以及清理後的驗證步驟（重新搜尋、執行測試、手動審查）。

MCP 資源

伺服器註冊了 MCP 資源，用於讀取專案和功能旗標資料。所有資源皆回傳 JSON，並快取 60 秒。

URI 模板說明
unleash://projects{?limit,order,offset}列出專案。預設頁面大小：20，依建立時間排序（最新的在前）。
unleash://projects/{projectId}/feature-flags{?limit,order,offset}列出專案中的旗標。預設頁面大小：50，依字母順序排序。
unleash://projects/{projectId}/feature-flags/{flagName}單一功能旗標的中繼資料。

前兩個模板接受選用的查詢參數：limit（頁面大小）、order（asc 或 desc），以及 offset（分頁起點）。回應包含 fetchedAt、cached、totalProjects 或 totalFlags，以及 nextOffset 欄位。

資源 vs. 工具： MCP 資源由應用程式控制，因此許多用戶端僅透過使用者驅動的 UI（例如 # 提及）來呈現，且不允許 agent 自行呼叫 resources/read。當 agent 需要以程式化方式列舉專案或旗標時，請使用 list_projects 和 list_flags 工具，它們會透過工具介面回傳相同的資料。detect_flag 庫存分析也透過相同路徑進行。

範例資源讀取

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

回傳 ecommerce 專案中前 10 個功能旗標，依字母順序排序，並附分頁中繼資料。

架構

此伺服器採用聚焦且目的驅動的設計。

結構

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

設計原則

  • 精簡的介面範圍：僅包含核心功能所需的端點。
  • 目的驅動：每個模組都有特定且明確的用途。
  • 明確驗證：Zod 架構在 API 呼叫前驗證所有輸入。
  • 錯誤標準化：所有錯誤皆轉換為 {code, message, hint} 格式。
  • 進度串流：長時間執行的操作提供可見性。
  • 最佳實務整合：工具說明中嵌入 Unleash 文件的指引。

設定

本節提供所有設定選項的快速參考。

環境變數：

  • UNLEASH_BASE_URL：您的 Unleash 實例 URL（必填）。https://your-instance.getunleash.io 和 https://your-instance.getunleash.io/api 皆可接受——伺服器會正規化尾端的 /api（若存在），因此您可以貼上大多數 Unleash SDK 所預期的相同值。
  • UNLEASH_PAT：個人存取權杖（必填）。
  • UNLEASH_DEFAULT_PROJECT：MCP 應使用的預設專案 ID（選填）。

CLI 旗標：

  • --dry-run：模擬操作而不進行實際 API 呼叫。
  • --log-level：設定記錄詳細程度（debug、info、warn、error）。

最佳實務

此伺服器鼓勵 官方文件 中的 Unleash 最佳實務：

旗標生命週期

  1. 有目的地建立：選擇正確的旗標類型以傳達用途。
  2. 清楚記錄：撰寫說明「為什麼」的描述。
  3. 規劃清理：功能旗標是暫時的；規劃其移除。
  4. 監控使用情況：為重要旗標啟用曝光資料。

旗標類型

  • 發布旗標：用於漸進式功能推出（完整推出後移除）。
  • 實驗旗標：用於 A/B 測試（分析後移除）。
  • 營運旗標：用於系統行為（生命週期較長，定期審查）。
  • 緊急開關：用於緊急控制（維護至功能穩定為止）。
  • 權限旗標：用於存取控制（生命週期較長，審查權限）。

命名慣例

  • 使用 kebab-case：new-checkout-flow
  • 具描述性：enable-ai-recommendations 而非 flag1。
  • 需要時包含範圍：mobile-push-notifications。

API 參考

此伺服器使用 Unleash Admin API。完整的 API 文件請參閱：

使用的端點

  • GET /api/admin/projects - 列出專案
  • GET /api/admin/projects/{projectId}/features - 列出功能旗標
  • POST /api/admin/projects/{projectId}/features - 建立功能旗標
  • GET /api/admin/projects/{projectId}/features/{featureName} - 取得旗標詳細資料
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - 新增推出策略
  • DELETE /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies/{strategyId} - 移除策略
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/on - 啟用旗標
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - 停用旗標

疑難排解

設定問題

錯誤：「UNLEASH_BASE_URL 必須是有效的 URL」：確保您的基礎 URL 完整，包含通訊協定。例如 https://app.unleash-hosted.com/instance。移除任何尾端的斜線。

錯誤：「需要 UNLEASH_PAT」：檢查您的 .env 檔案是否存在且包含 UNLEASH_PAT={{your-personal-access-token}}。驗證該權杖在 Unleash 中是否有效。

API 問題

錯誤：「HTTP_401」：您的個人存取權杖可能無效或已過期。請在 個人資料 > 檢視個人資料設定 > 個人 API 權杖 > 新增權杖 下產生新權杖。

錯誤：「HTTP_403」：您的權杖沒有在此專案中建立旗標的權限。請在 Unleash 中審查您的角色和權限。

錯誤：「HTTP_404」：專案 ID 不存在。請在 Unleash Admin UI 中確認專案 ID。

錯誤：「HTTP_409」：此名稱的旗標已存在於專案中。請使用不同的名稱或重複使用現有旗標。

授權

MIT

貢獻

這是一個目的驅動且範圍聚焦的專案。貢獻應：

  • 與現有的工具介面和 MCP 資源模型保持一致。
  • 維持精簡且目的驅動的架構。
  • 遵循 Unleash 最佳實務。
  • 包含清楚的文件。