Unleash MCP Server

Unleash MCP 伺服器

一個專為管理 Unleash 功能旗標而設計的 模型上下文協定 (MCP) 伺服器。此伺服器讓 LLM 驅動的程式碼助理能夠遵循 Unleash 最佳實務來建立和管理功能旗標。

若要分享意見回饋，請加入我們的 社群 Slack 或在 GitHub 上開立議題。

概觀

此 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：列出已設定權杖可用的 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：最後，此工具會提供特定語言的程式碼來實作新旗標。

請參閱 工具參考 章節，以取得核心工作流程工具的更多資訊。

先決條件

在執行伺服器之前，您需要以下項目：

• Node.js 22 或更高版本
• pnpm 套件管理器或 npm
• 一個 Unleash 執行個體（託管或自託管）
• 一個具有建立功能旗標權限的個人存取權杖

開始使用

本章節涵蓋安裝和執行 Unleash MCP 伺服器的不同方式。您可以遵循 代理程式（例如 Claude Code 和 Codex）的設定、使用 npx 將 MCP 作為獨立程序執行，或使用本機開發設定。

代理程式設定

您可以將 MCP 伺服器直接新增至 Claude Code 或 Codex。代理程式設定是路徑特定的。您必須從要使用 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

遠端代理程式設定（實驗性）

您可以透過 HTTP 直接連線到 Unleash 執行個體內建的遠端 MCP 伺服器，而無需在本機執行 MCP 伺服器。這使用可串流的 HTTP 傳輸 — 不需要本機程序。

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

OAuth

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

針對 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 小時後過期。

個人存取權杖 (PAT)

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

若要建立 PAT：登入您的 Unleash 執行個體，前往個人檔案 > 個人存取權杖，然後建立一個新的權杖。

針對 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 --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 [email protected] --activate

pnpm install

2. 直接從 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 配對，以便在變更時重新建置，同時代理程式命令保持穩定。
• 日誌保留在儲存庫根目錄中（app.log、mcp-stdio.log），兩者皆被 git 忽略。

日誌控制

• 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 會以通道前綴分流寫入此單一檔案。協定訊息仍會正常透過 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）。

使用範例

代理程式提示

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 管理 UI 中的 URL、用於程式化存取的 MCP 資源連結、建立時間戳記和設定詳細資料。

評估變更

evaluate_change 工具會評估程式碼變更是否應置於功能旗標之後。它會檢查變更的結構、上下文和潛在風險，並傳回包含說明和後續步驟的建議。

使用時機

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

運作方式

此工具會根據 Unleash 最佳實務，為 LLM 助理傳回詳細的、以 Markdown 格式化的指引。

指引包括：

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

當 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（字串）：用於偵測父旗標的周遭程式碼。

使用範例

代理提示

讓代理自行收集上下文的簡單用法：

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（選填）：用於掃描旗標的鄰近程式碼。

使用範例

代理提示

在建立旗標前檢查現有旗標：

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"。

使用範例

代理提示

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}）。

使用範例

代理提示

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 管理 UI 中該旗標的連結、管理 API 策略 URL，以及該旗標的 MCP 資源連結。

取得旗標狀態

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

使用時機

在修改旗標之前，使用此工具來檢查旗標；或檢查跨環境有多少作用中策略；或在呼叫 remove_flag_strategy 之前尋找策略 ID。

參數

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

使用範例

代理提示

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

工具酬載

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

工具輸出

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

列出旗標

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

使用時機

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

參數

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

使用範例

代理提示

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 工具會列舉已設定權杖可用的 Unleash 專案，並提供分頁和排序順序。

使用時機

當目標專案未知，或代理需要在列出或建立旗標前選擇專案時，使用此工具。它是 unleash://projects 資源的代理可調用版本（請參閱 MCP 資源）。

參數

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

使用範例

代理提示

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）。

使用範例

代理提示

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

工具酬載

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

工具輸出

回傳新狀態的確認訊息、環境摘要（已啟用／已停用、策略數量），以及指向 Unleash 管理介面和管理 API 中該旗標的連結。

移除旗標策略

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

使用時機

當需要清理過時的策略，或透過移除舊策略並使用 set_flag_rollout 設定新策略來替換現有策略時，可使用此工具。

參數

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

使用範例

代理提示

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 管理介面和管理 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 自動偵測。

使用範例

代理提示

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 欄位。

資源與工具的比較： MCP 資源由應用程式控制，因此許多客戶端僅透過使用者驅動的 UI（例如 # 提及）來呈現它們，而不會讓代理自行呼叫 resources/read。當代理需要以程式化方式列舉專案或旗標時，請使用 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. 監控使用情況：為重要旗標啟用 impression 資料。

旗標類型

• 發布旗標：用於漸進式功能部署（全面部署後移除）。
• 實驗旗標：用於 A/B 測試（分析後移除）。
• 操作旗標：用於系統行為（生命週期較長，定期審查）。
• 終止開關：用於緊急控制（維持到功能穩定為止）。
• 權限旗標：用於存取控制（生命週期較長，審查權限）。

命名慣例

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

API 參考

此伺服器使用 Unleash 管理 API。如需完整的 API 文件，請參閱：

• Unleash 管理 API OpenAPI 規範
• Unleash 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 管理介面中確認專案 ID。

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

授權

MIT

貢獻

這是一個目的導向的專案，具有明確的範圍。貢獻應符合以下條件：

• 與現有的工具表面和 MCP 資源模型保持一致。
• 維持精簡、目的導向的架構。
• 遵循 Unleash 最佳實務。
• 包含清晰的文件。