Unleash

공식

Unleash 기능 플래그를 관리하고 모범 사례를 자동화하기 위한 MCP 서버입니다.

GitHub

Unleash MCP(으)로 무엇을 할 수 있나요?

Create feature flags — Ask the assistant to create a new flag with create_flag, specifying name, type, and description.
Evaluate if a change needs a flag — Use evaluate_change to assess risk and get a recommendation before modifying code.
Detect existing flags to avoid duplicates — Run detect_flag to search the codebase for flags that already cover your use case.
Get code wrapping guidance — After creating a flag, use wrap_change to generate language-specific snippets for implementing it.
Configure gradual rollouts — Set rollout percentage and stickiness with set_flag_rollout before enabling a flag.
Toggle flags and manage strategies — Enable or disable flags via toggle_flag_environment, remove strategies with remove_flag_strategy, and inspect state with get_flag_state.

문서

Unleash MCP 서버

Unleash 기능 플래그를 관리하기 위한 목적 지향 모델 컨텍스트 프로토콜 (MCP) 서버입니다. 이 서버는 LLM 기반 코딩 어시스턴트가 Unleash 모범 사례에 따라 기능 플래그를 생성하고 관리할 수 있도록 지원합니다.

피드백을 공유하려면 커뮤니티 Slack에 참여하거나 GitHub에서 이슈를 열어주세요.

개요

이 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를 실행하거나, 로컬 개발 설정을 사용할 수 있습니다.

에이전트 설정

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 서버에 직접 연결할 수 있습니다. 이는 스트리밍 가능 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 핸드셰이크를 중단시키므로 피하세요. 두 가지 조용한 옵션:

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이 채널 접두사와 함께 이 단일 파일로 티(tee)됩니다. 프로토콜 메시지는 여전히 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/<version> (MCP Server)로 되돌리려면 UNLEASH_MCP_CLIENT_ATTRIBUTION=off을 설정하세요. 기본값: 활성화됨.

도구 참조

이 섹션에서는 각 핵심 도구의 목적, 매개변수 및 출력을 포함하여 자세히 설명합니다.

플래그 생성

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 Admin UI의 새 기능 플래그 URL, 프로그래밍 방식 액세스를 위한 MCP 리소스 링크, 생성 타임스탬프 및 구성 세부 정보를 포함하는 JSON 객체를 반환합니다.

변경 평가

evaluate_change 도구는 코드 변경이 기능 플래그 뒤에 있어야 하는지 평가합니다. 변경의 구조, 컨텍스트 및 잠재적 위험을 검토하고 설명 및 다음 단계와 함께 권장 사항을 반환합니다.

사용 시기

기능 또는 수정 작업을 시작할 때 해당 작업에 기능 플래그가 필요한지 이해하려면 evaluate_change를 사용하세요. 이 도구는 어떤 플래그 유형을 사용해야 할지 확실하지 않거나 롤아웃 계획에 대한 지침이 필요할 때도 유용합니다.

작동 방식

이 도구는 Unleash 모범 사례를 기반으로 LLM 어시스턴트를 위한 상세한 마크다운 형식의 지침을 반환합니다.

지침에는 다음이 포함됩니다:

상위 플래그 감지: 코드가 이미 기존 플래그로 보호되고 있는지 확인합니다.
위험 평가: 코드 패턴을 분석하여 위험한 작업을 식별합니다.
코드 유형 평가: 변경 사항을 분류합니다(예: 테스트, 구성, 기능 또는 버그 수정).
권장 사항: 플래그 생성, 기존 플래그 사용 또는 플래그 건너뛰기를 제안합니다.
다음 조치: 수행할 작업에 대한 구체적인 지침을 제공합니다.

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 (문자열): 저장소 이름 또는 경로.
branch (문자열): 현재 브랜치 이름.
files (배열): 변경 중인 파일 목록.
description (문자열): 변경 사항에 대한 설명.
riskLevel (열거형): 사용자가 평가한 low, medium, high, 또는 critical.
codeContext (문자열): 상위 플래그 감지를 위한 주변 코드.

사용 예시

에이전트 프롬프트

에이전트가 컨텍스트를 수집하도록 하는 간단한 사용법:

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

도구 출력

코드 래핑 방법을 안내하는 포괄적인 마크다운 형식의 문자열을 반환합니다. 여기에는 빠른 시작, 검색 지침, 플레이스홀더가 포함된 래핑 지침, 해당 언어에 사용 가능한 모든 템플릿, 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(기본값)로 한 번, archived: true로 한 번 호출하세요.

사용 시기

에이전트가 이미 존재하는 플래그를 발견해야 할 때, 예를 들어 프로젝트 감사, 정리 대상 후보 찾기, 플래그 생성 또는 래핑 전 컨텍스트 구축 시 이 도구를 사용하세요. 이는 unleash://projects/{projectId}/feature-flags 리소스의 에이전트 호출 가능 버전입니다 (MCP 리소스 참조).

매개변수

projectId (선택 사항): 플래그를 나열할 프로젝트 (기본값: UNLEASH_DEFAULT_PROJECT; 단일 프로젝트 존재 시 자동 해결).
archived (선택 사항): 활성 플래그 대신 보관된 플래그를 나열하려면 true. 기본값은 false입니다. 활성 플래그와 보관된 플래그는 동일한 응답에 반환될 수 없습니다.
limit (선택 사항): 페이지당 최대 플래그 수 (기본값: 서버 페이지 크기, 일반적으로 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 (선택 사항): 페이지당 최대 프로젝트 수 (기본값: 서버 페이지 크기, 일반적으로 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 명령, 패턴별 제거 지침, 언어별 임포트 정리, 정리 후 확인 단계(재검색, 테스트 실행, 수동 검토)를 다루는 마크다운 가이드를 반환합니다.

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}`	단일 기능 플래그 메타데이터.

처음 두 템플릿은 선택적 쿼리 매개변수를 허용합니다: 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

설계 원칙

얇은 표면적: 핵심 기능에 필요한 엔드포인트만 사용.
목적 지향: 각 모듈은 구체적이고 잘 정의된 목적을 수행.
명시적 유효성 검사: Zod 스키마가 API 호출 전에 모든 입력을 검증.
오류 정규화: 모든 오류를 {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": 개인 액세스 토큰이 유효하지 않거나 만료되었을 수 있습니다. 프로필 > 프로필 설정 보기 > 개인 API 토큰 > 새 토큰에서 새 토큰을 생성하세요.

오류: "HTTP_403": 토큰에 이 프로젝트에서 플래그를 생성할 권한이 없습니다. Unleash에서 역할과 권한을 검토하세요.

오류: "HTTP_404": 프로젝트 ID가 존재하지 않습니다. Unleash 관리 UI에서 프로젝트 ID를 확인하세요.

오류: "HTTP_409": 해당 이름의 플래그가 프로젝트에 이미 존재합니다. 다른 이름을 사용하거나 기존 플래그를 재사용하세요.

라이선스

MIT

기여

이 프로젝트는 집중된 범위를 가진 목적 지향적 프로젝트입니다. 기여 시 다음 사항을 준수해야 합니다:

기존 도구 표면 및 MCP 리소스 모델과 일치.
얇고 목적 지향적인 아키텍처 유지.
Unleash 모범 사례 준수.
명확한 문서 포함.

Unleash

Unleash MCP(으)로 무엇을 할 수 있나요?

문서

Unleash MCP 서버

개요

사용 가능한 도구

핵심 워크플로

전제 조건

시작하기

에이전트 설정

원격 에이전트 설정 (실험적)

OAuth

개인 액세스 토큰 (PAT)

npx를 사용한 빠른 시작

로컬 개발 설정

로깅 제어

클라이언트 어트리뷰션

도구 참조

플래그 생성

사용 시기

매개변수

사용 예시

변경 평가

사용 시기

작동 방식

매개변수

사용 예시

플래그 감지

사용 시기

작동 방식

매개변수

사용 예시

변경 사항 래핑

사용 시기

작동 방식

매개변수

사용 예시

플래그 롤아웃 설정

사용 시기

매개변수

사용 예시

플래그 상태 가져오기

사용 시기

매개변수

사용 예시

플래그 목록

사용 시기

매개변수

사용 예시

프로젝트 목록

사용 시기

매개변수

사용 예시

플래그 환경 전환

사용 시기

매개변수- featureName (필수): 기능 플래그 이름.

사용 예시

플래그 전략 제거

사용 시기

매개변수

사용 예시

플래그 정리

사용 시기

작동 방식

매개변수

사용 예시

MCP 리소스

아키텍처

구조

설계 원칙

구성

모범 사례

플래그 수명 주기

플래그 유형

명명 규칙

API 참조

사용되는 엔드포인트

문제 해결

구성 문제

API 문제

매개변수- `featureName` (필수): 기능 플래그 이름.