unleash-mcp

Unleash MCP 服务

一个以目标为导向的 Model Context Protocol（MCP）服务，用于管理 Unleash 功能标志。此服务可让由大模型驱动的编码助手按照 Unleash 最佳实践创建和管理功能标志。

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

概览

此 MCP 服务提供的工具可与 Unleash Admin API 集成，让 AI 编码助手能够：

• 创建功能标志，并进行适当的验证和类型检查。
• 检测现有标志，以防止重复创建或鼓励复用。
• 评估变更，判断何时需要功能标志。
• 流式传输进度，让操作过程清晰可见。
• 妥善处理错误，并提供有用的提示。
• 仅在用户选择同意后，通过 send_feedback 将 MCP 的问题反馈给 Unleash。
• 遵循 Unleash 文档中的最佳实践。

可用工具

此 MCP 服务提供以下工具：

• create_flag：在 Unleash 中创建功能标志。
• evaluate_change：评估风险并建议是否使用功能标志。
• detect_flag：查找现有功能标志，避免重复创建。
• wrap_change：提供如何用功能标志封装变更的指导。
• set_flag_rollout：设置各环境中哪些对象可以获取某个功能标志：发布百分比、分段、约束，以及该环境是否已启用。
• create_targeting：在某个项目中或为所有项目创建 set_flag_rollout 所针对的上下文字段和分段。
• get_flag_state：显示功能标志的元数据及其激活策略。
• get_flag_history：从事件日志中返回功能标志的近期变更，并逐项显示变更内容、操作者、时间和环境。
• evaluate_flag：在某个环境中，根据 Unleash 上下文（例如用户 ID 和自定义属性）评估单个功能标志，并说明哪些策略匹配。
• list_flags：列出项目中的所有功能标志，可选择分页和排序方式。
• search_flags：按名称或描述的一部分搜索所有项目中的活跃功能标志，或按完整名称查找某个标志及其所属项目。
• list_projects：列出配置令牌可访问的 Unleash 项目，可选择分页。
• toggle_flag_environment：在某个环境中启用或禁用功能标志。
• remove_flag_strategy：删除某个环境中的功能标志策略。
• update_flag_lifecycle：完成、取消完成、归档或恢复功能标志，或将其标记为过时。
• update_project_settings：设置项目的默认粘性（仅限 Enterprise）和各环境的默认策略，并将现有环境添加到项目中。
• cleanup_flag：生成安全移除标记代码路径的说明。
• send_feedback：向 Unleash 报告工具调用失败、不支持的请求或意外结果，以便改进 MCP。需要用户同意。如果用户通过 UNLEASH_MCP_SEND_FEEDBACK=false 或服务器选项 feedbackConsent 预先拒绝同意，则不会列出此工具。

核心工作流

AI 助手的核心工作流设计如下：

1. evaluate_change：首先评估代码变更，判断是否需要功能标志。
2. detect_flag：此工具通常由 evaluate_change 自动调用，以防止创建重复标志。
3. create_flag：如果需要新标志，此工具会在 Unleash 中创建它。
4. wrap_change：最后，此工具会提供用于实现新标志的特定语言代码。

有关核心工作流工具的更多信息，请参阅工具参考部分。

前置条件

运行服务之前，需要准备以下内容：

• Node.js 22 或更高版本
• pnpm 包管理器或 npm
• 一个 Unleash 实例（托管或可自托管）
• 一个个人访问令牌，且具有创建功能标记的权限

开始使用

本节介绍安装和运行 Unleash MCP 服务的不同方式。你可以按照Agent 设置（例如 Claude Code 和 Codex）进行配置，也可以使用 npx 将 MCP 作为独立进程运行，或采用本地开发设置。

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 设置（实验性）

你可以直接通过 HTTP 连接到 Unleash 实例内置的远程 MCP 服务，而不必在本地运行 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 [email protected] --activate

pnpm install

2. 直接从 Claude 或 Codex 以开发模式运行

避免 npm run 输出和 tsx watch 横幅，因为任何额外的标准输出都会破坏 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 会连同通道前缀一起写入此单个文件。协议消息仍会照常通过 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)。默认值：启用。

工具参考

本节详细介绍每个核心工具，包括其用途、参数和输出。

在执行写入前，这些工具会读取项目的变更请求设置和你的权限。与 Unleash UI 一样，如果你的变更需要审批，set_flag_rollout、toggle_flag_environment 和 remove_flag_strategy 会将变更放入变更请求，管理员也不例外；如果在那里设置了 SKIP_CHANGE_REQUEST，则会直接写入。使用 update_flag_lifecycle 归档时，只要任何环境启用了变更请求，就会为所有人创建变更请求，并优先选择生产环境。结果中会包含 outcome: "pendingApproval"，以及 requested 和变更请求的 id、url、state；其他情况下则为 outcome: "saved"。

变更会放入该环境中你已打开的变更请求，或新建一个，并基于你已在其中为该标志提交的待处理变更继续构建，因此后续变更会修改待处理的变更，而不是再添加第二项。重复提交已在等待处理的变更不会产生任何内容；如果请求的内容与当前线上状态相同，则会移除待处理的变更，而不是添加一项用于撤销它的变更。只有当新的变更请求中仅包含这些变更时，才会将其送审。你已有的草稿不会被提交，因此可以在准备就绪后于 Unleash 中提交；向正在审核或已批准的变更请求添加内容会重置其审批状态。如果某个标志的归档操作已经在等待处理，再次归档不会产生任何内容。

创建标志

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 资源 URI、创建时间戳和配置详情。

评估变更

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')
• Hook：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 工具会生成特定语言的代码片段和说明，指导如何使用功能标志包装代码。它可以帮助大模型和开发者遵循代码库中的现有模式，并正确使用标志。

使用时机

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

使用示例

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 工具用于设置哪些用户会在一个或多个环境中获得功能标志：设置发布百分比，可选择按用户群组和上下文字段上的约束条件进一步缩小范围，并设置各环境是否启用。

该工具会在进行任何更改前检查整个请求：包括每个环境、用户群组名称、上下文字段和约束值。如果用户群组名称或要更改的策略不明确，且 MCP 客户端可以显示表单，工具会要求用户从列表中选择。否则，错误信息会列出可供 Agent 提交给用户的有效选项。

在每个环境中：

• 如果没有策略，且条目设置了任何策略字段，工具会添加一个 flexibleRollout 策略。发布范围默认覆盖 100% 的目标用户，粘性默认值为 default。如果条目仅包含 enabled: true，则不会添加任何内容，因此 Unleash 会为该环境应用项目的默认策略。
• 如果只有一个 flexibleRollout 策略，则更新该策略。未提供的字段会保留原值，因此 { rolloutPercentage: 100 } 会将发布范围调至 100%，同时保留用户群组、约束条件、粘性和变体。
• 如果有多个策略，则必须提供 strategyId。
• 工具会先保存策略，再启用环境，以免 Unleash 在其旁边添加项目的默认策略。关闭环境会在保存前进行，因此新策略不会在该环境中生效。
• 启用一个所有策略均已禁用的环境时，工具会重新启用所有策略。

何时使用

在使用 create_flag 后调用此工具以逐步发布标志；之后也可用来更改哪些用户会获得该标志，例如将发布范围从 30% 提高到 100%。

参数

• featureName（必需）：功能标志名称。
• projectId（可选）：项目 ID（默认为 UNLEASH_DEFAULT_PROJECT）。
• environments（必需）：每个环境对应一项，每项包含：
  • environment（必需）：环境名称，例如 "production"。
  • rolloutPercentage（可选）：目标用户中可使用该标志的百分比（0-100）。
  • segments（可选）：分段名称，按用户提供的名称填写。大小写、空格和连字符均不影响匹配。[] 会移除所有分段。
  • constraints（可选）：约束条件，每项包含 contextName、operator（任意 Unleash 约束运算符）、values 或 value、inverted 和 caseInsensitive。[] 会移除所有约束。
  • strategyId（可选）：当环境中有多个策略时，要更改的策略。
  • strategyMode（可选）："update"（默认值）会更改现有策略。"add" 会在现有策略旁添加新的 flexibleRollout 策略。
  • stickiness（可选）：粘滞性字段。新策略使用 "default"。
  • groupId（可选）：用于粘滞性分桶的组 ID。新策略使用标志名称。
  • title（可选）：策略的描述性标题。
  • strategyDisabled（可选）：暂停策略，但不删除它。这与 enabled: false 不同；后者会在该环境中关闭标志。
  • variants（可选）：策略变体，每项包含 name、weight（0-1000）、weightType、stickiness 和 payload。[] 会移除所有变体。
  • enabled（可选）：开启或关闭环境。true 也会在策略已禁用时将其开启，除非同时传入 strategyDisabled。

使用示例

Agent 提示词

Turn on new-checkout-flow in development, and roll it out to 30% of beta users in production.

工具载荷

{
  "featureName": "new-checkout-flow",
  "projectId": "ecommerce",
  "environments": [
    { "environment": "development", "enabled": true },
    {
      "environment": "production",
      "rolloutPercentage": 30,
      "segments": ["beta users"],
      "enabled": true
    }
  ]
}

工具输出

对于每个环境，输出会说明策略是已添加、已更新还是保持不变，环境是否开启，以及已保存的发布百分比、分段名称和约束条件。更新时还会显示之前的值。备注会标明限制发布的情况，例如环境已关闭或仍有其他适用策略。结果还会链接到 Unleash Admin UI 中的标志、Admin API 以及该标志的 MCP 资源 URI。

错误

如果请求有问题，则不会进行任何更改。错误代码为 INVALID_ROLLOUT，problems 会一次列出所有问题，每项都包含其环境、代码、消息、提示，以及（如有）有效的 options：

代码	条件
ENVIRONMENT_NOT_FOUND	该标志没有同名环境。options 会列出其环境。
DUPLICATE_ENVIRONMENT	同一环境出现在多个条目中。
SEGMENT_NOT_FOUND	没有可供项目使用的片段与名称匹配、匹配到多个片段，或匹配到的片段属于其他项目。options 会列出匹配的名称；如果没有匹配项，则列出项目可使用的所有片段。
CONTEXT_FIELD_NOT_FOUND	项目没有同名上下文字段。如果仅大小写不同，提示会给出正确名称；否则会链接到可创建该字段的位置。options 会列出项目的字段。
INVALID_CONSTRAINT	约束没有值，或 Unleash 拒绝其值，例如 NUM_GT 使用文本，或值不在字段的合法值范围内。
STRATEGY_NOT_CHOSEN	环境有多个 flexibleRollout 策略，但没有 strategyId，或 strategyId 与其中任何一个都不匹配。options 会列出这些策略。
STRATEGY_NOT_FOUND	strategyId 与任何策略都不匹配，且环境没有可供选择的 flexibleRollout 策略。
STRATEGY_CONFLICT	条目同时设置了 strategyMode: "add" 和 strategyId。
STRATEGY_NOT_SUPPORTED	要更改的策略不是 flexibleRollout 策略。
LAST_STRATEGY_PAUSED	在保持开启的环境中，strategyDisabled: true 会暂停唯一的活动策略。当最后一个活动策略暂停时，Unleash 会关闭该环境；再次开启时会添加项目的默认策略。

其他错误：

• 如果字段是工具不认识的字段（例如拼写错误），则返回 VALIDATION_ERROR，因此该字段绝不会被忽略。
• 如果标志不在项目中，则返回 HTTP_404。提示会指向 create_flag 和 search_flags。
• 如果保存中途失败，错误会保留 Unleash 的代码，并添加 failedEnvironment、applied（已保存或已提交审核的环境）和 notChanged。

创建定向规则

create_targeting 工具会创建 上下文字段 和 片段，供 set_flag_rollout 用于定向。上下文字段会先于片段创建，因此一次调用可以先创建字段，再创建一个以该字段为约束条件的片段。

默认情况下，所有内容都归项目所有。scope: "global" 会使其可用于每个项目，且不能与 projectId 一起使用。项目上下文字段需要 Unleash 7.4.1 或更高版本。上下文字段和片段名称在整个实例中必须唯一。

只有在所有名称和约束都通过检查后才会开始创建。随后每个项目都会单独调用一次 API，且不会回滚。中途失败会停止调用，错误会列出已 created 的内容、失败的 failed 项，以及未尝试的 notAttempted 项。

参数

• projectId（可选）：要创建内容所属的项目（默认为 UNLEASH_DEFAULT_PROJECT）。
• scope（可选）："project"（默认）或 "global"。
• contextFields（可选）：字段列表，每个字段包含 name、description、legalValues、stickiness 和 sortOrder。名称应适合用于 URL，且最多 100 个字符。
• segments（可选）：片段列表，每个片段包含 name、description 和 constraints（结构与 set_flag_rollout 中相同）。

使用示例

工具负载

{
  "projectId": "ecommerce",
  "contextFields": [{ "name": "plan" }],
  "segments": [
    {
      "name": "enterprise customers",
      "constraints": [{ "contextName": "plan", "operator": "IN", "values": ["enterprise"] }]
    }
  ]
}

工具输出

scope、project（适用于项目范围）以及 created（上下文字段和片段列表，包含各自的 kind 和 name）。

错误

如果请求有问题，则不会创建任何内容。错误代码为 INVALID_TARGETING，problems 会一次性列出所有问题，每项均包含其所属项目的 kind 和 name、代码、消息、提示，以及（如有）有效的 options：

代码	情况
DUPLICATE_NAME	同一上下文字段或分段名称出现多次。
CONTEXT_FIELD_EXISTS	任意项目中已存在同名上下文字段。消息会说明该字段属于哪个项目。
SEGMENT_EXISTS	任意项目中已存在同名分段。
CONTEXT_FIELD_NOT_FOUND	分段约束指定的字段既不存在，也未在同一调用中创建。若其他项目中有同名字段，提示会说明这一点。options 会列出该分段可使用的字段。
INVALID_CONSTRAINT	约束没有值，或 Unleash 拒绝其值，例如为 NUM_GT 提供文本，或提供了超出字段合法值范围的值。

其他错误也会在创建任何内容之前返回：

• INVALID_SCOPE：scope: "global" 同时指定了 projectId。
• PROJECT_NOT_FOUND：项目不存在。提示会指向 list_projects。
• VALIDATION_ERROR：上下文字段超出 Unleash 的限制：名称不符合 URL 规范或超过 100 个字符、描述超过 250 个字符，或合法值超过 100 个字符或有重复。
• HTTP_404：Unleash 版本低于 7.4.1，因此不支持项目上下文字段。提示建议使用 scope: "global"。较旧版本仍支持项目分段。

如果创建过程中途失败，错误会保留 Unleash 的代码，并添加 failed、created 和 notAttempted。

获取功能开关状态

get_flag_state 工具会从 Unleash Admin API 获取功能开关当前的元数据和环境策略。它会返回功能开关的类型、启用／归档状态、曝光数据设置，以及各环境的策略和变体。

使用场景

在修改功能开关前检查它、查看各环境中有多少个策略处于启用状态，或在调用 remove_flag_strategy 前查找策略 ID 时，可使用此工具。

参数

• featureName（必填）：功能开关名称。
• projectId（可选）：项目 ID（默认为 UNLEASH_DEFAULT_PROJECT）。
• environment（可选）：将结果筛选为单个环境（不区分大小写）。
• includeSegments（可选）：同时返回匹配环境中的策略所使用的分段。
• includeContextFields（可选）：同时返回该功能开关所属项目中的约束可使用的上下文字段。

使用示例

Agent 提示词

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

工具负载

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

工具输出

返回一个 JSON 对象，其中包含完整的功能对象（所有环境和策略详情）、与筛选条件匹配的环境，以及 UI 和 API 链接。

策略仅通过 ID 列出其分段。如果匹配的环境使用了分段，输出会包含一个 hint，列出这些分段的名称。使用 includeSegments 时，输出会改为包含 segments，其中每项包含 id、name、description、project，以及用于确定包含对象的 constraints。无法获取的分段会列在 segmentErrors 下，每项包含 Unleash 返回的 error，且不会导致调用失败。

使用 includeContextFields 时，输出会包含 contextFields：根上下文字段以及项目自有字段，每项包含其 name、description、legalValues、是否可用于设置 rollout stickiness，以及（如果是项目专属字段）其所属的 project。

评估标志

evaluate_flag 工具使用 Unleash playground API，在某个环境中根据 Unleash 上下文评估单个功能标志。它会返回该标志在此上下文中是否启用、解析出的变体，以及逐策略的明细，列出未匹配的约束和分段。项目根据标志名称解析。

**Alpha：**此工具使用 POST /api/admin/playground/features/{featureName}，这是一个可能发生变化的 Unleash Alpha API。使用此工具需要 Unleash 版本提供此端点。

适用场景

使用此工具回答类似“用户 asdf 是否启用了 show-new-checkout？”的问题，或排查某个用户的标志为何处于关闭状态。若要检查标志的配置，请使用 get_flag_state。

参数

• featureName（必填）：功能标志名称。
• environment（可选）：要评估的环境（默认为 UNLEASH_DEFAULT_ENVIRONMENT；如果未设置，则为必填项）。
• context（可选）：扁平的 Unleash 上下文对象。userId、sessionId、remoteAddress、currentTime 和 appName 将作为标准字段发送；其他键（例如 tier）将作为自定义上下文属性发送。数字和布尔值会转换为字符串。也接受嵌套的 properties 对象。
• appName（可选）：上下文的应用名称（默认值：unleash-mcp）。

用法示例

Agent 提示词

Use evaluate_flag to check whether "show-new-checkout" is enabled in production
for userId "asdf" on the "top" tier.

工具载荷

{
  "featureName": "show-new-checkout",
  "environment": "production",
  "context": { "userId": "asdf", "tier": "top" }
}

工具输出

返回文本摘要，其中包含结果（ENABLED、DISABLED；当无法评估自定义策略时为 UNKNOWN）、变体、标志在环境中关闭或存在未满足依赖项时的警告、每个策略的结果及其未通过的约束和分段、发送的上下文，以及指向 Unleash Admin UI 中该标志的链接。结构化输出包含完整的 playground 响应。

获取标志历史记录

get_flag_history 工具从 Unleash 事件日志中获取某个功能标志最近的变更事件，按时间从新到旧排列。它不会返回每个事件完整的变更前后载荷，而是在工具内部计算结构化差异，仅返回发生变化的字段，让 Agent 直接读取变更内容，无需对比两个大型对象。

适用场景

在编辑或切换标志之前，使用此工具查看近期变更内容及变更者；也可用于说明标志为何处于当前状态。如果仅凭当前配置无法回答问题，请将此工具与 get_flag_state 配合使用。

参数

• featureName（必填）：功能标志名称。
• limit（可选）：要返回的最近变更数量上限，范围为 1 至 100（默认值：20）。

用法示例

Agent 提示词

Use get_flag_history with:
- featureName: "new-checkout-flow"
- limit: 10

工具载荷

{
  "featureName": "new-checkout-flow",
  "limit": 10
}

工具输出

返回一个 JSON 对象，其中包含 featureName、total（该标志记录的所有变更数量）和 events。每个事件都包含 createdAt、createdBy、type、environment 和 changes：一个变更叶节点列表，其中包含 path（例如 ["parameters", "rollout"]）、before 和 after。新增字段的 before 为 undefined，删除字段的 after 为 undefined。像 createdAt 和 lastSeenAt 这类独立变化的字段会从差异中剔除。对于没有载荷的事件，例如启用或禁用某个环境的事件，changes 列表为空；其类型由 type 描述。当 total 大于返回的事件数量时，请调高 limit。

列出标志

list_flags 工具会枚举某个项目中的功能标志，并返回带分页和排序的结构化清单。活动标志和已归档标志会分别返回：调用一次并设置 archived: false（默认值），再调用一次并设置 archived: true，即可汇总完整清单以用于审计工作流。

适用场景

当 Agent 需要查找现有标记时，可使用此工具，例如审计项目、寻找待清理的候选项，或在创建或封装标记前构建上下文。它相当于可由 Agent 调用的 unleash://projects/{projectId}/feature-flags 资源（参见 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"
}

工具输出

返回一个 JSON 对象，包含 projectId、archived、order、limit、offset、nextOffset、totalFlags 和 flags 数组（每个元素包含名称、类型、所属项目、归档状态和链接）。对于大型项目，可使用 nextOffset 获取后续页面。

搜索标记

search_flags 工具会在所有项目中，根据名称或描述的一部分搜索活跃功能标记。提供标记的完整名称时，它会返回该标记及其所属项目，而其他标记工具需要将所属项目作为 projectId。

参数

• query（必填）：标记名称或描述的一部分，或完整的标记名称。

工具输出

返回一个 JSON 对象，包含匹配标记的数量 total 和 flags。每个标记包含其名称、所属项目、类型、描述、是否过时，以及在各环境中是否启用。当 total 大于返回的标记数量时，可使用更长的查询词缩小结果范围。

列出项目

list_projects 工具会枚举配置的令牌可访问的 Unleash 项目，并支持分页和排序。

适用场景

当目标项目未知，或 Agent 需要在列出或创建标记前选择项目时，可使用此工具。它相当于可由 Agent 调用的 unleash://projects 资源（参见 MCP 资源）。

参数

• limit（可选）：每页的项目数量上限（默认值：服务端页面大小，通常为 20）。
• order（可选）：按项目创建时间排序，asc 或 desc（默认值：desc，最新的项目排在前面）。
• offset（可选）：分页时要跳过的项目数量（默认值：0）。

使用示例

Agent 提示词

Use list_projects to see which projects are available.

工具负载

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

工具输出

返回一个 JSON 对象，包含 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"
}

工具输出

返回一个 JSON 对象，包含新的启用状态、更新后的功能对象，以及指向 Unleash Admin UI 和 Admin API 中该标记的链接。

移除标记策略

remove_flag_strategy 工具会从功能标记环境中删除策略配置。请先使用 get_flag_state 查找策略 ID。

适用场景

使用此工具清理过时的策略，或替换 set_flag_rollout 无法更改的策略（即不是 flexibleRollout 的策略）：先移除该策略，再次调用 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"
}

工具输出

返回一个 JSON 对象，其中包含已移除的策略 ID、环境中剩余策略的数量、更新后的功能对象，以及 Unleash Admin UI 和 Admin API 中该标志的链接。

更新标志生命周期

update_flag_lifecycle 工具可推动功能标志完成其生命周期。Unleash 根据 SDK 指标设置 initial、pre-live 和 live 阶段，因此此工具只会更改 API 允许的状态：完成、归档、撤销这两项操作，以及过时标记。

适用场景

当标志已完成其使命时，使用此工具。建议的顺序是：先执行 complete，再执行 cleanup_flag 从代码中移除该标志，最后执行 archive。

参数

• featureName（必填）：功能标志名称。
• action（必填）：以下其中一项：
  • complete：将标志标记为已完成。需要提供 status。
  • uncomplete：撤销 complete。
  • archive：归档标志，使 SDK 不再接收该标志。如果其他标志依赖它，则拒绝归档。
  • revive：恢复已归档的标志。
  • mark_stale / unmark_stale：设置或清除过时标记，该标记独立于阶段。
• status（complete 时必填）：如果该功能保留在产品中，则为 "kept"；如果已移除，则为 "discarded"。
• statusValue（可选）：complete 的详细信息，例如保留的变体。
• projectId（可选）：项目 ID。省略时，工具会根据标志名称查找项目，因为标志名称在各项目之间是唯一的。

使用示例

Agent 提示词

The new checkout flow is fully rolled out. Mark "new-checkout-flow" as completed and kept.

工具负载

{
  "featureName": "new-checkout-flow",
  "action": "complete",
  "status": "kept",
  "projectId": "ecommerce"
}

工具输出

返回一个 JSON 对象，其中包含 changed、调用前后的标志生命周期状态 before 和 after、一行摘要 summary，以及包含后续工具调用建议的 help。当标志达到 completed 或 archived 状态时，help 会建议调用 cleanup_flag，并根据完成状态设置 preservePath（kept 保留启用路径，discarded 保留禁用路径）。如果标志已处于请求的状态，changed 将为 false，且不会进行任何修改。

更新项目设置

update_project_settings 工具可更改项目中标志的设置方式：各环境的默认策略、默认粘性，以及项目包含哪些环境。开启某个环境中尚无策略的标志时，Unleash 会添加该环境的默认策略；使用 toggle_flag_environment 开启其所有策略均已暂停的标志时（包括现有标志），也会添加该默认策略。

适用场景

当用户希望更改项目的默认设置时，使用此工具。可以添加环境，但不能移除环境。

参数

• projectId（可选）：项目 ID。默认使用 UNLEASH_DEFAULT_PROJECT。
• defaultStickiness（可选）：用于让用户始终处于同一分桶中的上下文属性，例如 sessionId。需要 Unleash Enterprise；开源版 Unleash 没有对应的端点。
• addEnvironments（可选）：要添加到项目中的现有环境名称。
• defaultStrategies（可选）：按环境配置 rolloutPercentage、segments（按名称）、constraints、stickiness、groupId、title 和 variants。未提供的字段保留当前值；[] 会清除 segments、constraints 或 variants。新默认策略会为每个功能标志分配独立的 groupId。

这三项设置中至少需要一项。只有所有名称和变体都通过验证后才会进行任何更改；如果当前默认策略不是 flexibleRollout 策略，则会拒绝操作，而不是替换它。首先设置默认粘滞性，因此在开源版 Unleash 上，调用会在任何更改发生前失败；然后添加环境，最后设置默认策略。操作不会回滚：如果某一步失败，错误会以输入原有的结构返回 applied、failed 和 notApplied。如果只是读取设置时失败，错误会返回 applied，并说明不要再次发送这些设置。在开源版 Unleash 上，defaultStickiness 会出现在 notSupported 下，而不是 failed 下。已匹配的设置不会再次写入，因此重复调用不会新增审计事件；同时会根据实例的限制检查约束。

使用示例

Agent 提示词

Flags turned on in production of ecommerce should start at 10% for the beta-users segment.

工具负载

{
  "projectId": "ecommerce",
  "defaultStrategies": [
    { "environment": "production", "rolloutPercentage": 10, "segments": ["beta-users"] }
  ]
}

工具输出

返回一个 JSON 对象，其中包含 applied、已匹配设置对应的 unchanged、项目的 defaultStickiness，以及每个环境的 defaultStrategy（对于已更改的策略，还包含 previous）。如果添加的环境已关闭更改请求，输出会附带相应说明。

清理功能标志

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 命令、针对各类模式的移除说明、特定语言的导入清理，以及清理后的验证步骤（重新搜索、运行测试、手动审查）。

发送反馈

send_feedback 工具会报告 MCP 未能满足预期的情况。报告会发送到 Unleash 托管的实例，以帮助确定修复事项和新工具的优先级。

使用时机

遇到以下情况之一时，助手应在回复用户之前调用此工具：

• tool_error：工具调用返回错误（身份验证错误除外，即 HTTP 401 或 403）。
• unsupported_action：用户请求的操作没有任何工具可以完成。
• unexpected_result：工具调用成功，但结果与预期不符。

工具调用成功后绝不要调用此工具，也不要用它来报告 send_feedback 本身发生的故障。

征求同意

只有用户同意后才会发送任何内容。首次调用时，MCP 会通过 MCP 征求提示词询问用户，并将答案保存在 feedback_consent.json 中，因此只会询问一次。该文件位于平台配置目录中：

• 设置了 XDG_CONFIG_HOME 时（适用于任何平台）：$XDG_CONFIG_HOME/unleash-mcp/feedback_consent.json。
• macOS：~/Library/Application Support/unleash-mcp/feedback_consent.json
• Linux：~/.config/unleash-mcp/feedback_consent.json
• Windows：%APPDATA%\unleash-mcp\feedback_consent.json（若未设置 APPDATA，则为 ~\AppData\Roaming\unleash-mcp\feedback_consent.json）

设置 UNLEASH_MCP_CONFIG_DIR 可将文件保存在其他目录。删除该文件即可再次收到询问。

如果用户拒绝，工具会返回一条消息，说明反馈功能已禁用；助手在本次会话中不应再次调用它。如果客户端不支持征求同意，或者提示已取消或 60 秒内未作答，则反馈在当前会话中保持禁用状态，且不会存储任何内容，因此会在下次会话中再次询问。

将 UNLEASH_MCP_SEND_FEEDBACK=true 或 UNLEASH_MCP_SEND_FEEDBACK=false 设为允许或拒绝同意，无需显示提示。此环境变量的优先级高于同意文件。这对不支持征求同意的客户端和 CI 配置很有用。通过这种方式拒绝同意时，send_feedback 工具不会出现在工具列表中，服务端指令也不会提及它，因此助手不会尝试调用它。

OpenCode、Google Gemini 和 Antigravity 不会向用户显示提示（OpenCode 会自动接受，Antigravity 会取消）。对于这些客户端，以及未报告名称的客户端，服务端会跳过提示并忽略同意文件，因为存储的同意可能并非来自用户。除非设置 UNLEASH_MCP_SEND_FEEDBACK=true，否则反馈功能会保持关闭。其他所有客户端均使用同意文件中存储的选择。

通过 createMcpHandler 将服务端嵌入 HTTP 主机时，除非主机传入 feedbackConsent，否则默认拒绝同意，因此默认不会向远程客户端提供 send_feedback。

记录的内容

只会发送允许列表中的字段：

• 问题类型、工具名称和规范化错误代码。
• MCP 版本、客户端名称和客户端版本。
• 助手提供的简短摘要。

摘要不得包含标志名称、项目 ID、代码、URL 或令牌。绝不会发送原始错误消息。

参数

• issueType（必填）：tool_error、unsupported_action 或 unexpected_result。
• summary（必填）：用一到两句话描述出了什么问题或用户请求了什么（最多 500 个字符）。
• tool（可选）：涉及的 MCP 工具名称，例如 create_flag。对于不受支持的请求，请省略。
• errorCode（可选）：失败的工具结果中的规范化错误代码，例如 HTTP_500 或 VALIDATION_ERROR。

使用示例

Agent 提示词

The set_flag_rollout call failed with HTTP_500. Use send_feedback to report it,
then tell me what happened.

工具载荷

{
  "issueType": "tool_error",
  "tool": "set_flag_rollout",
  "errorCode": "HTTP_500",
  "summary": "Configuring a gradual rollout failed with a server error even though the flag exists in the environment."
}

工具输出

返回一个包含 success、sent、dryRun 和 message 的 JSON 对象。message 会确认反馈已发送（或在 --dry-run 模式下将会发送），或者说明由于用户尚未同意，反馈功能已禁用。

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（例如 # 提及）显示资源，不允许 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
│   ├── attribution.ts           # Client attribution for outbound headers
│   └── feedbackHttpClient.ts    # send_feedback transport
├── http/
│   └── httpClient.ts            # Generic fetch wrapper for API clients
├── feedback/
│   ├── consentDecision.ts       # granted | denied consent type
│   ├── consentResolver.ts       # Resolves send_feedback consent (env, file, prompt)
│   ├── consentStore.ts          # Persists consent in feedback_consent.json
│   └── elicitation.ts           # MCP elicitation prompt asking the user once
├── 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
│   ├── constraints.ts           # Constraint schema and checks shared by set_flag_rollout and create_targeting
│   ├── createTargeting.ts       # create_targeting tool
│   ├── setFlagRollout.ts        # set_flag_rollout tool
│   ├── getFlagState.ts          # get_flag_state tool
│   ├── listFlags.ts             # list_flags tool
│   ├── listProjects.ts          # list_projects tool
│   ├── searchFlags.ts           # search_flags tool
│   ├── evaluateFlag.ts          # evaluate_flag tool
│   ├── getFlagHistory.ts        # get_flag_history tool
│   ├── toggleFlagEnvironment.ts # toggle_flag_environment tool
│   ├── removeFlagStrategy.ts    # remove_flag_strategy tool
│   ├── updateFlagLifecycle.ts   # update_flag_lifecycle tool
│   ├── updateProjectSettings.ts # update_project_settings tool
│   └── sendFeedback.ts          # send_feedback 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
    ├── toolResult.ts            # JSON tool results
    ├── showsElicitationForms.ts # Clients whose elicitation forms never reach the user
    └── stdioLogging.ts          # Stdio protocol traffic logging

设计原则

• 精简的接口范围：仅包含核心功能所需的端点。
• 以目标为导向：每个模块都服务于明确且具体的用途。
• 显式验证：在调用 API 前，使用 Zod 模式验证所有输入。
• 错误规范化：将所有错误转换为 {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（可选）。
• UNLEASH_MCP_SEND_FEEDBACK：设为 true 或 false，以在不提示的情况下允许或拒绝 send_feedback 同意（可选）。此设置会覆盖已存储的同意文件。
• UNLEASH_FEEDBACK_URL：接收 send_feedback 报告的 Unleash 实例基础 URL（可选）。默认为 Unleash 托管的生产实例。
• UNLEASH_MCP_CONFIG_DIR：存放 feedback_consent.json 的目录（可选）。默认为 同意 中所述的平台配置目录。

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 文档请参阅：

• Unleash Admin 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} - 获取标志详情
• GET /api/admin/segments/{id} - 获取分段
• POST /api/admin/segments - 创建分段
• GET /api/admin/context - 列出全局上下文字段
• GET /api/admin/context/{name} - 获取上下文字段
• POST /api/admin/context - 创建全局上下文字段
• GET /api/admin/projects/{projectId}/context - 列出项目的上下文字段
• POST /api/admin/projects/{projectId}/context - 创建项目上下文字段
• GET /api/admin/projects/{projectId}/overview - 获取项目设置和默认策略
• PUT /api/admin/projects/{projectId} - 设置项目默认粘性（仅限 Enterprise）
• GET /api/admin/environments - 列出环境
• POST /api/admin/projects/{projectId}/environments - 将环境添加到项目
• POST /api/admin/projects/{projectId}/environments/{environment}/default-strategy - 设置环境默认策略
• GET /api/admin/search/features - 搜索功能标志
• GET /api/admin/search/events - 获取功能标志的变更事件
• 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 - 禁用标志
• POST /api/admin/projects/{projectId}/features/{featureName}/lifecycle/complete - 完成标志
• POST /api/admin/projects/{projectId}/features/{featureName}/lifecycle/uncomplete - 取消完成标志
• POST /api/admin/projects/{projectId}/archive/validate - 归档前检查依赖项
• DELETE /api/admin/projects/{projectId}/features/{featureName} - 归档标志
• POST /api/admin/archive/revive/{featureName} - 恢复已归档的标志
• POST /api/admin/projects/{projectId}/stale - 将标志标记为过时或未过时
• GET /api/admin/projects/{projectId}/change-requests/config - 查找需要审批的环境
• GET /api/admin/user - 检查你是否可以跳过变更请求
• GET /api/admin/projects/{projectId}/change-requests/pending - 查找你未完成的变更请求及其中等待处理的变更
• POST /api/admin/projects/{projectId}/environments/{environment}/change-requests - 将变更添加到变更请求
• PUT /api/admin/projects/{projectId}/change-requests/{id}/changes/{changeId} - 修改等待添加的策略
• PUT /api/admin/projects/{projectId}/change-requests/{id}/state - 提交变更请求以供审核，或取消仅包含已撤回变更的请求
• DELETE /api/admin/projects/{projectId}/change-requests/{id}/changes/{changeId} - 撤回一项等待处理的变更
• DELETE /api/admin/projects/{projectId}/change-requests/{id} - 删除仅包含已撤回变更的草稿
• GET /api/admin/ui-config - 读取默认策略必须遵守的约束和分段限制

send_feedback 不会调用你的 Unleash 实例。它会向 Unleash 托管的反馈实例发送请求：POST {UNLEASH_FEEDBACK_URL}/feedback。

故障排除

配置问题

错误："UNLEASH_BASE_URL must be a valid URL"：确保基础 URL 完整，包含协议。例如，https://app.unleash-hosted.com/instance。请移除末尾的斜杠。

错误："UNLEASH_PAT is required"：检查 .env 文件是否存在且包含 UNLEASH_PAT={{your-personal-access-token}}。在 Unleash 中验证令牌是否有效。

API 问题

错误：“HTTP_401”：您的个人访问令牌可能无效或已过期。请前往 Profile > View Profile settings > Personal API tokens > New token 生成新令牌。

错误：“HTTP_403”：您的令牌没有在此项目中创建标志的权限。请在 Unleash 中检查您的角色和权限。

错误：“HTTP_404”：项目 ID 不存在。请在 Unleash 管理界面中确认项目 ID。

错误：“HTTP_409”：项目中已存在同名标志。请使用其他名称，或重复使用现有标志。

反馈问题

“反馈已禁用”：用户拒绝了授权，客户端无法显示授权提示，或已设置 UNLEASH_MCP_SEND_FEEDBACK=false。请设置 UNLEASH_MCP_SEND_FEEDBACK=true，或删除 feedback_consent.json，以便再次询问。请参阅授权。

错误：“无法连接到 Unleash 反馈端点”：报告无法连接到反馈实例。请检查您的网络是否可以访问 UNLEASH_FEEDBACK_URL（或默认生产实例）。标志操作不受影响。

许可证

MIT

贡献

这是一个目标明确、范围聚焦的项目。贡献应：

• 与现有工具范围和 MCP 资源模型保持一致。
• 维持轻量、目标明确的架构。
• 遵循 Unleash 最佳实践。
• 包含清晰的文档。