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 服务器

一个用于管理 Unleash 功能标志的、有明确用途的 Model Context Protocol (MCP) 服务器。该服务器使基于 LLM 的编码助手能够按照 Unleash 最佳实践创建和管理功能标志。

如需分享反馈，请加入我们的 社区 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：列出配置的令牌可用的 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

远程代理设置（实验性）

无需在本地运行 MCP 服务器，您可以直接通过 HTTP 连接到 Unleash 实例内置的远程 MCP 服务器。这使用了 Streamable 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 实例，转到 Profile > Personal Access Tokens，然后创建一个新令牌。

对于 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 配对使用，以便在代理命令保持稳定的同时，在更改时重新构建。
  • 日志保留在仓库根目录（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）。

使用示例

代理提示

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 最佳实践 为 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（字符串）：用于父级标志检测的周围代码。

使用示例

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 工具枚举配置的令牌可访问的 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 管理界面和管理 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 管理界面和管理 API 中该开关的链接。

清理开关

cleanup_flag 工具会生成逐步说明，用于安全地从代码库中移除功能开关代码，同时保留所需的代码路径。

使用时机

当功能开关的生命周期结束时使用此工具：

  • 当发布达到 100% 且不再需要该开关时。
  • 当弃用实验性功能时（保留禁用路径）。
  • 当移除不再必要的紧急开关时。
  • 在旧开关的技术债务清理期间。

工作原理

该工具返回全面的清理说明，指导 LLM 完成以下步骤：

  1. 使用 grep 模式查找开关的所有出现位置。
  2. 识别使用模式（if-else 块、三元表达式、守卫子句、钩子、装饰器、中间件）。
  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 字段。

资源与工具： MCP 资源由应用程序控制，因此许多客户端仅通过用户驱动的界面（例如 # 提及）来展示它们，而不允许 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 管理 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”：确保您的 base 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 最佳实践。
  • 包含清晰的文档。