Unleash

официальный

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

Что можно делать с Unleash MCP?

Создание флагов функций — Попросите ассистента создать новый флаг с помощью create_flag, указав имя, тип и описание.
Оценка необходимости флага для изменения — Используйте evaluate_change, чтобы оценить риск и получить рекомендацию перед изменением кода.
Поиск существующих флагов для избежания дублирования — Запустите detect_flag, чтобы найти в кодовой базе флаги, которые уже покрывают ваш сценарий использования.
Получение рекомендаций по обёртке кода — После создания флага используйте wrap_change, чтобы сгенерировать сниппеты для его внедрения на конкретном языке.
Настройка постепенного развёртывания — Установите процент развёртывания и привязку с помощью set_flag_rollout перед включением флага.
Управление флагами и стратегиями — Включайте или отключайте флаги через toggle_flag_environment, удаляйте стратегии с помощью remove_flag_strategy и проверяйте состояние через get_flag_state.

Документация

Unleash MCP Server

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

Чтобы поделиться отзывами, присоединяйтесь к нашему сообществу в Slack или создайте issue на 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 (облачный или собственный)
Персональный токен доступа с правами на создание флагов функций

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

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

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

Вы можете добавить MCP-сервер непосредственно в Claude Code или Codex. Конфигурации агента зависят от пути. Вы должны выполнить следующую команду из корневой директории проекта, в котором хотите использовать MCP.

Для Claude Code:

claude mcp add unleash \
    --env UNLEASH_BASE_URL={{your-instance-url}} \
    --env UNLEASH_PAT={{your-personal-access-token}} \
    -- npx -y @unleash/mcp@latest --log-level error

Для Codex:

codex mcp add unleash \
    --env UNLEASH_BASE_URL={{your-instance-url}} \
    --env UNLEASH_PAT={{your-personal-access-token}} \
    -- npx -y @unleash/mcp@latest --log-level error

Настройка удаленного агента (экспериментальная)

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

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

Оценить изменение

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

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

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

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

Инструмент возвращает подробное руководство в формате markdown для LLM-ассистента, основанное на лучших практиках Unleash.

Руководство включает:

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

Когда 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/**). Изменения, ограниченные исключенными файлами, не вызовут рекомендации флага.

Полные определения шаблонов, включая ключевые слова по категориям, glob-шаблоны файлов, шаблоны кода и обоснование, находятся в 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 истинно, он включает объект 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, guard clauses, хуки, декораторы, middleware и многое другое.

Поддерживаемые языки и фреймворки:

TypeScript/JavaScript: Node.js, React Hooks, Express middleware.
Python: FastAPI, Django, Flask декораторы.
Go: Стандартные блоки if, HTTP middleware.
Ruby: Rails контроллеры.
PHP: Laravel контроллеры.
C#: .NET/ASP.NET контроллеры.
Java: Spring Boot.
Rust: Actix/Rocket обработчики.

Параметры

flagName (обязательный): Имя функционального флага для оборачивания кода. Например: "new-checkout-flow" или "stripe-integration".
language (необязательный): Язык программирования (автоопределяется из fileName, если не указан). Поддерживаются: typescript, javascript, python, go, ruby, php, csharp, java, rust
fileName (необязательный): Имя изменяемого файла (помогает определить язык). Например: "checkout.ts", "payment.py" или "handler.go".
codeContext (необязательный): Окружающий код для обнаружения существующих шаблонов.
frameworkHint (необязательный): Фреймворк для специализированных шаблонов. Например, "React", "Express", "Django", "Rails" или "Spring Boot".

Пример использования

Запрос агента

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

Полезная нагрузка инструмента

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

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

Возвращает исчерпывающую строку в формате Markdown, которая помогает пользователю обернуть свой код. Включает быстрый старт, инструкции по поиску, инструкции по оборачиванию с заполнителями, все доступные шаблоны для языка и ссылки на документацию SDK.

# Feature Flag Wrapping Guide: "new-checkout-flow"

**Language:** TypeScript
**Framework:** React

## Quick Start
[Recommended pattern with import and usage]

## How to Search for Existing Flag Patterns
[Step-by-step Grep instructions]

## How to Wrap Code with Feature Flag
[Wrapping instructions with examples]

## All Available Templates
[If-block, guard clause, hooks, ternary, etc.]

Настройка развёртывания флага

Инструмент set_flag_rollout настраивает стратегию flexibleRollout для окружения функционального флага. Он задаёт процент развёртывания, закрепление (stickiness) и необязательные варианты на уровне стратегии. Это не включает флаг; используйте 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. Он возвращает тип флага, статус включён/архивирован, настройку данных впечатлений (impression data) и сводку по окружениям с активными стратегиями и вариантами.

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

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

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

Используйте этот инструмент для очистки устаревших стратегий или для замены существующей стратегии путём удаления старой и настройки новой с помощью 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, тернарные выражения, предохранительные условия, хуки, декораторы, промежуточное ПО).
Удалить проверки флага, сохраняя правильный путь выполнения кода.
Очистить неиспользуемые импорты с учётом специфики языка.
Проверить изменения с помощью поиска после очистки и шагов тестирования.

Если 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"
}

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

Возвращает руководство в формате Markdown, охватывающее область очистки и сохраняемый путь, команды 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.

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

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

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

Возвращает первые 10 флагов функциональности в проекте 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, если он есть, поэтому вы можете вставить то же значение, которое ожидают большинство SDK Unleash.
UNLEASH_PAT: Персональный токен доступа (обязательно).
UNLEASH_DEFAULT_PROJECT: ID проекта по умолчанию, который должен использовать MCP (необязательно).

Флаги 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 проекта не существует. Подтвердите ID проекта в Unleash Admin UI.

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

Лицензия

MIT

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

Это целенаправленный проект с узкой областью. Вклады должны:

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