Unleash

официальный

MCP-сервер для управления функциональными флагами Unleash и автоматизации лучших практик.

GitHub

Попробовать этот 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 Server

Целевой Model Context Protocol (MCP) сервер для управления Unleash функциональными флагами. Этот сервер позволяет LLM-ассистентам для программирования создавать и управлять функциональными флагами, следуя лучшим практикам Unleash.

Чтобы поделиться отзывами, присоединяйтесь к нашему community Slack или откройте issue on GitHub.

Обзор

Этот MCP-сервер предоставляет инструменты, которые интегрируются с Unleash Admin API, позволяя AI-ассистентам для программирования:

Создавать функциональные флаги с правильной валидацией и типизацией.
Обнаруживать существующие флаги для предотвращения дубликатов или поощрения повторного использования.
Оценивать изменения для решения, когда нужен функциональный флаг.
Отображать прогресс для наглядности во время операций.
Обрабатывать ошибки корректно с полезными подсказками.
Следовать лучшим практикам из Unleash documentation.

Доступные инструменты

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: Наконец, этот инструмент предоставляет код на конкретном языке для реализации нового флага.

Дополнительную информацию об инструментах основного рабочего процесса см. в разделе Tool reference.

Предварительные требования

Перед запуском сервера вам понадобится следующее:

Node.js 22 или выше
Менеджер пакетов pnpm или npm
Экземпляр Unleash (хостируемый или самохостируемый)
personal access token с правами на создание функциональных флагов

Начало работы

В этом разделе рассматриваются различные способы установки и запуска Unleash MCP-сервера. Вы можете следовать настройке для agents (таких как Claude Code и Codex), запустить MCP как standalone process с помощью npx или использовать local development настройку.

Настройка агента

Вы можете добавить 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-сервера вы можете подключиться напрямую к встроенному удаленному MCP-серверу вашего экземпляра Unleash через HTTP. Это использует Streamable HTTP transport — локальный процесс не требуется.

Примечание: Удаленный 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 часа по умолчанию.

Personal Access Token (PAT)

Используйте этот метод, если у вас уже есть PAT или вам нужен headless/неинтерактивный доступ (CI-конвейеры, общие среды разработчиков, клиенты, не поддерживающие OAuth).

Чтобы создать PAT: войдите в свой экземпляр Unleash, перейдите в Profile > Personal Access Tokens и создайте новый токен.

Для 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

Вы можете запустить MCP-сервер как автономный процесс без клонирования репозитория, используя npx. Предоставьте конфигурацию через переменные окружения или локальный файл .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

Избегайте вывода 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, если не задано.
Флаг CLI --log-level: опциональное переопределение для LOG_LEVEL, когда нужна разовая настройка.
APP_LOG_FILE (опционально): если задано, журналы приложения записываются в этот файл (не в stdout). Если не задано, журналы идут в stderr.
MCP_STDIO_LOG_FILE (опционально): если задано, stdin/stdout/stderr MCP записываются в этот единый файл с префиксами каналов. Протокольные сообщения по-прежнему передаются через stdout нормально.

Атрибуция клиента

Когда MCP-клиент отправляет clientInfo во время инициализации (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro и другие соответствующие клиенты), сервер обогащает заголовок User-Agent в исходящих вызовах Unleash Admin API:

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
}

Вывод инструмента

При успехе инструмент возвращает JSON-объект, содержащий URL нового функционального флага в админ-интерфейсе Unleash, ссылку на ресурс MCP для программного доступа, временную метку создания и детали конфигурации.

Оценка изменения

Инструмент evaluate_change оценивает, должно ли изменение кода быть за функциональным флагом. Он анализирует структуру, контекст и потенциальный риск изменения и возвращает рекомендацию с объяснением и следующими шагами.

Когда использовать

Используйте evaluate_change в начале функции или модификации, когда вы хотите понять, требует ли работа функционального флага. Этот инструмент также полезен, когда вы не уверены, какой тип флага использовать, или хотите получить рекомендации по планированию раскатки.

Как это работает

Инструмент возвращает подробные рекомендации в формате Markdown для LLM-ассистента на основе Unleash best practices.

Рекомендации включают:

Обнаружение родительского флага: Проверяет, защищен ли код уже существующими флагами.
Оценка риска: Анализирует паттерны кода для выявления рискованных операций.
Оценка типа кода: Классифицирует изменение (например, тест, конфигурация, функция или исправление ошибки).
Рекомендация: Предлагает создать флаг, использовать существующий флаг или пропустить флаг.
Следующие действия: Предоставляет конкретные инструкции о том, что делать дальше.

Когда 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

Вывод включает оценку confidence (0-1), представляющую самооценку уверенности LLM, которая увеличивается с предоставлением большего контекста.

Категория исключенных охватывает файлы, которым не нужны функциональные флаги независимо от содержимого: тестовые файлы (*.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 middleware.
Python: FastAPI, Django, Flask decorators.
Go: Стандартные if-блоки, HTTP middleware.
Ruby: Rails controllers.
PHP: Laravel controllers.
C#: .NET/ASP.NET controllers.
Java: Spring Boot.
Rust: Actix/Rocket handlers.

Параметры

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 Admin UI, URL стратегий Admin API и ссылку на MCP-ресурс для флага.

Получить состояние флага

Инструмент get_flag_state получает текущие метаданные флага функции и стратегии окружений из Unleash Admin API. Он возвращает тип флага, статус включения/архивации, настройку данных о показах и сводку по каждому окружению с активными стратегиями и вариантами.

Когда использовать

Используйте этот инструмент для проверки флага перед его изменением, для проверки количества активных стратегий в окружениях или для поиска ID стратегий перед вызовом remove_flag_strategy.

Параметры

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 (обязательно): имя feature flag.
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 удаляет конфигурацию стратегии из окружения feature flag. Используйте get_flag_state сначала, чтобы узнать ID стратегии.

Когда использовать

Используйте этот инструмент для очистки устаревших стратегий или для замены существующей стратегии путем удаления старой и настройки новой с помощью set_flag_rollout.

Параметры

featureName (обязательно): имя feature flag.
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 генерирует пошаговые инструкции для безопасного удаления кода feature flag из кодовой базы с сохранением нужного пути выполнения кода.

Когда использовать

Используйте этот инструмент, когда feature flag завершил свой жизненный цикл:

После того как раскатка достигла 100% и флаг больше не нужен.
При выводе экспериментальной функции из эксплуатации (сохраните путь с отключенным флагом).
При удалении аварийного выключателя, который больше не нужен.
При очистке технического долга от старых флагов.

Как это работает

Инструмент возвращает подробные инструкции по очистке, которые направляют LLM через:

Поиск всех вхождений флага с помощью grep-паттернов.
Определение паттернов использования (блоки if-else, тернарные выражения, guard-условия, хуки, декораторы, middleware).
Удаление проверок флага с сохранением правильного пути выполнения кода.
Очистку неиспользуемых импортов с учетом языка программирования.
Проверку изменений с помощью поиска после очистки и тестовых шагов.

Если preservePath не указан, инструмент возвращает инструкции спросить пользователя, какой путь сохранить, перед продолжением.

Параметры

flagName (обязательно): имя feature flag для удаления (например, "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"
}

Вывод инструмента

Возвращает markdown-руководство, охватывающее область очистки и сохраненный путь, grep-команды для поиска всех вхождений, инструкции по удалению для каждого паттерна, очистку импортов с учетом языка и шаги проверки после очистки (повторный поиск, запуск тестов, ручная проверка).

MCP-ресурсы

Сервер регистрирует MCP ресурсы для чтения данных о проектах и feature flags. Все ресурсы возвращают JSON и кэшируются на 60 секунд.

Шаблон URI	Описание
`unleash://projects{?limit,order,offset}`	Список проектов. Размер страницы по умолчанию: 20, сортировка по времени создания (сначала новые).
`unleash://projects/{projectId}/feature-flags{?limit,order,offset}`	Список флагов в проекте. Размер страницы по умолчанию: 50, сортировка по алфавиту.
`unleash://projects/{projectId}/feature-flags/{flagName}`	Метаданные одного feature flag.

Первые два шаблона принимают необязательные параметры запроса: limit (размер страницы), order (asc или desc) и offset (начало пагинации). Ответы включают поля fetchedAt, cached, totalProjects или totalFlags и nextOffset.

Ресурсы и инструменты: MCP-ресурсы управляются приложением, поэтому многие клиенты показывают их только через пользовательский интерфейс (например, упоминания через #) и не позволяют агенту вызывать resources/read самостоятельно. Когда агенту нужно программно перечислить проекты или флаги, используйте инструменты list_projects и list_flags, которые возвращают те же данные через интерфейс инструментов. Анализ инвентаризации detect_flag проходит через тот же путь.

Пример чтения ресурса

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

Возвращает первые 10 feature flags в проекте ecommerce, отсортированные по алфавиту, с метаданными пагинации.

Архитектура

Сервер следует целенаправленному дизайну, ориентированному на конкретные задачи.

Структура

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: URL вашего экземпляра Unleash (обязательно). Принимаются как https://your-instance.getunleash.io, так и https://your-instance.getunleash.io/api — сервер нормализует завершающий /api, если он присутствует, поэтому вы можете вставить то же значение, которое ожидают большинство Unleash SDK.
UNLEASH_PAT: персональный токен доступа (обязательно).
UNLEASH_DEFAULT_PROJECT: ID проекта по умолчанию, который должен использовать MCP (необязательно).

Флаги CLI:

--dry-run: имитация операций без реальных вызовов API.
--log-level: установка уровня детализации логирования (debug, info, warn, error).

Лучшие практики

Этот сервер поддерживает лучшие практики Unleash из официальной документации:

Жизненный цикл флага

Создавайте с намерением: выбирайте правильный тип флага, чтобы обозначить цель.
Документируйте четко: пишите описания, объясняющие «почему».
Планируйте очистку: feature flags временны; планируйте их удаление.
Отслеживайте использование: включайте данные о показах для важных флагов.

Типы флагов

Флаги релизов: для постепенной раскатки функций (удалять после полной раскатки).
Флаги экспериментов: для 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 — список feature flags
POST /api/admin/projects/{projectId}/features — создать feature flag
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 проекта не существует. Подтвердите ID проекта в Unleash Admin UI.

Ошибка: «HTTP_409»: флаг с таким именем уже существует в проекте. Используйте другое имя или повторно используйте существующий флаг.

Лицензия

MIT

Участие в разработке

Это целенаправленный проект с четко определенной областью. Участие должно:

Соответствовать существующей поверхности инструментов и модели MCP-ресурсов.
Поддерживать минимальную целенаправленную архитектуру.
Следовать лучшим практикам Unleash.
Включать четкую документацию.