Bucket Feature Flags MCP Server

Reflag CLI

用于与 Reflag 服务交互的命令行界面。该 CLI 允许你管理应用、 标志、身份验证，并为你的 Reflag 标志生成 TypeScript 类型。借助此工具， 你可以直接在终端中简化标志工作流。

安装

将 CLI 作为开发依赖项安装到你的项目中：

# npm
npm install --save-dev @reflag/cli

# yarn
yarn add --dev @reflag/cli

从项目的根目录运行 new 命令，一步初始化 CLI、创建标志并生成 TypeScript 类型：

# npm
npx reflag new

# yarn
yarn reflag new

从 Bucket SDK 迁移

如果你正在从 Bucket CLI 迁移，以下是需要注意的关键变化：

• 命令名称：从 bucket 改为 reflag
• 类型定义文件：从 features.d.ts 重命名为 flags.d.ts（如果旧文件已提交，请手动删除）
• 身份验证文件：从 .bucket-auth 改为 .reflag-auth（重命名或删除旧文件）
• 配置文件：从 bucket.config.json 改为 reflag.config.json（重命名或删除旧文件）
• 命令：features 命令现在为 flags
• 环境变量：使用 REFLAG_API_KEY 代替 BUCKET_API_KEY

重要：请更新你的脚本、构建步骤和 .gitignore 模式以反映这些变化。

单独命令

如需更多控制，你可以单独运行每个命令：

# Initialize Reflag in your project (if not already setup)
npx reflag init

# Create a new flag
npx reflag flags create "My Flag"

# Generate TypeScript types for your flags
npx reflag flags types

配置

当你运行 reflag init 时，CLI 会在你的项目目录中创建一个 reflag.config.json 文件。该文件包含 Reflag 集成所需的所有设置。

配置文件结构

以下是 reflag.config.json 文件中所有可用的配置选项：

{
  "$schema": "https://unpkg.com/@reflag/cli@latest/schema.json",
  "baseUrl": "https://app.reflag.com",
  "apiUrl": "https://app.reflag.com/api",
  "appId": "ap123456789",
  "typesOutput": [
    {
      "path": "gen/flags.d.ts",
      "format": "react"
    }
  ]
}

选项	描述	默认值
$schema	配置的自动补全。latest 可以替换为特定版本。	"https://unpkg.com/@reflag/cli@latest/schema.json"
baseUrl	Reflag 服务的基础 URL。	"https://app.reflag.com"
apiUrl	Reflag 服务的 API URL（为 API 调用覆盖 baseUrl）。	"https://app.reflag.com/api"
appId	你的 Reflag 应用程序 ID。	必需
typesOutput	将生成 TypeScript 类型的路径。可以是字符串或包含 path 和 format 属性的对象数组。可用格式：react 和 node。	"gen/flags.ts"，格式为 "react"

你可以使用单个命令的命令行选项覆盖这些设置。

命令

reflag init

在你的项目中初始化新的 Reflag 配置。这将创建一个包含你的设置的 reflag.config.json 文件，并提示输入任何未通过选项提供的必需信息。

npx reflag init [--overwrite]

选项：

• --overwrite：如果存在现有配置文件，则覆盖它。
• --app-id <id>：设置应用程序 ID。
• --key-format <format>：设置标志的键格式。

reflag new [flagName]

一体化命令，帮助你快速上手。该命令将 init、flag 创建和类型生成合并为一步。使用它可最快地开始使用 Reflag。

npx reflag new "My Flag" [--app-id ap123456789] [--key my-flag]  [--key-format custom] [--out gen/flags.ts] [--format react]

选项：

• --key：flag 的特定 key。
• --app-id：要使用的 App ID。
• --key-format：flag key 的格式（custom、snake、camel 等）。
• --out：生成 TypeScript 类型的路径。
• --format：生成类型的格式（react 或 node）。

如果你希望对每个步骤有更多控制，可以改用单独的命令（init、flags create、flags types）。

reflag login

使用你的 Reflag 账户进行身份验证。这会安全地存储你的凭据，供后续操作使用。

npx reflag login

reflag logout

退出你的 Reflag 账户并移除已存储的凭据。

npx reflag logout

reflag flags

使用以下子命令管理你的 Reflag flag：

reflag flags create [flagName]

在你的 Reflag 应用中创建一个新 flag。如果未提供选项，该命令会通过交互式提示引导你完成 flag 创建过程。

npx reflag flags create "My Flag" [--app-id ap123456789] [--key my-flag] [--key-format custom]

选项：

• --key：flag 的特定 key。
• --app-id：要使用的 App ID。
• --key-format：flag key 的格式。

reflag flags list

列出当前应用的所有 flag。这有助于你可视化了解有哪些 flag 可用及其当前配置。

npx reflag flags list [--app-id ap123456789]

选项：

• --app-id：要使用的 App ID。

reflag flags types

为你的 flag 生成 TypeScript 类型。这可确保在 TypeScript/JavaScript 应用中使用 Reflag flag 时的类型安全。

npx reflag flags types [--app-id ap123456789] [--out gen/flags.ts] [--format react]

选项：

• --app-id：要使用的 App ID。
• --out：生成 TypeScript 类型的路径。
• --format：生成类型的格式（react 或 node）。

reflag apps

用于管理 Reflag 应用的命令。

全局选项

这些选项可用于任何命令：

• --debug：启用调试模式以输出详细日志。
• --base-url <url>：设置 Reflag API 的基础 URL。
• --api-url <url>：直接设置 API URL（覆盖基础 URL）。
• --api-key <key>：用于非交互式身份验证的 Reflag API key。
• --help：显示命令的帮助信息。

AI 辅助开发

Reflag 通过规则和 Model Context Protocol（MCP）提供强大的 AI 辅助开发能力。这些功能可帮助你的 AI 开发工具更好地理解你的 flag，并提供更准确的辅助。

Reflag 规则（推荐）

rules 命令可帮助你为项目设置 AI 专用规则。这些规则使 AI 工具能够更好地理解如何使用 Reflag flag，以及它们应如何在你的代码库中使用。

npx reflag rules [--format <cursor|copilot>] [--yes]

选项：

• --format：添加规则的格式：
  • cursor：将规则添加到 .cursor/rules/reflag.mdc，用于 Cursor IDE 集成。
  • copilot：将规则添加到 .github/copilot-instructions.md，用于 GitHub Copilot 集成。
• --yes：跳过确认提示，并直接覆盖现有文件而不询问。

该命令会向你的项目添加规则，为 AI 工具提供有关如何设置和使用 Reflag flag 的上下文。对于 copilot 格式，规则会添加到文件中的专用部分，让你可以在 Reflag 规则之外维护其他 copilot 指令。

Model Context Protocol

Model Context Protocol（MCP）是一种开放协议，提供了一种标准化方式，将 AI 模型连接到不同的数据源和工具。在 Reflag 的语境中，MCP 使你的代码编辑器能够理解你的 flag、它们的状态以及它们在你的代码库中的关系。这在你的 flag 管理工作流与 AI 驱动的开发工具之间建立了无缝桥梁。MCP 服务由 Reflag 托管，因此很容易开始使用。

**注意：Reflag mcp 命令行命令以前用于 _本地 服务。然而，在最近版本的 Reflag 命令行中，mcp 命令已被重新用途，用于帮助你连接到新的远程 MCP 服务。**_

设置 MCP

mcp 命令可帮助你配置编辑器或 AI 客户端，使其连接到 Reflag 的远程 MCP 服务。这样你的 AI 工具就能理解你的功能开关并提供更具上下文感知的协助。

npx reflag mcp [--editor <editor>] [--scope <local|global>]

选项：

• --editor：要配置的编辑器/客户端：
  • cursor：Cursor IDE
  • vscode：Visual Studio Code
  • claude：Claude Desktop
  • windsurf：Windsurf
• --scope：是全局配置还是为项目进行本地配置。

该命令将引导你完成以下步骤：

1. 选择要配置的编辑器/客户端。
2. 选择要连接到哪个 Reflag 应用。
3. 决定使用全局配置还是项目本地配置。
4. 为你选择的编辑器设置相应的配置文件。

注意：该设置使用 mcp-remote 作为兼容层，使远程托管的 Reflag MCP 服务能够与所有支持 MCP STDIO 服务的编辑器/客户端配合使用。如果你的编辑器/客户端支持带 OAuth 的 HTTP Streaming，则可以直接连接到 Reflag MCP 服务。

在 CI/CD 流水线中使用

Reflag CLI 专为在 CI/CD 流水线中无缝运行而设计。对于无法进行交互式登录的自动化环境，请使用 --api-key 选项，或在 REFLAG_API_KEY 环境变量中指定 API 密钥。

# Generate types in CI/CD
npx reflag apps list --api-key $REFLAG_API_KEY

重要限制：

• 使用 --api-key 时，login 和 logout 命令将被禁用
• API 密钥会绕过所有交互式身份验证流程
• API 密钥仅绑定到一个应用。诸如 apps list 之类的命令只会返回绑定的应用
• 使用你的 CI/CD 平台的密钥管理功能安全地存储 API 密钥

CI 工作流示例：

# GitHub Actions example
- name: Generate types
  run: npx reflag flags types --api-key ${{ secrets.REFLAG_API_KEY }}

# GitHub Actions example (using environment):
- name: Generate types (environment)
  run: npx reflag flags types
  env:
    REFLAG_API_KEY: ${{ secrets.REFLAG_CI_API_KEY }}

开发

# Build the CLI
yarn build

# Run the CLI locally
yarn reflag [command]

# Lint and format code
yarn lint
yarn format

要求

• Node.js >=18.0.0

许可证

MIT License Copyright (c) 2025 Bucket ApS