Unleash

공식

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

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

코드 변경 평가 — evaluate_change를 호출하여 위험도를 점수화하고 코드 변경에 기능 플래그가 필요한지 추천받습니다.
기능 플래그 생성 — create_flag를 사용하여 유형, 설명, 프로젝트 타게팅을 포함한 새 플래그를 프로비저닝합니다.
기존 플래그 감지 — detect_flag를 실행하여 코드나 git 히스토리에서 재사용 가능한 플래그를 찾고 중복을 방지합니다.
래핑 가이드 얻기 — wrap_change를 요청하여 플래그 구현을 위한 언어별 코드 템플릿을 받습니다.
롤아웃 및 상태 관리 — set_flag_rollout 백분율을 구성한 다음 toggle_flag_environment로 플래그를 활성화 또는 비활성화합니다.
플래그 검사 및 목록화 — get_flag_state 또는 list_flags를 사용하여 플래그 메타데이터, 전략, 프로젝트 인벤토리를 검토합니다.

문서

Unleash MCP 서버

목적 중심의 Model Context Protocol(MCP) 서버로, Unleash 기능 플래그를 관리합니다. 이 서버는 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 서버를 로컬에서 실행하는 대신 Unleash 인스턴스의 내장 원격 MCP 서버에 HTTP로 직접 연결할 수 있습니다. 이는 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@latest --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에서 직접 개발 모드로 실행

추가 stdout이 MCP 핸드셰이크를 방해하므로 npm run 출력과 tsx watch 배너를 피하세요. 두 가지 조용한 옵션이 있습니다:

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_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 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 Admin UI 및 Admin 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 Admin UI 및 Admin API의 플래그 링크를 반환합니다.

플래그 정리

cleanup_flag 도구는 원하는 코드 경로를 유지하면서 코드베이스에서 기능 플래그 코드를 안전하게 제거하기 위한 단계별 지침을 생성합니다.

사용 시기

기능 플래그의 수명 주기가 완료된 경우 이 도구를 사용하세요:

롤아웃이 100%에 도달하고 플래그가 더 이상 필요하지 않은 경우.
실험적 기능을 폐기할 때(비활성화 경로 유지).
더 이상 필요하지 않은 킬 스위치를 제거할 때.
오래된 플래그의 기술 부채 정리 중.

작동 방식

이 도구는 LLM을 안내하는 포괄적인 정리 지침을 반환합니다:

grep 패턴을 사용하여 플래그의 모든 발생 위치 찾기.
사용 패턴 식별(if-else 블록, 삼항 표현식, 가드 절, 훅, 데코레이터, 미들웨어).
올바른 코드 경로를 유지하면서 플래그 검사 제거.
언어별 지침으로 사용하지 않는 import 정리.
정리 후 검색 및 테스트 단계로 변경 사항 검증.

preservePath가 제공되지 않으면 도구는 진행 전에 사용자에게 유지할 경로를 물어보라는 지침을 반환합니다.

매개변수

flagName (필수): 제거할 기능 플래그 이름 (예: "new-checkout-flow").
preservePath (선택): 완료된 롤아웃의 일반적인 경우 플래그-온 코드 경로를 유지하려면 "enabled", 제거된 실험의 경우 플래그-오프 경로를 유지하려면 "disabled". 생략하면 도구가 사용자에게 물어보도록 안내합니다.
files (선택): 정리할 특정 파일. 생략하면 전체 코드베이스를 검색합니다.
language (선택): 특수 import 정리 지침을 위한 프로그래밍 언어 (예: "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 명령, 패턴별 제거 지침, 언어별 import 정리, 정리 후 검증 단계(재검색, 테스트 실행, 수동 검토)를 포함한 마크다운 가이드를 반환합니다.

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 테스트용 (분석 후 제거).
운영 플래그: 시스템 동작용 (장기 유지, 주기적 검토).
킬 스위치: 비상 제어용 (기능이 안정될 때까지 유지).
권한 플래그: 액세스 제어용 (장기 유지, 권한 검토).

명명 규칙

kebab-case 사용: new-checkout-flow
설명적으로 작성: enable-ai-recommendations (flag1 아님).
필요 시 범위 포함: mobile-push-notifications.

API 참조

이 서버는 Unleash Admin 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 Admin UI에서 프로젝트 ID를 확인하세요.

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

라이선스

MIT

기여

이 프로젝트는 집중된 범위를 가진 목적 중심 프로젝트입니다. 기여는 다음을 따라야 합니다:

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