Unleash MCP Server

Unleash MCP 服务器

一个专为管理 Unleash 功能开关而设计的 模型上下文协议 (MCP) 服务器。该服务器使基于 LLM 的编码助手能够遵循 Unleash 最佳实践来创建和管理功能开关。

要分享反馈，请加入我们的 社区 Slack 或在 GitHub 上提交问题。

概述

此 MCP 服务器提供与 Unleash 管理 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 服务器。这使用可流式传输的 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），两者均被 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 管理 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 块、守卫子句、钩子、装饰器、中间件等。

支持的语言和框架：

• 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 管理 UI 和管理 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 管理 UI 和管理 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 自动检测。

使用示例

代理提示

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. 监控使用情况：为重要的开关启用印象数据。

开关类型

• 发布开关：用于逐步推出功能（完全推出后移除）。
• 实验开关：用于 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 管理 UI 中确认项目 ID。

错误：“HTTP_409”：项目中已存在具有此名称的开关。请使用其他名称或复用现有开关。

许可证

MIT

贡献

这是一个目的驱动的项目，范围集中。贡献应：

• 与现有的工具表面积和 MCP 资源模型保持一致。
• 保持精简、目的驱动的架构。
• 遵循 Unleash 最佳实践。
• 包含清晰的文档。