Unleash

chính thức

Máy chủ MCP để quản lý các cờ tính năng Unleash và tự động hóa các phương pháp tốt nhất.

GitHub
21
Dùng thử MCP nàyĐược tài trợ

Bạn có thể làm gì với Unleash MCP?

  • Đánh giá rủi ro thay đổi — Yêu cầu trợ lý chạy evaluate_change trên một thay đổi mã để nhận điểm rủi ro và khuyến nghị gắn cờ.
  • Tạo cờ tính năng — Sử dụng create_flag để cấp phát một cờ mới với loại, mô tả và nhắm mục tiêu dự án.
  • Phát hiện cờ hiện có — Gọi detect_flag để tìm các cờ có thể tái sử dụng và tránh trùng lặp trước khi tạo cờ mới.
  • Nhận hướng dẫn bọc — Yêu cầu wrap_change để lấy các đoạn mã cụ thể theo ngôn ngữ nhằm triển khai cờ một cách an toàn.
  • Quản lý triển khai và trạng thái — Sử dụng set_flag_rollout và toggle_flag_environment để cấu hình và kích hoạt triển khai dần dần.
  • Kiểm tra và dọn dẹp — Truy vấn get_flag_state hoặc list_flags để kiểm toán cờ, sau đó dùng cleanup_flag để nhận hướng dẫn gỡ bỏ.

Tài liệu

Máy chủ MCP Unleash

Máy chủ Model Context Protocol (MCP) chuyên dụng để quản lý cờ tính năng Unleash. Máy chủ này cho phép các trợ lý mã hóa hỗ trợ bởi LLM tạo và quản lý cờ tính năng theo các phương pháp tốt nhất của Unleash.

Để chia sẻ phản hồi, hãy tham gia Slack cộng đồng của chúng tôi hoặc mở một vấn đề trên GitHub.

Tổng quan

Máy chủ MCP này cung cấp các công cụ tích hợp với Unleash Admin API, cho phép các trợ lý mã hóa AI:

  • Tạo cờ tính năng với kiểm tra và phân loại hợp lệ.
  • Phát hiện cờ hiện có để ngăn trùng lặp hoặc khuyến khích tái sử dụng.
  • Đánh giá thay đổi để quyết định khi nào cần cờ tính năng.
  • Truyền phát tiến trình để hiển thị trong quá trình thao tác.
  • Xử lý lỗi một cách khéo léo với các gợi ý hữu ích.
  • Báo cáo vấn đề với MCP cho Unleash thông qua send_feedback, chỉ sau khi người dùng đồng ý.
  • Tuân theo các phương pháp tốt nhất từ tài liệu Unleash.

Các công cụ có sẵn

Máy chủ MCP cung cấp các công cụ sau:

  • create_flag: Tạo cờ tính năng trong Unleash.
  • evaluate_change: Chấm điểm rủi ro và đề xuất việc sử dụng cờ tính năng.
  • detect_flag: Khám phá các cờ tính năng hiện có để tránh trùng lặp.
  • wrap_change: Cung cấp hướng dẫn về cách bọc một thay đổi trong cờ tính năng.
  • set_flag_rollout: Cấu hình chiến lược triển khai cho cờ tính năng (không bật cờ).
  • get_flag_state: Hiển thị siêu dữ liệu của cờ tính năng và các chiến lược kích hoạt của nó.
  • list_flags: Liệt kê tất cả cờ tính năng trong một dự án, với phân trang và thứ tự sắp xếp tùy chọn.
  • list_projects: Liệt kê các dự án Unleash có sẵn cho token đã cấu hình, với phân trang tùy chọn.
  • toggle_flag_environment: Bật hoặc tắt cờ tính năng trong một môi trường.
  • remove_flag_strategy: Xóa chiến lược của cờ tính năng khỏi một môi trường.
  • cleanup_flag: Tạo hướng dẫn để loại bỏ an toàn các đường dẫn mã được gắn cờ.
  • send_feedback: Báo cáo một lệnh gọi công cụ thất bại, một yêu cầu không được hỗ trợ hoặc một kết quả bất ngờ cho Unleash để cải thiện MCP. Yêu cầu sự đồng ý của người dùng.

Quy trình làm việc cốt lõi

Quy trình làm việc cốt lõi cho trợ lý AI được thiết kế như sau:

  1. evaluate_change: Đầu tiên, đánh giá một thay đổi mã để xem có cần cờ hay không.
  2. detect_flag: Công cụ này thường được gọi tự động bởi evaluate_change để ngăn việc tạo cờ trùng lặp.
  3. create_flag: Nếu cần một cờ mới, công cụ này sẽ tạo nó trong Unleash.
  4. wrap_change: Cuối cùng, công cụ này cung cấp mã theo ngôn ngữ cụ thể để triển khai cờ mới.

Xem thêm thông tin về các công cụ quy trình làm việc cốt lõi trong phần Tham chiếu công cụ.

Điều kiện tiên quyết

Trước khi bạn có thể chạy máy chủ, bạn cần có:

  • Node.js 22 trở lên
  • Trình quản lý gói pnpm hoặc npm
  • Một phiên bản Unleash (được lưu trữ hoặc tự lưu trữ)
  • Một mã thông báo truy cập cá nhân có quyền tạo cờ tính năng

Bắt đầu

Phần này bao gồm các cách khác nhau để cài đặt và chạy máy chủ MCP Unleash. Bạn có thể làm theo thiết lập cho tác nhân (chẳng hạn như Claude Code và Codex), chạy MCP như một quy trình độc lập bằng npx, hoặc sử dụng thiết lập phát triển cục bộ.

Thiết lập tác nhân

Bạn có thể thêm máy chủ MCP trực tiếp vào Claude Code hoặc Codex. Cấu hình tác nhân phụ thuộc vào đường dẫn. Bạn phải chạy lệnh sau từ thư mục gốc của dự án nơi bạn muốn sử dụng MCP.

Đối với 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

Đối với 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

Thiết lập tác nhân từ xa (thử nghiệm)

Thay vì chạy máy chủ MCP cục bộ, bạn có thể kết nối trực tiếp đến máy chủ MCP từ xa tích hợp sẵn của phiên bản Unleash của bạn qua HTTP. Điều này sử dụng Streamable HTTP transport — không cần quy trình cục bộ.

Lưu ý: MCP từ xa là một tính năng thử nghiệm phải được bật trên phiên bản Unleash của bạn. Liên hệ với nhóm Unleash để được bật tính năng này.

OAuth

Luồng OAuth mở trình duyệt của bạn, cho phép bạn đăng nhập vào Unleash và tự động cấp một PAT ngắn hạn. Không cần quản lý token thủ công.

Đối với Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

Đối với Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

Khi sử dụng lần đầu, máy khách sẽ tự động mở trình duyệt của bạn để đăng nhập. Sau khi xác thực với Unleash, một PAT được tạo và sử dụng cho tất cả các yêu cầu tiếp theo.

PAT hết hạn sau 24 giờ theo mặc định.

Mã thông báo truy cập cá nhân (PAT)

Sử dụng phương pháp này khi bạn đã có PAT hoặc cần truy cập không tương tác/không có giao diện (đường ống CI, môi trường phát triển dùng chung, máy khách không hỗ trợ OAuth).

Để tạo PAT: đăng nhập vào phiên bản Unleash của bạn, đi tới Hồ sơ > Mã thông báo truy cập cá nhân và tạo một token mới.

Đối với Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

Đối với Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

Cờ --header gửi PAT trực tiếp, bỏ qua hoàn toàn luồng OAuth.

Khởi động nhanh với npx

Bạn có thể chạy máy chủ MCP như một quy trình độc lập mà không cần sao chép kho lưu trữ bằng npx. Cung cấp cấu hình thông qua các biến môi trường hoặc tệp .env cục bộ trong thư mục nơi bạn chạy lệnh:

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 hỗ trợ các cờ giống như bản dựng cục bộ (ví dụ: --dry-run, --log-level).

Thiết lập phát triển cục bộ

Làm theo các bước sau để thiết lập dự án cho phát triển cục bộ.

  1. Cài đặt phụ thuộc

Sao chép kho lưu trữ và cài đặt phụ thuộc bằng pnpm. Corepack giữ mọi người ở cùng phiên bản 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 pnpm@11.0.8 --activate

pnpm install
  1. Chạy ở chế độ phát triển trực tiếp từ Claude hoặc Codex

Tránh đầu ra npm run và biểu ngữ tsx watch vì bất kỳ stdout bổ sung nào sẽ phá vỡ quá trình bắt tay MCP. Hai tùy chọn yên tĩnh:

A) Sử dụng JS đã biên dịch (đáng tin cậy nhất)

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) Sử dụng TypeScript trực tiếp (không cần biên dịch)

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"

Ghi chú:

  • node --import tsx yên tĩnh (không có đầu ra vòng đời npm) và chạy TS trực tiếp; sử dụng điều này khi bạn muốn tránh biên dịch.
  • node dist/index.js là lựa chọn an toàn nhất; kết hợp với npm run build:watch để biên dịch lại khi có thay đổi trong khi lệnh tác nhân vẫn ổn định.
  • Nhật ký nằm trong thư mục gốc của kho lưu trữ (app.log, mcp-stdio.log), cả hai đều được gitignore.

Kiểm soát ghi nhật ký

  • LOG_LEVEL (ưu tiên): kiểm soát mức độ chi tiết ghi nhật ký ứng dụng (debug, info, warn, error). Mặc định là error khi không được đặt.
  • Cờ CLI --log-level: ghi đè tùy chọn cho LOG_LEVEL khi bạn muốn thay đổi một lần.
  • APP_LOG_FILE (tùy chọn): nếu được đặt, nhật ký ứng dụng được ghi vào tệp này (không phải stdout). Nếu không được đặt, nhật ký sẽ đi đến stderr.
  • MCP_STDIO_LOG_FILE (tùy chọn): nếu được đặt, MCP stdin/stdout/stderr được ghi vào tệp duy nhất này với tiền tố kênh. Các thông điệp giao thức vẫn truyền qua stdout bình thường.

Ghi nhận máy khách

Khi một máy khách MCP gửi clientInfo trong quá trình khởi tạo (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro và các máy khách tuân thủ khác), máy chủ làm phong phú tiêu đề User-Agent trên các lệnh gọi API Unleash Admin đi ra:

User-Agent: unleash-mcp/<version> (MCP Server; client=claude-code/1.2.3)

Điều này làm cho nhật ký sự kiện Unleash trả lời "công cụ AI nào đã tạo hoặc chuyển đổi cờ này" mà không cần thay đổi phía máy chủ. Các giá trị ghi nhận được làm sạch để chúng không thể phá vỡ tiêu đề User-Agent.

Đặt UNLEASH_MCP_CLIENT_ATTRIBUTION=off để tắt làm phong phú và quay lại unleash-mcp/<version> (MCP Server). Mặc định: được bật.

Tham chiếu công cụ

Phần này mô tả chi tiết từng công cụ cốt lõi, bao gồm mục đích, tham số và đầu ra của nó.

Tạo cờ

Công cụ create_flag tạo một cờ tính năng mới trong Unleash với xác thực toàn diện và theo dõi tiến trình.

Khi nào sử dụng

Sử dụng công cụ này khi bạn đã xác định rằng cần một cờ tính năng (ví dụ: sau khi chạy evaluate_change) và bạn đã sẵn sàng tạo nó với loại và siêu dữ liệu chính xác.

Tham số

Công cụ chấp nhận các tham số sau:

  • name (bắt buộc): Tên cờ tính năng duy nhất trong dự án.
  • type (bắt buộc): Loại cờ tính năng cho biết vòng đời và mục đích.
    • release: Triển khai tính năng dần dần cho người dùng.
    • experiment: Kiểm tra A/B và thử nghiệm.
    • operational: Hành vi hệ thống và công tắc vận hành.
    • kill-switch: Tắt khẩn cấp hoặc bộ ngắt mạch.
    • permission: Kiểm soát quyền truy cập tính năng dựa trên vai trò hoặc quyền của người dùng.
  • description (bắt buộc): Giải thích rõ ràng về những gì cờ kiểm soát và tại sao nó tồn tại.
  • projectId (tùy chọn): Dự án mục tiêu (mặc định là UNLEASH_DEFAULT_PROJECT).
  • impressionData (tùy chọn): Bật theo dõi phân tích (mặc định là false).

Ví dụ sử dụng

Lời nhắc tác nhân

Use create_flag with:
- name: "new-checkout-flow"
- type: "release"
- description: "Gradual rollout of the redesigned checkout experience"
- projectId: "ecommerce"

Tải trọng công cụ

{
  "name": "new-checkout-flow",
  "type": "release",
  "description": "Gradual rollout of the redesigned checkout experience with improved conversion tracking",
  "projectId": "ecommerce",
  "impressionData": true
}

Đầu ra công cụ

Khi thành công, công cụ trả về một đối tượng JSON chứa URL của cờ tính năng mới trong giao diện quản trị Unleash, một liên kết tài nguyên MCP để truy cập theo chương trình, dấu thời gian tạo và chi tiết cấu hình.

Đánh giá thay đổi

Công cụ evaluate_change đánh giá xem một thay đổi mã có nên được đặt sau cờ tính năng hay không. Nó kiểm tra cấu trúc, bối cảnh và rủi ro tiềm ẩn của thay đổi và trả về khuyến nghị kèm giải thích và các bước tiếp theo.

Khi nào sử dụng

Sử dụng evaluate_change ở đầu một tính năng hoặc sửa đổi khi bạn muốn hiểu liệu công việc có yêu cầu cờ tính năng hay không. Công cụ này cũng hữu ích khi bạn không chắc chắn nên sử dụng loại cờ nào hoặc muốn hướng dẫn về kế hoạch triển khai.

Cách hoạt động

Công cụ trả về hướng dẫn chi tiết, được định dạng markdown cho trợ lý LLM dựa trên các phương pháp tốt nhất của Unleash.

Hướng dẫn bao gồm:

  • Phát hiện cờ cha: Kiểm tra xem mã đã được bảo vệ bởi các cờ hiện có hay chưa.
  • Đánh giá rủi ro: Phân tích các mẫu mã để xác định các thao tác rủi ro.
  • Đánh giá loại mã: Phân loại thay đổi (ví dụ: kiểm thử, cấu hình, tính năng hoặc sửa lỗi).
  • Khuyến nghị: Đề xuất tạo cờ, sử dụng cờ hiện có hoặc bỏ qua cờ.
  • Hành động tiếp theo: Cung cấp hướng dẫn cụ thể về việc cần làm tiếp theo.

Khi evaluate_change xác định cần một cờ, nó cung cấp hướng dẫn rõ ràng để:

  1. Gọi công cụ create_flag để tạo cờ tính năng.
  2. Gọi công cụ wrap_change để nhận hướng dẫn bọc mã theo ngôn ngữ cụ thể.
  3. Triển khai mã được bọc theo các mẫu đã phát hiện.

Quy trình đánh giá

Công cụ tuân theo một quy trình đánh giá rõ ràng:

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)

Đánh giá rủi ro

Công cụ sử dụng các mẫu không phụ thuộc ngôn ngữ để chấm điểm rủi ro:

  • Rủi ro nghiêm trọng (Điểm +5): Ví dụ: xác thực, thanh toán, bảo mật và thao tác cơ sở dữ liệu.
  • Rủi ro cao (Điểm +3): Ví dụ: thay đổi API, dịch vụ bên ngoài hoặc lớp mới.
  • Rủi ro trung bình (Điểm +2): Ví dụ: thao tác không đồng bộ hoặc quản lý trạng thái.
  • Rủi ro thấp (Điểm +1): Ví dụ: sửa lỗi, tái cấu trúc hoặc thay đổi nhỏ.

Điểm tích lũy qua các danh mục khớp. Tổng ánh xạ đến mức rủi ro:

  • Nghiêm trọng: Điểm ≥ 5
  • Cao: Điểm ≥ 3
  • Trung bình: Điểm ≥ 2
  • Thấp: Điểm < 2

Đầu ra bao gồm điểm confidence (0-1) đại diện cho mức độ chắc chắn tự đánh giá của LLM, tăng lên khi có nhiều bối cảnh hơn được cung cấp.

Một danh mục loại trừ bao gồm các tệp không cần cờ tính năng bất kể nội dung: tệp kiểm thử (*.test.ts, *_test.go, v.v.), tệp cấu hình (*.config.js, .env, *.yaml) và tệp tài liệu (*.md, docs/**). Các thay đổi chỉ giới hạn trong các tệp bị loại trừ sẽ không kích hoạt khuyến nghị cờ.

Các định nghĩa mẫu đầy đủ, bao gồm từ khóa theo danh mục, mẫu tệp, mẫu mã và lý do, nằm trong src/evaluation/riskPatterns.ts.

Phát hiện cờ cha

Công cụ tìm kiếm các mẫu phổ biến trên các ngôn ngữ, chẳng hạn như:

  • Câu điều kiện: if (isEnabled('flag')), if client.is_enabled('flag'):
  • Phép gán: const enabled = useFlag('flag')
  • Hook: const enabled = useFlag('flag') → {enabled && <Component />}
  • Bộ bảo vệ: if (!isEnabled('flag')) return;
  • Trình bao bọc: withFeatureFlag('flag', () => {...})

Tham số

Tất cả các tham số đều không bắt buộc, nhưng càng nhiều ngữ cảnh thì khuyến nghị càng tốt:

  • repository (chuỗi): Tên hoặc đường dẫn kho lưu trữ.
  • branch (chuỗi): Tên nhánh hiện tại.
  • files (mảng): Danh sách các tệp đang được thay đổi.
  • description (chuỗi): Mô tả về thay đổi.
  • riskLevel (enum): low, medium, high, hoặc critical, theo đánh giá của người dùng.
  • codeContext (chuỗi): Mã xung quanh để phát hiện cờ cha.

Ví dụ sử dụng

Lời nhắc của tác nhân

Cách sử dụng đơn giản khi bạn để tác nhân thu thập ngữ cảnh:

Use evaluate_change to help me determine if I need a feature flag

Hướng dẫn tường minh:

Use evaluate_change with:
- description: "Add Stripe payment processing"
- riskLevel: "high"

Tải trọng công cụ

{
  "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"
}

Đầu ra công cụ

Trả về một đối tượng JSON với kết quả đánh giá, bao gồm một boolean needsFlag, một recommendation (ví dụ: "create_new"), tên cờ được đề xuất, mức độ rủi ro và một explanation chi tiết.

{
  "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
}

Phát hiện cờ

Công cụ detect_flag tìm các cờ tính năng hiện có trong mã nguồn để bạn có thể tái sử dụng chúng thay vì tạo bản sao trùng lặp. Công cụ này được tích hợp tự động vào quy trình evaluate_change nhưng cũng có thể được sử dụng thủ công.

Khi nào nên sử dụng

Sử dụng công cụ này trước khi tạo cờ tính năng mới hoặc trong quá trình đánh giá mã để kiểm tra các cờ hiện có có thể đã bao phủ trường hợp sử dụng của bạn. Điều này giúp ngăn chặn việc trùng lặp cờ.

Cách hoạt động

Công cụ trả về hướng dẫn tìm kiếm toàn diện và sử dụng nhiều chiến lược phát hiện:

  • Phát hiện dựa trên tệp: Tìm kiếm trong các tệp bạn đang sửa đổi để tìm cờ hiện có.
  • Phân tích lịch sử Git: Tìm các cờ được thêm gần đây trong lịch sử commit.
  • Khớp tên ngữ nghĩa: Khớp mô tả với tên cờ hiện có.
  • Phân tích ngữ cảnh mã: Kiểm tra mã xung quanh thay đổi.

Sau đó, công cụ thực hiện quy trình chấm điểm:

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

Mức độ tin cậy

Công cụ trả về các ứng viên với điểm tin cậy:

  • Cao ≥0.7: Khớp mạnh; nên tái sử dụng.
  • Trung bình 0.4-0.7: Có thể khớp; xem xét thủ công.
  • Thấp <0.4: Khớp yếu; có khả năng tạo cờ mới.

Tham số

  • description (bắt buộc): Mô tả về thay đổi hoặc tính năng. Ví dụ: "payment processing with Stripe", "new checkout flow".
  • files (không bắt buộc): Các tệp đang được sửa đổi. Ví dụ: ["src/payments/stripe.ts", "src/checkout/flow.ts"].
  • codeContext (không bắt buộc): Mã gần đó để quét tìm cờ.

Ví dụ sử dụng

Lời nhắc của tác nhân

Kiểm tra các cờ hiện có trước khi tạo cờ:

Use detect_flag with description "payment processing with Stripe"

Được tích hợp tự động trong đánh giá:

Use evaluate_change - automatically searches for existing flags

Tải trọng công cụ

{
  "description": "payment processing with Stripe",
  "files": ["src/payments/stripe.ts"]
}

Đầu ra công cụ

Trả về một đối tượng JSON cho biết có tìm thấy cờ hay không. Nếu flagFound là true, nó bao gồm một đối tượng candidate với tên cờ, vị trí, điểm tin cậy và lý do khớp.

Tìm thấy khớp:

{
  "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"
  }
}

Không tìm thấy khớp:

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

Bọc thay đổi

Công cụ wrap_change tạo các đoạn mã và hướng dẫn cụ thể theo ngôn ngữ để bọc mã bằng cờ tính năng. Nó giúp các LLM và nhà phát triển tuân theo các mẫu hiện có trong mã nguồn và sử dụng cờ một cách chính xác.

Khi nào nên sử dụng

Sử dụng công cụ này sau khi bạn đã tạo cờ tính năng (với create_flag) và cần triển khai nó trong mã của bạn. Nó đặc biệt hữu ích khi bạn muốn đảm bảo tuân theo các mẫu mã nguồn hiện có hoặc cần các ví dụ cụ thể theo framework (ví dụ: React, Django).

Cách hoạt động

Công cụ này là bước cuối cùng trong quy trình evaluate_change → create_flag → wrap_change.

Công cụ cung cấp các hướng dẫn sau trong phản hồi của nó:

  1. Hướng dẫn tìm kiếm: Hướng dẫn từng bước để tìm các mẫu cờ hiện có trong mã nguồn của bạn bằng grep.
  2. Phát hiện mẫu: Xác định các mẫu phổ biến (ví dụ: import, tên biến client, tên phương thức hoặc kiểu bọc).
  3. Mẫu mặc định: Các đoạn mã dự phòng nếu không tìm thấy mẫu nào.
  4. Ví dụ cụ thể theo framework: Các mẫu chuyên biệt cho React, Express, Django và các framework khác.
  5. Nhiều mẫu: Khối if, mệnh đề bảo vệ, hook, decorator, middleware, v.v.

Ngôn ngữ và framework được hỗ trợ:

  • TypeScript/JavaScript: Node.js, React Hooks, Express middleware.
  • Python: FastAPI, Django, Flask decorators.
  • Go: Khối if tiêu chuẩn, HTTP middleware.
  • Ruby: Rails controllers.
  • PHP: Laravel controllers.
  • C#: .NET/ASP.NET controllers.
  • Java: Spring Boot.
  • Rust: Actix/Rocket handlers.

Tham số

  • flagName (bắt buộc): Tên cờ tính năng để bọc mã. Ví dụ: "new-checkout-flow", hoặc "stripe-integration".
  • language (không bắt buộc): Ngôn ngữ lập trình (tự động phát hiện từ fileName nếu không được cung cấp). Được hỗ trợ: typescript, javascript, python, go, ruby, php, csharp, java, rust
  • fileName (không bắt buộc): Tên tệp đang được sửa đổi (giúp phát hiện ngôn ngữ). Ví dụ: "checkout.ts", "payment.py", hoặc "handler.go".
  • codeContext (không bắt buộc): Mã xung quanh để giúp phát hiện các mẫu hiện có.
  • frameworkHint (không bắt buộc): Framework cho các mẫu chuyên biệt. Ví dụ: "React", "Express", "Django", "Rails", hoặc "Spring Boot".

Ví dụ sử dụng

Lời nhắc của tác nhân

Use wrap_change with:
- flagName: "new-checkout-flow"
- fileName: "src/components/checkout.ts"
- frameworkHint: "React"

Tải trọng công cụ

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

Đầu ra công cụ

Trả về một chuỗi toàn diện, được định dạng markdown, hướng dẫn người dùng cách bọc mã của họ. Điều này bao gồm khởi động nhanh, hướng dẫn tìm kiếm, hướng dẫn bọc với các placeholder, tất cả các mẫu có sẵn cho ngôn ngữ và liên kết đến tài liệu 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.]

Đặt triển khai cờ

Công cụ set_flag_rollout cấu hình một chiến lược flexibleRollout trên một môi trường cờ tính năng. Nó đặt tỷ lệ triển khai, độ bám dính và các biến thể tùy chọn ở cấp chiến lược. Điều này không bật cờ; sử dụng toggle_flag_environment để bật nó.

Khi nào nên sử dụng

Sử dụng công cụ này sau khi tạo cờ bằng create_flag để cấu hình cách phân phối lưu lượng trước khi bật nó. Cũng sử dụng nó để cập nhật tỷ lệ triển khai hiện có hoặc thêm biến thể.

Tham số

  • featureName (bắt buộc): Tên cờ tính năng.
  • environment (bắt buộc): Môi trường mục tiêu (ví dụ: "production", "development").
  • rolloutPercentage (bắt buộc): Tỷ lệ phần trăm lưu lượng nhận tính năng (0-100).
  • projectId (không bắt buộc): ID dự án (mặc định là UNLEASH_DEFAULT_PROJECT).
  • groupId (không bắt buộc): Khóa phân nhóm độ bám dính (mặc định là tên tính năng).
  • stickiness (không bắt buộc): Trường độ bám dính (mặc định là "default").
  • title (không bắt buộc): Tiêu đề mô tả cho chiến lược.
  • disabled (không bắt buộc): Tạo chiến lược ở trạng thái vô hiệu (mặc định là false).
  • variants (không bắt buộc): Danh sách các biến thể ở cấp chiến lược, mỗi biến thể có name, weight (0-1000), weightType tùy chọn ("variable" hoặc "fix"), stickiness và payload ({type, value}).

Ví dụ sử dụng

Lời nhắc của tác nhân

Use set_flag_rollout with:
- featureName: "new-checkout-flow"
- environment: "production"
- rolloutPercentage: 25

Tải trọng công cụ

{
  "featureName": "new-checkout-flow",
  "environment": "production",
  "rolloutPercentage": 25,
  "projectId": "ecommerce",
  "stickiness": "userId"
}

Đầu ra công cụ

Trả về xác nhận với tỷ lệ phần trăm đã cấu hình, liên kết đến cờ trong Giao diện quản trị Unleash, URL chiến lược Admin API và liên kết tài nguyên MCP cho cờ.

Lấy trạng thái cờ

Công cụ get_flag_state lấy siêu dữ liệu hiện tại của cờ tính năng và các chiến lược môi trường từ Unleash Admin API. Nó trả về loại cờ, trạng thái bật/đã lưu trữ, cài đặt dữ liệu ấn tượng và tóm tắt theo môi trường về các chiến lược và biến thể đang hoạt động.

Khi nào nên sử dụng

Sử dụng công cụ này để kiểm tra cờ trước khi sửa đổi nó, để kiểm tra có bao nhiêu chiến lược đang hoạt động trên các môi trường hoặc để tìm ID chiến lược trước khi gọi remove_flag_strategy.

Tham số

  • featureName (bắt buộc): Tên cờ tính năng.
  • projectId (không bắt buộc): ID dự án (mặc định là UNLEASH_DEFAULT_PROJECT).
  • environment (không bắt buộc): Lọc kết quả theo một môi trường duy nhất (không phân biệt hoa thường).

Ví dụ sử dụng

Lời nhắc của tác nhân

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

Tải trọng công cụ

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

Đầu ra công cụ

Trả về tóm tắt văn bản về cờ (loại, trạng thái bật/đã lưu trữ/dữ liệu ấn tượng, dự án, tóm tắt môi trường với số lượng chiến lược) cùng với liên kết UI và API. Đầu ra có cấu trúc bao gồm đối tượng tính năng đầy đủ với tất cả các môi trường và chi tiết chiến lược.

Liệt kê cờ

Công cụ list_flags liệt kê các cờ tính năng trong một dự án và trả về một danh mục có cấu trúc với phân trang và thứ tự sắp xếp. Các cờ đang hoạt động và đã lưu trữ được trả về riêng biệt: gọi nó một lần với archived: false (mặc định) và một lần với archived: true để tập hợp một danh mục đầy đủ cho các quy trình kiểm toán.

Khi nào nên sử dụng

Sử dụng công cụ này khi tác nhân cần khám phá những cờ nào đã tồn tại, ví dụ để kiểm toán một dự án, tìm ứng viên để dọn dẹp hoặc xây dựng ngữ cảnh trước khi tạo hoặc bọc một cờ. Đây là tương đương có thể gọi bởi tác nhân của tài nguyên unleash://projects/{projectId}/feature-flags (xem Tài nguyên MCP).

Tham số

  • projectId (không bắt buộc): Dự án để liệt kê cờ (mặc định là UNLEASH_DEFAULT_PROJECT; tự động phân giải khi chỉ có một dự án).
  • archived (không bắt buộc): true để liệt kê các cờ đã lưu trữ thay vì các cờ đang hoạt động. Mặc định là false. Các cờ đang hoạt động và đã lưu trữ không thể được trả về trong cùng một phản hồi.
  • limit (không bắt buộc): Số cờ tối đa mỗi trang (mặc định: kích thước trang máy chủ, thường là 50).
  • order (không bắt buộc): Thứ tự sắp xếp theo tên cờ, asc hoặc desc (mặc định: asc).
  • offset (không bắt buộc): Số cờ để bỏ qua cho phân trang (mặc định: 0).

Ví dụ sử dụng

Lời nhắc của tác nhân

Use list_flags with:
- projectId: "ecommerce"
- archived: false

Tải trọng công cụ

{
  "projectId": "ecommerce",
  "archived": false,
  "limit": 50,
  "order": "asc"
}

Đầu ra công cụ

Trả về tóm tắt văn bản cộng với nội dung có cấu trúc với projectId, archived, order, limit, offset, nextOffset, totalFlags và mảng flags (mỗi mục có tên, loại, dự án, trạng thái đã lưu trữ và liên kết). Sử dụng nextOffset để phân trang qua các dự án lớn.

Liệt kê dự án

Công cụ list_projects liệt kê các dự án Unleash có sẵn cho token đã cấu hình, với phân trang và thứ tự sắp xếp.

Khi nào nên sử dụng

Sử dụng công cụ này khi dự án mục tiêu không xác định hoặc khi tác nhân cần chọn một dự án trước khi liệt kê hoặc tạo cờ. Đây là tương đương có thể gọi bởi tác nhân của tài nguyên unleash://projects (xem Tài nguyên MCP).

Tham số

  • limit (không bắt buộc): Số dự án tối đa mỗi trang (mặc định: kích thước trang máy chủ, thường là 20).
  • order (không bắt buộc): Thứ tự sắp xếp theo thời gian tạo dự án, asc hoặc desc (mặc định: desc, mới nhất trước).
  • offset (không bắt buộc): Số dự án để bỏ qua cho phân trang (mặc định: 0).

Ví dụ sử dụng

Lời nhắc của tác nhân

Use list_projects to see which projects are available.

Tải trọng công cụ

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

Đầu ra công cụ

Trả về tóm tắt văn bản cộng với nội dung có cấu trúc với order, limit, offset, nextOffset, totalProjects và mảng projects (mỗi mục có id, tên, mô tả, chế độ, thời gian tạo và URL).

Chuyển đổi môi trường cờ

Công cụ toggle_flag_environment bật hoặc tắt một cờ tính năng trong một môi trường cụ thể. Đối với triển khai dần dần, hãy cấu hình một chiến lược với set_flag_rollout trước khi bật.

Khi nào nên sử dụng

Sử dụng công cụ này để bật cờ sau khi cấu hình chiến lược triển khai hoặc để tắt cờ trong sự cố hoặc sau khi hoàn thành triển khai.

Tham số

  • featureName (bắt buộc): Tên cờ tính năng.
  • environment (bắt buộc): Môi trường để bật/tắt (ví dụ: "production").
  • enabled (bắt buộc): true để bật, false để tắt.
  • projectId (tùy chọn): ID dự án (mặc định là UNLEASH_DEFAULT_PROJECT).

Ví dụ sử dụng

Lời nhắc của tác nhân

Use toggle_flag_environment with:
- featureName: "new-checkout-flow"
- environment: "production"
- enabled: true

Tải trọng công cụ

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

Đầu ra của công cụ

Trả về xác nhận trạng thái mới, tóm tắt về môi trường (đã bật/tắt, số lượng chiến lược) và liên kết đến cờ trong Giao diện quản trị Unleash và API quản trị.

Xóa chiến lược cờ

Công cụ remove_flag_strategy xóa cấu hình chiến lược khỏi môi trường cờ tính năng. Sử dụng get_flag_state trước để khám phá ID chiến lược.

Khi nào nên sử dụng

Sử dụng công cụ này để dọn dẹp các chiến lược cũ hoặc để thay thế một chiến lược hiện có bằng cách xóa chiến lược cũ và cấu hình một chiến lược mới bằng set_flag_rollout.

Tham số

  • featureName (bắt buộc): Tên cờ tính năng.
  • environment (bắt buộc): Môi trường để xóa chiến lược.
  • strategyId (bắt buộc): ID của chiến lược cần xóa (tìm qua get_flag_state).
  • projectId (tùy chọn): ID dự án (mặc định là UNLEASH_DEFAULT_PROJECT).

Ví dụ sử dụng

Lời nhắc của tác nhân

Use get_flag_state to find strategy IDs for "new-checkout-flow" in production,
then use remove_flag_strategy to delete the old strategy.

Tải trọng công cụ

{
  "featureName": "new-checkout-flow",
  "environment": "production",
  "strategyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "projectId": "ecommerce"
}

Đầu ra của công cụ

Trả về xác nhận việc xóa, số lượng chiến lược còn lại trong môi trường và liên kết đến cờ trong Giao diện quản trị Unleash và API quản trị.

Dọn dẹp cờ

Công cụ cleanup_flag tạo hướng dẫn từng bước để xóa mã cờ tính năng khỏi cơ sở mã một cách an toàn trong khi vẫn giữ nguyên luồng mã mong muốn.

Khi nào nên sử dụng

Sử dụng công cụ này khi một cờ tính năng đã hoàn thành vòng đời của nó:

  • Sau khi triển khai đạt 100% và cờ không còn cần thiết.
  • Khi không dùng nữa một tính năng thử nghiệm (giữ nguyên luồng tắt).
  • Khi xóa một công tắc ngắt khẩn cấp không còn cần thiết.
  • Trong quá trình dọn dẹp nợ kỹ thuật của các cờ cũ.

Cách hoạt động

Công cụ trả về hướng dẫn dọn dẹp toàn diện hướng dẫn LLM thực hiện:

  1. Tìm tất cả các lần xuất hiện của cờ bằng các mẫu grep.
  2. Xác định các mẫu sử dụng (khối if-else, biểu thức ternary, mệnh đề bảo vệ, hook, decorator, middleware).
  3. Xóa các kiểm tra cờ trong khi vẫn giữ đúng luồng mã.
  4. Dọn dẹp các import không sử dụng với hướng dẫn cụ thể theo ngôn ngữ.
  5. Xác minh các thay đổi bằng các bước tìm kiếm và kiểm tra sau khi dọn dẹp.

Nếu preservePath không được cung cấp, công cụ sẽ trả về hướng dẫn yêu cầu người dùng chọn luồng nào cần giữ trước khi tiếp tục.

Tham số

  • flagName (bắt buộc): Tên của cờ tính năng cần xóa (ví dụ: "new-checkout-flow").
  • preservePath (tùy chọn): "enabled" để giữ luồng mã khi cờ bật (điển hình cho các đợt triển khai hoàn tất) hoặc "disabled" để giữ luồng khi cờ tắt (cho các thử nghiệm đã gỡ bỏ). Nếu bỏ qua, công cụ sẽ nhắc bạn hỏi người dùng.
  • files (tùy chọn): Các tệp cụ thể cần dọn dẹp. Nếu bỏ qua, sẽ tìm kiếm toàn bộ cơ sở mã.
  • language (tùy chọn): Ngôn ngữ lập trình để có hướng dẫn dọn dẹp import chuyên biệt (ví dụ: "typescript", "python"). Tự động phát hiện từ files nếu không được cung cấp.

Ví dụ sử dụng

Lời nhắc của tác nhân

Use cleanup_flag with:
- flagName: "new-checkout-flow"
- preservePath: "enabled"

Tải trọng công cụ

{
  "flagName": "new-checkout-flow",
  "preservePath": "enabled",
  "files": ["src/components/checkout.tsx", "src/api/checkout.ts"],
  "language": "typescript"
}

Đầu ra của công cụ

Trả về hướng dẫn markdown bao gồm phạm vi dọn dẹp và luồng được giữ, các lệnh grep để tìm tất cả các lần xuất hiện, hướng dẫn xóa theo từng mẫu, dọn dẹp import theo ngôn ngữ cụ thể và các bước xác minh sau khi dọn dẹp (tìm kiếm lại, chạy kiểm tra, xem xét thủ công).

Gửi phản hồi

Công cụ send_feedback báo cáo thời điểm MCP này hoạt động chưa đạt yêu cầu. Báo cáo được gửi đến một phiên bản do Unleash lưu trữ và giúp ưu tiên các bản sửa lỗi và công cụ mới.

Khi nào nên sử dụng

Trợ lý nên gọi công cụ này trước khi trả lời người dùng khi một trong những điều sau xảy ra:

  • tool_error: một lệnh gọi công cụ trả về lỗi (ngoại trừ lỗi xác thực, HTTP 401 hoặc 403).
  • unsupported_action: người dùng yêu cầu điều gì đó mà không công cụ nào có thể thực hiện.
  • unexpected_result: một công cụ thành công nhưng kết quả của nó không như mong đợi.

Không bao giờ gọi công cụ này sau một lệnh gọi công cụ thành công và không bao giờ báo cáo lỗi của chính send_feedback.

Sự đồng ý

Không có gì được gửi cho đến khi người dùng chọn tham gia. Ở lần gọi đầu tiên, MCP hỏi người dùng thông qua lời nhắc elicitation của MCP và lưu câu trả lời vào feedback_consent.json, do đó câu hỏi chỉ được hỏi một lần. Tệp nằm trong thư mục cấu hình nền tảng:

  • $XDG_CONFIG_HOME/unleash-mcp/feedback_consent.json khi XDG_CONFIG_HOME được đặt (bất kỳ nền tảng nào).
  • macOS: ~/Library/Application Support/unleash-mcp/feedback_consent.json
  • Linux: ~/.config/unleash-mcp/feedback_consent.json
  • Windows: %APPDATA%\unleash-mcp\feedback_consent.json (hoặc ~\AppData\Roaming\unleash-mcp\feedback_consent.json khi APPDATA không được đặt)

Đặt UNLEASH_MCP_CONFIG_DIR để giữ tệp trong một thư mục khác. Xóa tệp để được hỏi lại.

Nếu người dùng từ chối, công cụ trả về thông báo rằng phản hồi đã bị tắt và trợ lý không nên gọi lại trong phiên đó. Nếu máy khách không hỗ trợ elicitation hoặc lời nhắc bị hủy hoặc không được trả lời trong vòng 60 giây, phản hồi vẫn bị tắt trong phiên hiện tại và không có gì được lưu trữ, do đó câu hỏi sẽ được hỏi lại trong phiên tiếp theo.

Đặt UNLEASH_MCP_SEND_FEEDBACK=true hoặc UNLEASH_MCP_SEND_FEEDBACK=false để cấp hoặc từ chối sự đồng ý mà không cần lời nhắc. Biến môi trường ghi đè tệp đồng ý. Điều này hữu ích cho các máy khách không hỗ trợ elicitation và cho các thiết lập CI.

Khi máy chủ được nhúng trong một máy chủ HTTP thông qua createMcpHandler, sự đồng ý mặc định bị từ chối trừ khi máy chủ truyền feedbackConsent.

Những gì được ghi lại

Chỉ các trường trong danh sách cho phép mới được gửi:

  • Loại vấn đề, tên công cụ và mã lỗi đã chuẩn hóa.
  • Phiên bản MCP, tên máy khách và phiên bản máy khách.
  • Tóm tắt ngắn do trợ lý cung cấp.

Tóm tắt không được chứa tên cờ, ID dự án, mã, URL hoặc mã thông báo. Thông báo lỗi thô không bao giờ được gửi.

Tham số

  • issueType (bắt buộc): tool_error, unsupported_action hoặc unexpected_result.
  • summary (bắt buộc): Một hoặc hai câu mô tả điều gì đã xảy ra sai hoặc điều gì đã được yêu cầu (tối đa 500 ký tự).
  • tool (tùy chọn): Tên của công cụ MCP liên quan, ví dụ create_flag. Bỏ qua đối với các yêu cầu không được hỗ trợ.
  • errorCode (tùy chọn): Mã lỗi đã chuẩn hóa từ kết quả công cụ bị lỗi, ví dụ HTTP_500 hoặc VALIDATION_ERROR.

Ví dụ sử dụng

Lời nhắc của tác nhân

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

Tải trọng công cụ

{
  "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."
}

Đầu ra của công cụ

Trả về xác nhận rằng phản hồi đã được gửi (hoặc sẽ được gửi ở chế độ --dry-run) hoặc thông báo rằng phản hồi bị tắt vì người dùng chưa chọn tham gia. Nội dung có cấu trúc bao gồm success, sent và dryRun.

Tài nguyên MCP

Máy chủ đăng ký tài nguyên MCP để đọc dữ liệu dự án và cờ tính năng. Tất cả tài nguyên trả về JSON và được lưu trong bộ nhớ cache trong 60 giây.

Mẫu URIMô tả
unleash://projects{?limit,order,offset}Liệt kê các dự án. Kích thước trang mặc định: 20, được sắp xếp theo thời gian tạo (mới nhất trước).
unleash://projects/{projectId}/feature-flags{?limit,order,offset}Liệt kê các cờ trong một dự án. Kích thước trang mặc định: 50, được sắp xếp theo bảng chữ cái.
unleash://projects/{projectId}/feature-flags/{flagName}Siêu dữ liệu của một cờ tính năng duy nhất.

Hai mẫu đầu tiên chấp nhận các tham số truy vấn tùy chọn: limit (kích thước trang), order (asc hoặc desc) và offset (bắt đầu phân trang). Phản hồi bao gồm các trường fetchedAt, cached, totalProjects hoặc totalFlags và nextOffset.

Tài nguyên so với công cụ: Tài nguyên MCP do ứng dụng kiểm soát, vì vậy nhiều máy khách chỉ hiển thị chúng qua giao diện người dùng (ví dụ: đề cập #) và không cho phép tác nhân tự gọi resources/read. Khi một tác nhân cần liệt kê các dự án hoặc cờ theo chương trình, hãy sử dụng các công cụ list_projects và list_flags, trả về cùng dữ liệu qua giao diện công cụ. Phân tích kiểm kê detect_flag đi qua cùng một đường dẫn.

Ví dụ đọc tài nguyên

Read unleash://projects/ecommerce/feature-flags?limit=10&order=asc

Trả về 10 cờ tính năng đầu tiên trong dự án ecommerce, được sắp xếp theo bảng chữ cái, với siêu dữ liệu phân trang.

Kiến trúc

Máy chủ tuân theo một thiết kế tập trung, theo định hướng mục đích.

Cấu trúc

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
│   ├── setFlagRollout.ts        # set_flag_rollout tool
│   ├── getFlagState.ts          # get_flag_state tool
│   ├── toggleFlagEnvironment.ts # toggle_flag_environment tool
│   ├── removeFlagStrategy.ts    # remove_flag_strategy 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
    └── stdioLogging.ts          # Stdio protocol traffic logging

Nguyên tắc thiết kế

  • Bề mặt mỏng: Chỉ các điểm cuối cần thiết cho các khả năng cốt lõi.
  • Theo định hướng mục đích: Mỗi mô-đun phục vụ một mục đích cụ thể, được xác định rõ ràng.
  • Xác thực rõ ràng: Lược đồ Zod xác thực tất cả đầu vào trước khi gọi API.
  • Chuẩn hóa lỗi: Tất cả lỗi được chuyển đổi sang định dạng {code, message, hint}.
  • Truyền phát tiến trình: Các hoạt động chạy lâu cung cấp khả năng hiển thị.
  • Tích hợp thực tiễn tốt nhất: Hướng dẫn từ tài liệu Unleash được nhúng trong mô tả công cụ.

Cấu hình

Phần này cung cấp tài liệu tham khảo nhanh cho tất cả các tùy chọn cấu hình.

Biến môi trường:

  • UNLEASH_BASE_URL: URL phiên bản Unleash của bạn (bắt buộc). Cả https://your-instance.getunleash.io và https://your-instance.getunleash.io/api đều được chấp nhận — máy chủ chuẩn hóa dấu /api ở cuối nếu có, vì vậy bạn có thể dán cùng giá trị mà hầu hết SDK Unleash mong đợi.
  • UNLEASH_PAT: Mã thông báo truy cập cá nhân (bắt buộc).
  • UNLEASH_DEFAULT_PROJECT: ID dự án mặc định mà MCP nên sử dụng (tùy chọn).
  • UNLEASH_MCP_SEND_FEEDBACK: true hoặc false để cấp hoặc từ chối sự đồng ý send_feedback mà không cần lời nhắc (tùy chọn). Ghi đè tệp đồng ý đã lưu trữ.
  • UNLEASH_FEEDBACK_URL: URL cơ sở của phiên bản Unleash nhận báo cáo send_feedback (tùy chọn). Mặc định là phiên bản sản xuất do Unleash lưu trữ.
  • UNLEASH_MCP_CONFIG_DIR: Thư mục chứa feedback_consent.json (tùy chọn). Mặc định là thư mục cấu hình nền tảng được mô tả trong Sự đồng ý.

Cờ CLI:

  • --dry-run: Mô phỏng các hoạt động mà không thực hiện các lệnh gọi API thực tế.
  • --log-level: Đặt mức độ chi tiết ghi nhật ký (debug, info, warn, error).

Thực tiễn tốt nhất

Máy chủ này khuyến khích các thực tiễn tốt nhất của Unleash từ tài liệu chính thức:

Vòng đời cờ

  1. Tạo có chủ đích: Chọn đúng loại cờ để báo hiệu mục đích.
  2. Ghi chép rõ ràng: Viết mô tả giải thích "lý do".
  3. Lên kế hoạch dọn dẹp: Cờ tính năng là tạm thời; lên kế hoạch xóa chúng.
  4. Theo dõi việc sử dụng: Bật dữ liệu ấn tượng cho các cờ quan trọng.

Các loại cờ

  • Cờ phát hành: Cho việc triển khai tính năng dần dần (xóa sau khi triển khai đầy đủ).
  • Cờ thử nghiệm: Cho các bài kiểm tra A/B (xóa sau khi phân tích).
  • Cờ vận hành: Cho hành vi hệ thống (tồn tại lâu hơn, xem xét định kỳ).
  • Công tắc ngắt: Cho các kiểm soát khẩn cấp (duy trì cho đến khi tính năng ổn định).
  • Cờ quyền: Cho kiểm soát truy cập (tồn tại lâu hơn, xem xét quyền).

Quy ước đặt tên

  • Sử dụng kebab-case: new-checkout-flow
  • Mô tả rõ ràng: enable-ai-recommendations không phải flag1.
  • Bao gồm phạm vi khi cần: mobile-push-notifications.

Tài liệu tham khảo API

Máy chủ này sử dụng API quản trị Unleash. Để có tài liệu API đầy đủ, hãy xem:

Các điểm cuối được sử dụng

  • GET /api/admin/projects - Liệt kê các dự án
  • GET /api/admin/projects/{projectId}/features - Liệt kê các cờ tính năng
  • POST /api/admin/projects/{projectId}/features - Tạo cờ tính năng
  • GET /api/admin/projects/{projectId}/features/{featureName} - Lấy chi tiết cờ
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - Thêm chiến lược triển khai
  • DELETE /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies/{strategyId} - Xóa chiến lược
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/on - Bật cờ
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - Tắt cờ

send_feedback không gọi phiên bản Unleash của bạn. Nó đăng lên POST {UNLEASH_FEEDBACK_URL}/feedback trên phiên bản phản hồi do Unleash lưu trữ.

Xử lý sự cố

Các vấn đề cấu hình

Lỗi: "UNLEASH_BASE_URL phải là một URL hợp lệ": Đảm bảo URL cơ sở của bạn đầy đủ, bao gồm giao thức. Ví dụ: https://app.unleash-hosted.com/instance. Xóa mọi dấu gạch chéo ở cuối.

Lỗi: "UNLEASH_PAT là bắt buộc": Kiểm tra rằng tệp .env của bạn tồn tại và chứa UNLEASH_PAT={{your-personal-access-token}}. Xác minh rằng mã thông báo hợp lệ trong Unleash.

Các vấn đề API

Lỗi: "HTTP_401": Mã truy cập cá nhân của bạn có thể không hợp lệ hoặc đã hết hạn. Tạo mã mới trong Hồ sơ > Xem cài đặt hồ sơ > Mã API cá nhân > Mã mới.

Lỗi: "HTTP_403": Mã của bạn không có quyền tạo cờ trong dự án này. Hãy xem lại vai trò và quyền của bạn trong Unleash.

Lỗi: "HTTP_404": ID dự án không tồn tại. Xác nhận ID dự án trong Giao diện quản trị Unleash.

Lỗi: "HTTP_409": Một cờ có tên này đã tồn tại trong dự án. Sử dụng tên khác hoặc tái sử dụng cờ hiện có.

Sự cố phản hồi

"Phản hồi bị tắt": Người dùng từ chối đồng ý, máy khách không thể hiển thị lời nhắc đồng ý hoặc UNLEASH_MCP_SEND_FEEDBACK=false được đặt. Đặt UNLEASH_MCP_SEND_FEEDBACK=true hoặc xóa feedback_consent.json để được hỏi lại. Xem Đồng ý.

Lỗi: "Không thể kết nối đến điểm cuối phản hồi của Unleash": Báo cáo không thể đến được phiên bản phản hồi. Kiểm tra rằng UNLEASH_FEEDBACK_URL (hoặc phiên bản sản xuất mặc định) có thể truy cập từ mạng của bạn. Các thao tác cờ không bị ảnh hưởng.

Giấy phép

MIT

Đóng góp

Đây là dự án có mục đích cụ thể với phạm vi tập trung. Các đóng góp nên:

  • Phù hợp với bề mặt công cụ hiện có và mô hình tài nguyên MCP.
  • Duy trì kiến trúc mỏng, theo mục đích cụ thể.
  • Tuân theo các phương pháp hay nhất của Unleash.
  • Bao gồm tài liệu rõ ràng.