Unleash

公式

Unleashのフィーチャーフラグを管理し、ベストプラクティスを自動化するためのMCPサーバー。

Unleash MCPで何ができますか？

フィーチャーフラグを作成する — アシスタントに依頼して、create_flag で新しいフラグを作成します。名前、タイプ、説明を指定します。
変更にフラグが必要か評価する — evaluate_change を使用してリスクを評価し、コードを変更する前に推奨事項を取得します。
重複を避けるために既存のフラグを検出する — detect_flag を実行して、コードベース内でユースケースをすでにカバーしているフラグを検索します。
コードラッピングのガイダンスを取得する — フラグを作成した後、wrap_change を使用して、実装するための言語固有のスニペットを生成します。
段階的なロールアウトを設定する — フラグを有効にする前に、set_flag_rollout でロールアウトの割合とスティッキネスを設定します。
フラグの切り替えと戦略の管理 — toggle_flag_environment でフラグを有効または無効にし、remove_flag_strategy で戦略を削除し、get_flag_state で状態を確認します。

ドキュメント

Unleash MCP サーバー

Unleash フィーチャーフラグを管理するための、目的に特化した Model Context Protocol (MCP) サーバーです。このサーバーにより、LLM を活用したコーディングアシスタントは、Unleash のベストプラクティスに従ってフィーチャーフラグを作成・管理できるようになります。

フィードバックは、コミュニティ Slack に参加するか、GitHub で Issue を作成してお寄せください。

概要

この MCP サーバーは、Unleash Admin API と統合するツールを提供し、AI コーディングアシスタントが以下を実行できるようにします。

フィーチャーフラグの作成: 適切な検証と型付けを伴います。
既存フラグの検出: 重複を防いだり、再利用を促進します。
変更の評価: フィーチャーフラグが必要なタイミングを判断します。
進行状況のストリーミング: 操作中の可視性を確保します。
エラー処理: 役立つヒントと共に適切に処理します。
ベストプラクティスの遵守: Unleash ドキュメントに従います。

利用可能なツール

MCP サーバーは以下のツールを公開します。

create_flag: Unleash でフィーチャーフラグを作成します。
evaluate_change: リスクをスコアリングし、フィーチャーフラグの使用を推奨します。
detect_flag: 重複を避けるため、既存のフィーチャーフラグを検出します。
wrap_change: 変更をフィーチャーフラグでラップする方法についてガイダンスを提供します。
set_flag_rollout: フィーチャーフラグのロールアウト戦略を設定します（フラグの有効化は行いません）。
get_flag_state: フィーチャーフラグのメタデータとその有効化戦略を表示します。
list_flags: プロジェクト内のすべてのフィーチャーフラグを、オプションのページネーションと並び順で一覧表示します。
list_projects: 設定されたトークンが利用可能な Unleash プロジェクトを、オプションのページネーションで一覧表示します。
toggle_flag_environment: 環境でフィーチャーフラグを有効または無効にします。
remove_flag_strategy: 環境からフィーチャーフラグの戦略を削除します。
cleanup_flag: フラグ付きコードパスを安全に削除するための手順を生成します。

コアワークフロー

AI アシスタントのコアワークフローは以下のように設計されています。

evaluate_change: まず、コード変更を評価し、フラグが必要かどうかを確認します。
detect_flag: これは、重複するフラグの作成を防ぐために evaluate_change によって自動的に呼び出されることがよくあります。
create_flag: 新しいフラグが必要な場合、このツールが Unleash でそれを作成します。
wrap_change: 最後に、このツールが新しいフラグを実装するための言語固有のコードを提供します。

コアワークフローツールの詳細については、ツールリファレンスセクションを参照してください。

前提条件

サーバーを実行する前に、以下が必要です。

Node.js 22 以上
pnpm パッケージマネージャーまたは npm
Unleash インスタンス（ホスト型またはセルフホスト型）
フィーチャーフラグを作成する権限を持つ個人用アクセストークン

はじめに

このセクションでは、Unleash MCP サーバーをインストールして実行するさまざまな方法について説明します。エージェント（Claude Code や Codex など）向けのセットアップ、npx を使用したスタンドアロンプロセスとしての実行、またはローカル開発セットアップのいずれかを選択できます。

エージェントセットアップ

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

リモートエージェントセットアップ（実験的）

MCP サーバーをローカルで実行する代わりに、HTTP 経由で Unleash インスタンスの組み込みリモート 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 インスタンスにログインし、プロフィール > 個人用アクセストークン に移動して、新しいトークンを作成します。

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 --log-level debug

CLI はローカルビルドと同じフラグ（例: --dry-run、--log-level）をサポートしています。

ローカル開発セットアップ

ローカル開発用にプロジェクトをセットアップするには、以下の手順に従ってください。

依存関係のインストール

リポジトリをクローンし、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 pnpm@11.0.8 --activate

pnpm install

Claude または Codex から直接開発モードで実行

npm run 出力や tsx watch バナーは避けてください。余分な stdout は MCP ハンドシェイクを破壊するためです。2 つの静音オプションがあります。

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 と組み合わせます。
ログはリポジトリルート（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) に戻ります。デフォルト: 有効。

ツールリファレンス

このセクションでは、各コアツールについて、その目的、パラメーター、出力を含めて詳しく説明します。

フラグの作成

create_flag ツールは、包括的な検証と進行状況の追跡を伴って、Unleash で新しいフィーチャーフラグを作成します。

使用するタイミング

フィーチャーフラグが必要であると既に判断しており（例: evaluate_change の実行後）、正しいタイプとメタデータでそれを作成する準備ができている場合に、このツールを使用します。

パラメーター

このツールは以下のパラメーターを受け入れます。

name（必須）: プロジェクト内で一意のフィーチャーフラグ名。
type（必須）: ライフサイクルと意図を示すフィーチャーフラグタイプ。
- release: ユーザーへの段階的な機能ロールアウト。
- experiment: A/B テストと実験。
- operational: システム動作と運用上の切り替え。
- kill-switch: 緊急シャットダウンまたはサーキットブレーカー。
- permission: ユーザーロールまたは権限に基づいて機能アクセスを制御します。
description（必須）: フラグが制御するものと、それが存在する理由の明確な説明。
projectId（オプション）: ターゲットプロジェクト（デフォルトは UNLEASH_DEFAULT_PROJECT）。
impressionData（オプション）: 分析トラッキングを有効にします（デフォルトは false）。

使用例

エージェントプロンプト

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
}

ツール出力

成功すると、ツールは Unleash 管理 UI での新しいフィーチャーフラグの URL、プログラムによるアクセスのための MCP リソースリンク、作成タイムスタンプ、および設定の詳細を含む JSON オブジェクトを返します。

変更の評価

evaluate_change ツールは、コード変更をフィーチャーフラグの背後に置くべきかどうかを評価します。変更の構造、コンテキスト、および潜在的なリスクを調べ、説明と次のステップを含む推奨事項を返します。

使用するタイミング

機能や変更の開始時に、その作業にフィーチャーフラグが必要かどうかを理解したい場合に evaluate_change を使用します。このツールは、どのフラグタイプを使用すべきかわからない場合や、ロールアウト計画に関するガイダンスが必要な場合にも役立ちます。

仕組み

このツールは、Unleash のベストプラクティスに基づいて、LLM アシスタント向けの詳細な Markdown 形式のガイダンスを返します。

ガイダンスには以下が含まれます。

親フラグ検出: コードが既存のフラグによって既に保護されているかどうかを確認します。
リスク評価: コードパターンを分析して、リスクの高い操作を特定します。
コードタイプ評価: 変更を分類します（例: テスト、設定、機能、またはバグ修正）。
推奨事項: フラグを作成するか、既存のフラグを使用するか、フラグをスキップするかを提案します。
次のアクション: 次に何をすべきかについて具体的な指示を提供します。

evaluate_change がフラグが必要であると判断した場合、以下の明示的な指示を提供します。

create_flag ツールを呼び出してフィーチャーフラグを作成します。
wrap_change ツールを呼び出して、言語固有のコードラッピングガイダンスを取得します。
検出されたパターンに従って、ラップされたコードを実装します。

評価プロセス

このツールは、明確な評価プロセスに従います。

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

出力には、LLM の自己評価による確実性を表す confidence スコア（0-1）が含まれ、より多くのコンテキストが提供されると増加します。

除外カテゴリは、コンテンツに関係なくフィーチャーフラグを必要としないファイルを対象とします。テストファイル（*.test.ts、*_test.go など）、設定ファイル（*.config.js、.env、*.yaml）、ドキュメントファイル（*.md、docs/**）です。除外ファイルに限定された変更は、フラグの推奨をトリガーしません。

カテゴリごとのキーワード、ファイルグロブ、コードパターン、理由を含む完全なパターン定義は、src/evaluation/riskPatterns.ts にあります。

親フラグ検出

このツールは、以下のような言語間で共通のパターンを探します。

条件文: 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 (string): リポジトリ名またはパス。
branch (string): 現在のブランチ名。
files (array): 変更されるファイルのリスト。
description (string): 変更内容の説明。
riskLevel (enum): low、medium、high、または critical。ユーザーによる評価に基づきます。
codeContext (string): 親フラグ検出のための周辺コード。

使用例

エージェントプロンプト

エージェントにコンテキストを収集させるシンプルな使用法:

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 (オプション): フラグをスキャンするための周辺コード。

使用例

エージェントプロンプト

フラグを作成する前に既存のフラグをチェックする:

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 は、フィーチャーフラグでコードをラップするための言語固有のコードスニペットとガイダンスを生成します。LLMや開発者がコードベース内の既存のパターンに従い、フラグを正しく使用するのに役立ちます。

使用するタイミング

(create_flag で)フィーチャーフラグを作成した後、それをコードに実装する必要がある場合にこのツールを使用します。既存のコードベースのパターンに従っていることを確認したい場合や、フレームワーク固有の例(React、Djangoなど)が必要な場合に特に便利です。

仕組み

このツールは、evaluate_change → create_flag → wrap_change ワークフローの最終ステップです。

このツールは、レスポンスで以下のガイダンスを提供します。

検索手順: grepを使用してコードベース内の既存のフラグパターンを見つけるためのステップバイステップガイド。
パターン検出: 一般的なパターン(インポート、クライアント変数名、メソッド名、ラッピングスタイルなど)を識別します。
デフォルトテンプレート: パターンが見つからない場合のフォールバックコードスニペット。
フレームワーク固有の例: React、Express、Djangoなどのための特殊なパターン。
複数のパターン: 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"。

使用例

エージェントプロンプト

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 ツールは、フィーチャーフラグ環境に flexibleRollout 戦略を設定します。ロールアウトの割合、スティッキネス、オプションの戦略レベルのバリアントを設定します。これはフラグを有効にするものではありません。有効にするには toggle_flag_environment を使用してください。

使用するタイミング

create_flag でフラグを作成した後、有効にする前にトラフィックの分散方法を設定するためにこのツールを使用します。また、既存のロールアウト率を更新したり、バリアントを追加したりするためにも使用します。

パラメータ

featureName (必須): フィーチャーフラグ名。
environment (必須): ターゲット環境(例: "production"、"development")。
rolloutPercentage (必須): 機能を受け取るトラフィックの割合(0-100)。
projectId (オプション): プロジェクトID(デフォルトは UNLEASH_DEFAULT_PROJECT)。
groupId (オプション): スティッキネスバケットキー(デフォルトは機能名)。
stickiness (オプション): スティッキネスフィールド(デフォルトは "default")。
title (オプション): 戦略の説明的なタイトル。
disabled (オプション): 無効状態で戦略を作成します(デフォルトはfalse)。
variants (オプション): 戦略レベルのバリアントのリスト。各バリアントには name、weight (0-1000)、オプションの weightType ("variable" または "fix")、stickiness、payload ({type, value}) が含まれます。

使用例

エージェントプロンプト

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

ツールペイロード

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

ツール出力

設定された割合、Unleash管理UIでのフラグへのリンク、管理API戦略URL、フラグのMCPリソースリンクを含む確認を返します。

フラグ状態の取得

get_flag_state ツールは、Unleash管理APIからフィーチャーフラグの現在のメタデータと環境戦略を取得します。フラグのタイプ、有効/アーカイブ状態、インプレッションデータ設定、環境ごとのアクティブな戦略とバリアントの概要を返します。

使用するタイミング

フラグを変更する前に検査したり、環境間でアクティブな戦略の数を確認したり、remove_flag_strategy を呼び出す前に戦略IDを見つけたりするためにこのツールを使用します。

パラメータ

featureName (必須): フィーチャーフラグ名。
projectId (オプション): プロジェクトID(デフォルトは UNLEASH_DEFAULT_PROJECT)。
environment (オプション): 結果を単一の環境にフィルタリングします(大文字と小文字を区別しません)。

使用例

エージェントプロンプト

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

ツールペイロード

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

ツール出力

フラグのテキストサマリー(タイプ、有効/アーカイブ/インプレッションデータ、プロジェクト、戦略数を含む環境サマリー)とUIおよびAPIリンクを返します。構造化された出力には、すべての環境と戦略の詳細を含む完全な機能オブジェクトが含まれます。

フラグの一覧表示

list_flags ツールは、プロジェクト内のフィーチャーフラグを列挙し、ページネーションとソート順序を備えた構造化されたインベントリを返します。アクティブなフラグとアーカイブされたフラグは別々に返されます。監査ワークフロー用に完全なインベントリを組み立てるには、archived: false (デフォルト)で1回、archived: true で1回呼び出します。

使用するタイミング

エージェントが既存のフラグを発見する必要がある場合、例えばプロジェクトの監査、クリーンアップ候補の発見、フラグの作成やラップ前のコンテキスト構築などにこのツールを使用します。これは unleash://projects/{projectId}/feature-flags リソースのエージェント呼び出し可能な同等機能です(MCPリソースを参照)。

パラメータ

projectId (オプション): フラグを一覧表示するプロジェクト(デフォルトは UNLEASH_DEFAULT_PROJECT。単一のプロジェクトが存在する場合は自動解決されます)。
archived (オプション): アクティブなフラグの代わりにアーカイブされたフラグを一覧表示する場合は true。デフォルトは false。アクティブなフラグとアーカイブされたフラグを同じレスポンスで返すことはできません。
limit (オプション): 1ページあたりの最大フラグ数(デフォルト: サーバーページサイズ、通常50)。
order (オプション): フラグ名によるソート順、asc または desc (デフォルト: asc)。
offset (オプション): ページネーションのためにスキップするフラグの数(デフォルト: 0)。

使用例

エージェントプロンプト

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

ツールペイロード

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

ツール出力

テキストサマリーと、projectId、archived、order、limit、offset、nextOffset、totalFlags、および flags 配列(それぞれ名前、タイプ、プロジェクト、アーカイブ状態、リンクを含む)を含む構造化コンテンツを返します。大規模なプロジェクトをページングするには nextOffset を使用します。

プロジェクトの一覧表示

list_projects ツールは、設定されたトークンで利用可能なUnleashプロジェクトを、ページネーションとソート順序で列挙します。

使用するタイミング

ターゲットプロジェクトが不明な場合や、エージェントがフラグを一覧表示または作成する前にプロジェクトを選択する必要がある場合にこのツールを使用します。これは unleash://projects リソースのエージェント呼び出し可能な同等機能です(MCPリソースを参照)。

パラメータ

limit (オプション): 1ページあたりの最大プロジェクト数(デフォルト: サーバーページサイズ、通常20)。
order (オプション): プロジェクト作成時間によるソート順、asc または desc (デフォルト: desc、新しい順)。
offset (オプション): ページネーションのためにスキップするプロジェクト数(デフォルト: 0)。

使用例

エージェントプロンプト

Use list_projects to see which projects are available.

ツールペイロード

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

ツール出力

テキストサマリーと、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)。

使用例

エージェントプロンプト

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

ツールペイロード

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

ツール出力

新しい状態の確認、環境のサマリー (有効/無効、ストラテジー数)、およびUnleash管理UIと管理APIでのフラグへのリンクを返します。

フラグストラテジーの削除

remove_flag_strategy ツールは、フィーチャーフラグ環境からストラテジー設定を削除します。ストラテジーIDを特定するには、事前に get_flag_state を使用してください。

使用する場面

古くなったストラテジーを整理する場合や、既存のストラテジーを削除して set_flag_rollout で新しいストラテジーを設定し直す場合に使用します。

パラメーター

featureName (必須): フィーチャーフラグ名。
environment (必須): ストラテジーを削除する環境。
strategyId (必須): 削除するストラテジーのID (get_flag_state で確認可能)。
projectId (任意): プロジェクトID (デフォルトは UNLEASH_DEFAULT_PROJECT)。

使用例

エージェントプロンプト

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

ツール出力

削除の確認、環境内の残りストラテジー数、およびUnleash管理UIと管理APIでのフラグへのリンクを返します。

フラグのクリーンアップ

cleanup_flag ツールは、コードベースからフィーチャーフラグコードを安全に削除し、目的のコードパスを保持するためのステップバイステップの手順を生成します。

使用する場面

フィーチャーフラグのライフサイクルが完了した場合に使用します:

ロールアウトが100%に達し、フラグが不要になった後。
実験的機能を廃止する場合 (無効パスを保持)。
不要になったキルスイッチを削除する場合。
古いフラグの技術的負債を解消する場合。

動作の仕組み

このツールは、以下の手順をLLMにガイドする包括的なクリーンアップ手順を返します:

grepパターンを使用してフラグの全出現箇所を検索。
使用パターン (if-elseブロック、三項演算子、ガード節、フック、デコレーター、ミドルウェア) の特定。
正しいコードパスを保持しながらフラグチェックを削除。
言語固有のガイダンスに従って未使用のインポートを整理。
クリーンアップ後の検索とテスト手順による変更の確認。

preservePath が指定されていない場合、ツールは続行前にどのパスを保持するかユーザーに尋ねるよう指示を返します。

パラメーター

flagName (必須): 削除するフィーチャーフラグの名前 (例: "new-checkout-flow")。
preservePath (任意): フラグオンのコードパスを保持する場合は "enabled"、フラグオフのパスを保持する場合は "disabled" (削除された実験用)。省略した場合、ツールはユーザーに確認するよう促します。
files (任意): クリーンアップ対象の特定のファイル。省略した場合、コードベース全体を検索します。
language (任意): インポート整理の専門的なガイダンスのためのプログラミング言語 (例: "typescript", "python")。指定がない場合、files から自動検出されます。

使用例

エージェントプロンプト

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

ツール出力

クリーンアップ範囲と保持パス、全出現箇所を検索するgrepコマンド、パターン別の削除手順、言語固有のインポート整理、クリーンアップ後の確認手順 (再検索、テスト実行、手動レビュー) をカバーするMarkdownガイドを返します。

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}`	単一フィーチャーフラグのメタデータ。

最初の2つのテンプレートは、オプションのクエリパラメーターを受け付けます: limit (ページサイズ)、order (asc または desc)、offset (ページネーション開始位置)。レスポンスには fetchedAt、cached、totalProjects または totalFlags、nextOffset フィールドが含まれます。

リソース vs. ツール: MCPリソースはアプリケーション制御のため、多くのクライアントはユーザー駆動のUI (例: # メンション) を通じてのみそれらを表示し、エージェントが単独で resources/read を呼び出すことを許可しません。エージェントがプログラムでプロジェクトやフラグを列挙する必要がある場合は、ツールインターフェースを通じて同じデータを返す 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
├── 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
├── 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

設計原則

薄いサーフェスエリア: コア機能に必要なエンドポイントのみ。
目的駆動: 各モジュールは特定の明確な目的を果たします。
明示的なバリデーション: 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 (任意)。

CLIフラグ:

--dry-run: 実際のAPI呼び出しを行わずに操作をシミュレートします。
--log-level: ログの詳細度を設定します (debug, info, warn, error)。

ベストプラクティス

このサーバーは、公式ドキュメントのUnleashベストプラクティスを推奨します:

フラグのライフサイクル

意図を持って作成: 目的を示す適切なフラグタイプを選択します。
明確に文書化: 「なぜ」を説明する説明を記述します。
クリーンアップを計画: フィーチャーフラグは一時的なものです。削除を計画します。
使用状況を監視: 重要なフラグではインプレッションデータを有効にします。

フラグタイプ

リリースフラグ: 段階的な機能ロールアウト用 (完全ロールアウト後に削除)。
実験フラグ: A/Bテスト用 (分析後に削除)。
運用フラグ: システム動作の変更用 (長期間存続、定期的にレビュー)。
キルスイッチ: 緊急制御用 (機能が安定するまで維持)。
権限フラグ: アクセス制御用 (長期間存続、権限をレビュー)。

命名規則

ケバブケースを使用: new-checkout-flow
説明的に: enable-ai-recommendations ではなく flag1。
必要に応じてスコープを含める: mobile-push-notifications。

APIリファレンス

このサーバーはUnleash管理APIを使用します。完全なAPIドキュメントについては、以下を参照してください:

使用エンドポイント

GET /api/admin/projects - プロジェクト一覧
GET /api/admin/projects/{projectId}/features - フィーチャーフラグ一覧
POST /api/admin/projects/{projectId}/features - フィーチャーフラグ作成
GET /api/admin/projects/{projectId}/features/{featureName} - フラグ詳細取得
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 - フラグ無効化

トラブルシューティング

設定の問題

エラー: "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管理UIでプロジェクトIDを確認してください。

エラー: "HTTP_409": この名前のフラグがプロジェクトに既に存在します。別の名前を使用するか、既存のフラグを再利用してください。

ライセンス

MIT

貢献

これは焦点を絞った範囲の目的駆動型プロジェクトです。貢献は以下に沿う必要があります:

既存のツールサーフェスとMCPリソースモデルに整合すること。
薄く、目的駆動型のアーキテクチャを維持すること。
Unleashのベストプラクティスに従うこと。
明確なドキュメントを含めること。