Bucket MCP Server

chính thức

Sử dụng Bucket để gắn cờ tính năng, quản lý dữ liệu công ty và kiểm soát quyền truy cập tính năng.

GitHub
23

Tài liệu

Reflag CLI

Giao diện dòng lệnh để tương tác với các dịch vụ Reflag. CLI cho phép bạn quản lý ứng dụng, cờ, xác thực và tạo kiểu TypeScript cho các cờ Reflag của bạn. Với công cụ này, bạn có thể hợp lý hóa quy trình làm việc với cờ trực tiếp từ terminal của mình.

Cài đặt

Cài đặt CLI như một phụ thuộc phát triển trong dự án của bạn:

npm

npm install --save-dev @reflag/cli

yarn

yarn add --dev @reflag/cli

Chạy lệnh new từ thư mục gốc của dự án để khởi tạo CLI, tạo một cờ và tạo kiểu TypeScript trong một bước duy nhất:

npm

npx reflag new

yarn

yarn reflag new

Di chuyển từ Bucket SDK

Nếu bạn đang di chuyển từ Bucket CLI, đây là những thay đổi chính cần lưu ý:

  • Tên lệnh: Đổi từ bucket thành reflag
  • Tệp định nghĩa kiểu: Đổi tên từ features.d.ts thành flags.d.ts (xóa thủ công tệp cũ nếu nó đã được commit)
  • Tệp xác thực: Đổi từ .bucket-auth thành .reflag-auth (đổi tên hoặc xóa tệp cũ)
  • Tệp cấu hình: Đổi từ bucket.config.json thành reflag.config.json (đổi tên hoặc xóa tệp cũ)
  • Lệnh: Lệnh features giờ là flags
  • Biến môi trường: Sử dụng REFLAG_API_KEY thay vì BUCKET_API_KEY

Quan trọng: Cập nhật các tập lệnh, bước build và mẫu .gitignore của bạn để phản ánh những thay đổi này.

Các lệnh riêng lẻ

Để kiểm soát nhiều hơn, bạn có thể chạy từng lệnh riêng lẻ:

Khởi tạo Reflag trong dự án của bạn (nếu chưa được thiết lập)

npx reflag init

Tạo một cờ mới

npx reflag flags create "My Flag"

Tạo kiểu TypeScript cho các cờ của bạn

npx reflag flags types

Cấu hình

CLI tạo một tệp reflag.config.json trong thư mục dự án của bạn khi bạn chạy reflag init. Tệp này chứa tất cả các cài đặt cần thiết cho tích hợp Reflag của bạn.

Cấu trúc tệp cấu hình

Dưới đây là tất cả các tùy chọn cấu hình có sẵn trong tệp 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" } ] }

Tùy chọnMô tảMặc định
$schemaTự động hoàn thành cho cấu hình. latest có thể được thay thế bằng một phiên bản cụ thể."https://unpkg.com/@reflag/cli@latest/schema.json"
baseUrlURL cơ sở cho các dịch vụ Reflag."https://app.reflag.com"
apiUrlURL API cho các dịch vụ Reflag (ghi đè baseUrl cho các lệnh gọi API)."https://app.reflag.com/api"
appIdID ứng dụng Reflag của bạn.Bắt buộc
typesOutput(Các) đường dẫn nơi kiểu TypeScript sẽ được tạo. Có thể là một chuỗi hoặc một mảng các đối tượng với thuộc tính path và format. Các định dạng có sẵn: react và node."gen/flags.ts" với định dạng "react"

Bạn có thể ghi đè các cài đặt này bằng các tùy chọn dòng lệnh cho từng lệnh riêng lẻ.

Các lệnh

reflag init

Khởi tạo cấu hình Reflag mới trong dự án của bạn. Điều này tạo một tệp reflag.config.json với các cài đặt của bạn và nhắc nhở bất kỳ thông tin cần thiết nào không được cung cấp qua các tùy chọn.

npx reflag init [--overwrite]

Các tùy chọn:

  • --overwrite: Ghi đè tệp cấu hình hiện có nếu tồn tại.
  • --app-id <id>: Đặt ID ứng dụng.
  • --key-format <format>: Đặt định dạng khóa cho các cờ.

reflag new [flagName]

Lệnh tất cả trong một để bắt đầu nhanh chóng. Lệnh này kết hợp init, tạo cờ và tạo kiểu trong một bước duy nhất. Sử dụng lệnh này để có cách nhanh nhất để bắt đầu và chạy với Reflag.

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

Các tùy chọn:

  • --key: Khóa cụ thể cho cờ.
  • --app-id: ID ứng dụng để sử dụng.
  • --key-format: Định dạng cho các khóa cờ (custom, snake, camel, v.v.).
  • --out: Đường dẫn để tạo kiểu TypeScript.
  • --format: Định dạng của các kiểu được tạo (react hoặc node).

Nếu bạn muốn kiểm soát nhiều hơn từng bước, bạn có thể sử dụng các lệnh riêng lẻ (init, flags create, flags types) thay thế.

reflag login

Xác thực với tài khoản Reflag của bạn. Điều này lưu trữ thông tin đăng nhập của bạn một cách an toàn cho các hoạt động tiếp theo.

npx reflag login

reflag logout

Đăng xuất khỏi tài khoản Reflag của bạn và xóa thông tin đăng nhập đã lưu trữ.

npx reflag logout

reflag flags

Quản lý các cờ Reflag của bạn với các lệnh con sau:

reflag flags create [flagName]

Tạo một cờ mới trong ứng dụng Reflag của bạn. Lệnh hướng dẫn bạn qua quá trình tạo cờ với các lời nhắc tương tác nếu các tùy chọn không được cung cấp.

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

Các tùy chọn:

  • --key: Khóa cụ thể cho cờ.
  • --app-id: ID ứng dụng để sử dụng.
  • --key-format: Định dạng cho các khóa cờ.

reflag flags list

Liệt kê tất cả các cờ cho ứng dụng hiện tại. Điều này giúp bạn hình dung những cờ nào có sẵn và cấu hình hiện tại của chúng.

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

Các tùy chọn:

  • --app-id: ID ứng dụng để sử dụng.

reflag flags types

Tạo kiểu TypeScript cho các cờ của bạn. Điều này đảm bảo an toàn kiểu khi sử dụng cờ Reflag trong các ứng dụng TypeScript/JavaScript của bạn.

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

Các tùy chọn:

  • --app-id: ID ứng dụng để sử dụng.
  • --out: Đường dẫn để tạo kiểu TypeScript.
  • --format: Định dạng của các kiểu được tạo (react hoặc node).

reflag apps

Các lệnh để quản lý ứng dụng Reflag.

Tùy chọn toàn cục

Các tùy chọn này có thể được sử dụng với bất kỳ lệnh nào:

  • --debug: Bật chế độ gỡ lỗi để có đầu ra chi tiết.
  • --base-url <url>: Đặt URL cơ sở cho API Reflag.
  • --api-url <url>: Đặt URL API trực tiếp (ghi đè URL cơ sở).
  • --api-key <key>: Khóa API Reflag để xác thực không tương tác.
  • --help: Hiển thị thông tin trợ giúp cho một lệnh.

Phát triển hỗ trợ bởi AI

Reflag cung cấp các khả năng phát triển hỗ trợ bởi AI mạnh mẽ thông qua các quy tắc và Model Context Protocol (MCP). Những tính năng này giúp các công cụ phát triển AI của bạn hiểu rõ hơn về các cờ của bạn và cung cấp hỗ trợ chính xác hơn.

Quy tắc Reflag (Khuyến nghị)

Lệnh rules giúp bạn thiết lập các quy tắc cụ thể cho AI trong dự án của bạn. Những quy tắc này cho phép các công cụ AI hiểu rõ hơn cách làm việc với cờ Reflag và cách chúng nên được sử dụng trong cơ sở mã của bạn.

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

Các tùy chọn:

  • --format: Định dạng để thêm quy tắc:
    • cursor: Thêm quy tắc vào .cursor/rules/reflag.mdc để tích hợp Cursor IDE.
    • copilot: Thêm quy tắc vào .github/copilot-instructions.md để tích hợp GitHub Copilot.
  • --yes: Bỏ qua các lời nhắc xác nhận và ghi đè các tệp hiện có mà không hỏi.

Lệnh này thêm các quy tắc vào dự án của bạn, cung cấp cho các công cụ AI ngữ cảnh về cách thiết lập và sử dụng cờ Reflag. Đối với định dạng copilot, các quy tắc được thêm vào một phần dành riêng trong tệp, cho phép bạn duy trì các hướng dẫn copilot khác cùng với các quy tắc của Reflag.

Model Context Protocol

Model Context Protocol (MCP) là một giao thức mở cung cấp một cách tiêu chuẩn hóa để kết nối các mô hình AI với các nguồn dữ liệu và công cụ khác nhau. Trong bối cảnh của Reflag, MCP cho phép trình soạn thảo mã của bạn hiểu các cờ của bạn, trạng thái của chúng và mối quan hệ của chúng trong cơ sở mã của bạn. Điều này tạo ra một cầu nối liền mạch giữa quy trình quản lý cờ của bạn và các công cụ phát triển hỗ trợ bởi AI. Máy chủ MCP được lưu trữ bởi Reflag, giúp bạn dễ dàng bắt đầu.

**Lưu ý: Lệnh CLI mcp của Reflag trước đây được sử dụng cho một máy chủ cục bộ. Tuy nhiên, trong các phiên bản gần đây của Reflag CLI, lệnh mcp đã được tái sử dụng để giúp bạn kết nối với máy chủ MCP từ xa mới.**

Thiết lập MCP

Lệnh mcp giúp bạn cấu hình trình soạn thảo hoặc máy khách AI của mình để kết nối với máy chủ MCP từ xa của Reflag. Điều này cho phép các công cụ AI của bạn hiểu các cờ của bạn và cung cấp hỗ trợ theo ngữ cảnh hơn.

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

Các tùy chọn:

  • --editor: Trình soạn thảo/máy khách để cấu hình:
    • cursor: Cursor IDE
    • vscode: Visual Studio Code
    • claude: Claude Desktop
    • windsurf: Windsurf
  • --scope: Cấu hình cài đặt toàn cục hay cục bộ cho dự án.

Lệnh sẽ hướng dẫn bạn qua:

  1. Chọn trình soạn thảo/máy khách nào để cấu hình.
  2. Chọn ứng dụng Reflag nào để kết nối.
  3. Quyết định giữa cấu hình toàn cục hay cục bộ cho dự án.
  4. Thiết lập tệp cấu hình phù hợp cho trình soạn thảo đã chọn của bạn.

Lưu ý: Thiết lập sử dụng mcp-remote như một lớp tương thích cho phép máy chủ MCP từ xa được lưu trữ bởi Reflag hoạt động với tất cả các trình soạn thảo/máy khách hỗ trợ máy chủ MCP STDIO. Nếu trình soạn thảo/máy khách của bạn hỗ trợ HTTP Streaming với OAuth, bạn có thể kết nối trực tiếp với máy chủ MCP của Reflag.

Sử dụng trong pipeline CI/CD (Beta)

Reflag CLI được thiết kế để hoạt động liền mạch trong các pipeline CI/CD. Đối với các môi trường tự động nơi đăng nhập tương tác không thể thực hiện được, hãy sử dụng tùy chọn --api-key hoặc chỉ định khóa API trong biến môi trường REFLAG_API_KEY.

Tạo kiểu trong CI/CD

npx reflag apps list --api-key $REFLAG_API_KEY

Các hạn chế quan trọng:

  • Khi sử dụng --api-key, các lệnh login và logout bị vô hiệu hóa
  • Khóa API bỏ qua tất cả các luồng xác thực tương tác
  • Khóa API chỉ bị ràng buộc với một ứng dụng. Các lệnh như apps list sẽ chỉ trả về ứng dụng bị ràng buộc
  • Lưu trữ khóa API một cách an toàn bằng cách sử dụng quản lý bí mật của nền tảng CI/CD của bạn

Ví dụ về quy trình CI:

Ví dụ GitHub Actions

  • name: Generate types run: npx reflag flags types --api-key ${{ secrets.REFLAG_API_KEY }}

Ví dụ GitHub Actions (sử dụng environment):

  • name: Generate types (environment) run: npx reflag flags types env: REFLAG_API_KEY: ${{ secrets.REFLAG_CI_API_KEY }}

Phát triển

Build CLI

yarn build

Chạy CLI cục bộ

yarn reflag [command]

Lint và định dạng mã

yarn lint yarn format

Yêu cầu

  • Node.js >=18.0.0

Giấy phép

Giấy phép MIT Bản quyền (c) 2025 Bucket ApS