解锁MCP服务器

一个以目的为导向的模型上下文协议（MCP）服务器，用于管理Unleash特性标志。此服务器使LLM驱动的编码助手能够按照Unleash的最佳实践创建和管理特性标志。

实验性功能

Unleash MCP服务器是一个实验性功能。其功能可能会发生变化，我们目前不建议在生产环境中使用它。

要分享反馈，请加入我们的社区Slack，在GitHub上打开一个问题，或通过电子邮件联系我们：beta@getunleash.io。

概览

这个MCP服务器提供了与Unleash管理API集成的工具，允许AI编码助手：

• 创建特性标志，具有适当的验证和类型。
• 检测现有标志，以防止重复或鼓励重用。
• 评估变更，决定何时需要特性标志。
• 流式进度，在操作期间提供可见性。
• 优雅地处理错误，并提供有用的提示。
• 遵循最佳实践，从Unleash文档中获取。

可用工具

MCP服务器暴露了以下工具：

• create_flag：在Unleash中创建一个特性标志。
• evaluate_change：评分风险并推荐特性标志的使用。
• detect_flag：发现现有的特性标志以避免重复。
• wrap_change：提供如何将更改包装在一个特性标志中的指导。
• set_flag_rollout：配置特性标志的推出策略（不会启用该标志）。
• get_flag_state：显示特性标志的元数据及其激活策略。
• 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 18或更高版本
• Yarn包管理器或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

使用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. 安装依赖项

克隆仓库并使用Yarn安装依赖项。

git clone https://github.com/Unleash/unleash-mcp.git
cd unleash-mcp
yarn install

2. 配置环境变量

复制.env.example到.env并填写您的Unleash凭据：

cp .env.example .env

编辑.env：

UNLEASH_BASE_URL={{your-instance-url}}
UNLEASH_PAT={{your-personal-access-token}}
UNLEASH_DEFAULT_PROJECT={{default_project_id}}  # 可选：MCP应默认使用的项目

3. 构建项目

yarn build

输出将在dist/目录中。

4. （可选）运行检查

# 类型检查和代码格式化
yarn lint

# 运行测试（Vitest框架已配置，但尚未有测试套件）
yarn test

运行服务器

开发模式带热重载

yarn dev

生产模式

node dist/index.js

带有CLI标志

# 干运行模式（模拟API调用而不实际创建标志）
node dist/index.js --dry-run

# 自定义日志级别
node dist/index.js --log-level debug

# 组合标志
node dist/index.js --dry-run --log-level debug

工具参考

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

创建标志

create_flag工具在Unleash中创建一个新的特性标志，并进行全面验证和进度跟踪。

何时使用

当您已经确定需要一个特性标志（例如，在运行evaluate_change之后），并且准备好使用正确的类型和元数据创建它时，使用此工具。

参数

该工具接受以下参数：

• name（必需）：项目内唯一的特性标志名称。
• type（必需）：表示生命周期和意图的特性标志类型。
  • release：逐步向用户推出功能。
  • experiment：A/B测试和实验。
  • operational：系统行为和操作切换。
  • kill-switch：紧急关闭或断路器。
  • permission：基于用户角色或权限控制功能访问。
• description（必需）：清晰解释标志控制的内容以及存在的原因。
• projectId（可选）：目标项目（默认为UNLEASH_DEFAULT_PROJECT）。
• impressionData（可选）：启用分析跟踪（默认为false）。

使用示例

代理提示

使用create_flag：
- name: "new-checkout-flow"
- type: "release"
- description: "逐步推出重新设计的结账体验"
- projectId: "ecommerce"

工具负载

{
  "name": "new-checkout-flow",
  "type": "release",
  "description": "逐步推出重新设计的结账体验，带有改进的转化追踪",
  "projectId": "ecommerce",
  "impressionData": true
}

工具输出

成功时，工具返回一个包含新特性标志在Unleash管理UI中的URL、MCP资源链接以供程序访问、创建时间戳和配置详情的JSON对象。

评估变更

evaluate_change工具评估代码更改是否应该位于特性标志之后。它检查更改的结构、上下文和潜在风险，并返回带有解释和下一步行动的建议。

何时使用

在功能或修改的开始阶段使用evaluate_change，以了解工作是否需要特性标志。此工具也有助于在不确定使用哪种标志类型或需要部署计划指导时使用。

如何工作

该工具根据Unleash最佳实践为LLM助手提供详细的、Markdown格式的指导。

指导包括：

• 父标志检测：检查代码是否已被现有标志保护。
• 风险评估：分析代码模式以识别危险操作。
• 代码类型评估：分类更改（例如，测试、配置、功能或错误修复）。
• 建议：建议创建标志、使用现有标志或跳过标志。
• 下一步行动：提供具体的下一步操作指令。

当evaluate_change确定需要标志时，它会提供明确的指示：

1. 调用create_flag工具创建特性标志。
2. 调用wrap_change工具获取特定于语言的代码包装指导。
3. 根据检测到的模式实施包装代码。

评估过程

工具遵循明确的评估过程：

步骤1：收集代码更改（git diff，读取文件）
↓
步骤2：检查父标志（避免嵌套）
↓
步骤3：评估代码类型（测试？配置？功能？）
↓
步骤4：评估风险（认证？支付？API更改？）
↓
步骤5：计算风险分数
↓
步骤6：提出建议
↓
步骤7：采取行动（创建标志或继续无标志）

风险评估

工具使用语言无关的模式来评分风险：

• 关键风险（+5分）：例如，认证、支付、安全和数据库操作。
• 高风险（+3分）：例如，API更改、外部服务或新类。
• 中等风险（+2分）：例如，异步操作或状态管理。
• 低风险（+1分）：例如，错误修复、重构或小改动。

父标志检测

工具跨语言查找常见模式，例如：

• 条件语句：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（枚举）：用户评估的“低”、“中”、“高”或“关键”。
• codeContext（字符串）：用于父标志检测的周围代码。

使用示例

代理提示 简单使用，让代理收集上下文：

使用evaluate_change帮助我确定是否需要特性标志

明确指示：

使用evaluate_change：
- description: "添加Stripe支付处理"
- riskLevel: "高"

工具负载

{
  "repository": "my-app",
  "branch": "feature/stripe-integration",
  "files": ["src/payments/stripe.ts"],
  "description": "添加Stripe支付处理",
  "riskLevel": "高",
  "codeContext": "用于父标志检测的周围代码"
}

工具输出

返回一个包含评估结果的JSON对象，包括needsFlag布尔值、recommendation（例如，“create_new”）、建议的标志名称、风险等级和详细的explanation。

{
  "needsFlag": true,
  "reason": "新功能",
  "recommendation": "create_new",
  "suggestedFlag": "stripe-payment-integration",
  "riskLevel": "关键",
  "riskScore": 5,
  "explanation": "此更改集成了Stripe支付，这是一个关键风险...",
  "confidence": 0.9
}

检测标志

detect_flag工具在代码库中查找现有的特性标志，以便您可以重用它们而不是创建重复项。此工具被自动集成到evaluate_change工作流程中，也可以手动使用。

何时使用

在创建新特性标志之前或在代码评估期间使用此工具，以检查可能已经覆盖您用例的现有标志。这有助于防止标志重复。

如何工作

该工具返回全面搜索指令，并使用多种检测策略：

• 基于文件的检测：在您正在修改的文件中搜索现有标志。
• Git历史分析：查看提交历史中最近添加的标志。
• 语义名称匹配：将描述与现有标志名称匹配。
• 代码上下文分析：检查更改周围的代码。

然后，工具遵循评分过程：

步骤1：执行基于文件的搜索（在目标文件中grep标志模式）
↓
步骤2：搜索Git历史中最近添加的标志
↓
步骤3：执行语义匹配（描述 → 标志名称）
↓
步骤4：分析代码上下文（如果提供）
↓
步骤5：结合所有方法的得分
↓
步骤6：返回最佳候选者及置信度得分

置信水平

工具返回带有置信度得分的候选人：

• 高 ≥0.7：强匹配；建议重用。
• 中等 0.4-0.7：可能匹配；手动审查。
• 低 <0.4：弱匹配；很可能创建新标志。

参数

• description（必需）：更改或特性的描述。例如，"使用Stripe的支付处理"，"新的结账流程"。
• files（可选）：正在修改的文件。例如，["src/payments/stripe.ts", "src/checkout/flow.ts"]。
• codeContext（可选）：附近要扫描标志的代码。

使用示例

代理提示 在创建标志之前检查现有标志：

使用detect_flag，描述为"使用Stripe的支付处理"`

自动集成在评估中：

使用evaluate_change - 自动搜索现有标志

工具负载

{
  "description": "使用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": "在您正在修改的同一文件中找到，2天前添加",
    "detectionMethod": "基于文件"
  }
}

未找到匹配：

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

包装更改

wrap_change工具生成特定于语言的代码片段和指导，用于将代码包装在特性标志中。它帮助LLMs和开发人员遵循代码库中的现有模式并正确使用标志。

何时使用

在您已经创建了一个特性标志（使用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"。

使用示例

代理提示

使用wrap_change：
- flagName: "new-checkout-flow"
- fileName: "src/components/checkout.ts"
- frameworkHint: "React"

工具负载

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