Unleash

Servidor MCP Unleash

Um servidor Model Context Protocol (MCP) com propósito definido para gerenciar feature flags do Unleash. Este servidor permite que assistentes de codificação baseados em LLM criem e gerenciem feature flags seguindo as melhores práticas do Unleash.

Para compartilhar feedback, entre no nosso Slack da comunidade ou abra uma issue no GitHub.

Visão geral

Este servidor MCP fornece ferramentas que se integram à API de Administração do Unleash, permitindo que assistentes de codificação baseados em IA possam:

• Criar feature flags com validação e tipagem adequadas.
• Detectar flags existentes para evitar duplicatas ou incentivar a reutilização.
• Avaliar mudanças para decidir quando uma feature flag é necessária.
• Transmitir progresso para visibilidade durante as operações.
• Tratar erros de forma elegante, com dicas úteis.
• Seguir as melhores práticas da documentação do Unleash.

Ferramentas disponíveis

O servidor MCP expõe as seguintes ferramentas:

• create_flag: Cria uma feature flag no Unleash.
• evaluate_change: Pontua o risco e recomenda o uso de feature flags.
• detect_flag: Descobre feature flags existentes para evitar duplicatas.
• wrap_change: Fornece orientação sobre como envolver uma mudança em uma feature flag.
• set_flag_rollout: Configura estratégias de rollout para uma feature flag (não ativa a flag).
• get_flag_state: Exibe os metadados de uma feature flag e suas estratégias de ativação.
• list_flags: Lista todas as feature flags em um projeto, com paginação e ordem de classificação opcionais.
• list_projects: Lista os projetos Unleash disponíveis para o token configurado, com paginação opcional.
• toggle_flag_environment: Ativa ou desativa uma feature flag em um ambiente.
• remove_flag_strategy: Exclui a estratégia de uma feature flag de um ambiente.
• cleanup_flag: Gera instruções para remover com segurança caminhos de código protegidos por flags.

Fluxo de trabalho principal

O fluxo de trabalho principal para um assistente de IA é projetado para ser:

1. evaluate_change: Primeiro, avalie uma mudança de código para ver se uma flag é necessária.
2. detect_flag: Isso geralmente é chamado automaticamente por evaluate_change para evitar a criação de flags duplicadas.
3. create_flag: Se uma nova flag for necessária, esta ferramenta a cria no Unleash.
4. wrap_change: Por fim, esta ferramenta fornece o código específico da linguagem para implementar a nova flag.

Consulte mais informações sobre as ferramentas do fluxo de trabalho principal na seção Referência de ferramentas.

Pré-requisitos

Antes de executar o servidor, você precisa do seguinte:

• Node.js 22 ou superior
• Gerenciador de pacotes pnpm ou npm
• Uma instância do Unleash (hospedada ou auto-hospedada)
• Um token de acesso pessoal com permissões para criar feature flags

Comece agora

Esta seção aborda as diferentes maneiras de instalar e executar o servidor MCP Unleash. Você pode seguir uma configuração para agentes (como Claude Code e Codex), executar o MCP como um processo independente usando npx, ou usar uma configuração de desenvolvimento local.

Configuração para agentes

Você pode adicionar o servidor MCP diretamente ao Claude Code ou Codex. As configurações do agente são específicas do caminho. Você deve executar o seguinte comando a partir do diretório raiz do projeto onde deseja usar o MCP.

Para 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

Para 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

Configuração remota para agentes (experimental)

Em vez de executar o servidor MCP localmente, você pode conectar-se diretamente ao servidor MCP remoto integrado da sua instância Unleash via HTTP. Isso usa o transporte Streamable HTTP — sem necessidade de processo local.

Observação: O MCP remoto é um recurso experimental que deve ser habilitado na sua instância Unleash. Entre em contato com a equipe do Unleash para ativá-lo.

OAuth

O fluxo OAuth abre seu navegador, permite que você faça login no Unleash e provisiona automaticamente um PAT de curta duração. Sem gerenciamento manual de tokens.

Para Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

Para Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

No primeiro uso, o cliente abrirá automaticamente seu navegador para login. Após a autenticação com o Unleash, um PAT é criado e usado para todas as solicitações subsequentes.

O PAT expira após 24 horas por padrão.

Token de Acesso Pessoal (PAT)

Use este método quando você já tiver um PAT ou precisar de acesso headless/não interativo (pipelines de CI, ambientes de desenvolvimento compartilhados, clientes que não suportam OAuth).

Para criar um PAT: faça login na sua instância Unleash, vá para Perfil > Tokens de Acesso Pessoal e crie um novo token.

Para Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

Para Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

A flag --header envia o PAT diretamente, ignorando completamente o fluxo OAuth.

Início rápido com npx

Você pode executar o servidor MCP como um processo independente sem clonar o repositório usando npx. Forneça a configuração por meio de variáveis de ambiente ou de um arquivo .env local no diretório onde você executa o comando:

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

A CLI suporta as mesmas flags da compilação local (por exemplo, --dry-run, --log-level).

Configuração de desenvolvimento local

Siga estas etapas para configurar o projeto para desenvolvimento local.

1. Instalar dependências

Clone o repositório e instale as dependências usando pnpm. O Corepack mantém todos na mesma versão do 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

2. Executar em modo de desenvolvimento diretamente do Claude ou Codex

Evite a saída de npm run e os banners de tsx watch porque qualquer stdout extra quebra o handshake do MCP. Duas opções silenciosas:

A) Usar JS compilado (mais confiável)

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) Usar TypeScript diretamente (sem compilação)

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"

Observações:

• node --import tsx é silencioso (sem saída de ciclo de vida do npm) e executa TS diretamente; use isso quando quiser evitar a compilação.
• node dist/index.js é a opção mais segura; combine-a com npm run build:watch para recompilar em mudanças enquanto o comando do agente permanece estável.
• Os logs permanecem na raiz do repositório (app.log, mcp-stdio.log), ambos ignorados pelo git.

Controle de registro

• LOG_LEVEL (preferido): controla o nível de detalhe do registro do aplicativo (debug, info, warn, error). O padrão é error quando não definido.
• Flag CLI --log-level: substituição opcional para LOG_LEVEL quando você quiser uma alteração pontual.
• APP_LOG_FILE (opcional): se definido, os logs do aplicativo são gravados neste arquivo (não em stdout). Se não definido, os logs vão para stderr.
• MCP_STDIO_LOG_FILE (opcional): se definido, stdin/stdout/stderr do MCP são registrados neste único arquivo com prefixos de canal. As mensagens do protocolo ainda fluem pelo stdout normalmente.

Atribuição do cliente

Quando um cliente MCP envia clientInfo durante a inicialização (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro e outros clientes compatíveis), o servidor enriquece o cabeçalho User-Agent nas chamadas de saída para a API de Administração do Unleash:

User-Agent: unleash-mcp/<version> (MCP Server; client=claude-code/1.2.3)

Isso faz com que os logs de eventos do Unleash respondam "qual ferramenta de IA criou ou alternou esta flag" sem nenhuma alteração no lado do servidor. Os valores de atribuição são sanitizados para não quebrarem o cabeçalho User-Agent.

Defina UNLEASH_MCP_CLIENT_ATTRIBUTION=off para desativar o enriquecimento e reverter para unleash-mcp/<version> (MCP Server). Padrão: ativado.

Referência de ferramentas

Esta seção descreve cada uma das ferramentas principais em detalhes, incluindo sua finalidade, parâmetros e saída.

Criar flag

A ferramenta create_flag cria uma nova feature flag no Unleash com validação abrangente e acompanhamento de progresso.

Quando usar

Use esta ferramenta quando você já determinou que uma feature flag é necessária (por exemplo, após executar evaluate_change) e estiver pronto para criá-la com o tipo e os metadados corretos.

Parâmetros

A ferramenta aceita os seguintes parâmetros:

• name (obrigatório): Nome exclusivo da feature flag dentro do projeto.
• type (obrigatório): Tipo da feature flag indicando ciclo de vida e intenção.
  • release: Rollouts graduais de recursos para usuários.
  • experiment: Testes A/B e experimentos.
  • operational: Comportamento do sistema e alternâncias operacionais.
  • kill-switch: Desligamentos de emergência ou disjuntores.
  • permission: Controla o acesso a recursos com base em funções ou direitos de usuário.
• description (obrigatório): Explicação clara do que a flag controla e por que ela existe.
• projectId (opcional): Projeto de destino (o padrão é UNLEASH_DEFAULT_PROJECT).
• impressionData (opcional): Ativa o rastreamento de análises (o padrão é falso).

Exemplo de uso

Prompt do agente

Use create_flag with:
- name: "new-checkout-flow"
- type: "release"
- description: "Gradual rollout of the redesigned checkout experience"
- projectId: "ecommerce"

Payload da ferramenta

{
  "name": "new-checkout-flow",
  "type": "release",
  "description": "Gradual rollout of the redesigned checkout experience with improved conversion tracking",
  "projectId": "ecommerce",
  "impressionData": true
}

Saída da ferramenta

Em caso de sucesso, a ferramenta retorna um objeto JSON contendo a URL da nova feature flag na interface de administração do Unleash, um link de recurso MCP para acesso programático, o carimbo de data/hora da criação e os detalhes da configuração.

Avaliar mudança

A ferramenta evaluate_change avalia se uma mudança de código deve estar atrás de uma feature flag. Ela examina a estrutura, o contexto e o risco potencial da mudança e retorna uma recomendação com explicação e próximos passos.

Quando usar

Use evaluate_change no início de um recurso ou modificação quando quiser entender se o trabalho requer uma feature flag. Esta ferramenta também é útil quando você não tem certeza de qual tipo de flag usar ou deseja orientação sobre o planejamento do rollout.

Como funciona

A ferramenta retorna orientação detalhada formatada em markdown para o assistente LLM com base nas melhores práticas do Unleash.

A orientação inclui:

• Detecção de flag pai: Verifica se o código já está protegido por flags existentes.
• Avaliação de risco: Analisa padrões de código para identificar operações arriscadas.
• Avaliação do tipo de código: Classifica a mudança (por exemplo, teste, configuração, recurso ou correção de bug).
• Recomendação: Sugere se deve criar uma flag, usar uma flag existente ou pular a flag.
• Próximas ações: Fornece instruções específicas sobre o que fazer a seguir.

Quando evaluate_change determina que uma flag é necessária, ele fornece instruções explícitas para:

1. Chamar a ferramenta create_flag para criar a feature flag.
2. Chamar a ferramenta wrap_change para obter orientação de envolvimento de código específica da linguagem.
3. Implementar o código envolvido seguindo os padrões detectados.

O processo de avaliação

A ferramenta segue um processo de avaliação claro:

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)

Avaliação de risco

A ferramenta usa padrões agnósticos de linguagem para pontuar o risco:

• Risco crítico (Pontuação +5): Por exemplo, autenticação, pagamentos, segurança e operações de banco de dados.
• Risco alto (Pontuação +3): Por exemplo, mudanças de API, serviços externos ou novas classes.
• Risco médio (Pontuação +2): Por exemplo, operações assíncronas ou gerenciamento de estado.
• Risco baixo (Pontuação +1): Por exemplo, correções de bugs, refatorações ou pequenas mudanças.

As pontuações se acumulam entre as categorias correspondentes. O total mapeia para um nível de risco:

• Crítico: Pontuação ≥ 5
• Alto: Pontuação ≥ 3
• Médio: Pontuação ≥ 2
• Baixo: Pontuação < 2

A saída inclui uma pontuação de confidence (0-1) representando a certeza autoavaliada do LLM, que aumenta com mais contexto fornecido.

Uma categoria excluída cobre arquivos que não precisam de feature flags independentemente do conteúdo: arquivos de teste (*.test.ts, *_test.go, etc.), arquivos de configuração (*.config.js, .env, *.yaml) e arquivos de documentação (*.md, docs/**). Mudanças limitadas a arquivos excluídos não acionarão uma recomendação de flag.

As definições completas de padrões, incluindo palavras-chave por categoria, globs de arquivos, padrões de código e raciocínio, estão em src/evaluation/riskPatterns.ts.

Detecção de flag pai

A ferramenta procura padrões comuns entre linguagens, como:

• Condicionais: if (isEnabled('flag')), if client.is_enabled('flag'):
• Atribuições: const enabled = useFlag('flag')
• Hooks: const enabled = useFlag('flag') → {enabled && <Component />}
• Guardas: if (!isEnabled('flag')) return;
• Wrappers: withFeatureFlag('flag', () => {...})

Parâmetros

Todos os parâmetros são opcionais, mas mais contexto leva a melhores recomendações:

• repository (string): Nome ou caminho do repositório.
• branch (string): Nome do branch atual.
• files (array): Lista de arquivos sendo alterados.
• description (string): Descrição da alteração.
• riskLevel (enum): low, medium, high ou critical, conforme avaliado pelo usuário.
• codeContext (string): Código ao redor para detecção do flag pai.

Exemplo de uso

Prompt do agente

Uso simples onde você deixa o agente coletar o contexto:

Use evaluate_change to help me determine if I need a feature flag

Instruções explícitas:

Use evaluate_change with:
- description: "Add Stripe payment processing"
- riskLevel: "high"

Payload da ferramenta

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

Saída da ferramenta

Retorna um objeto JSON com o resultado da avaliação, incluindo um booleano needsFlag, um recommendation (ex.: "create_new"), um nome de flag sugerido, nível de risco e um explanation detalhado.

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

Detectar flag

A ferramenta detect_flag encontra flags de funcionalidade existentes no código para que você possa reutilizá-los em vez de criar duplicatas. Esta ferramenta é integrada automaticamente ao fluxo de trabalho evaluate_change, mas também pode ser usada manualmente.

Quando usar

Use esta ferramenta antes de criar um novo flag de funcionalidade ou durante a avaliação de código para verificar se já existem flags que possam cobrir seu caso de uso. Isso ajuda a evitar duplicação de flags.

Como funciona

A ferramenta retorna instruções abrangentes de busca e usa múltiplas estratégias de detecção:

• Detecção baseada em arquivos: Busca nos arquivos que você está modificando por flags existentes.
• Análise do histórico do Git: Procura por flags adicionados recentemente no histórico de commits.
• Correspondência semântica de nomes: Compara descrições com nomes de flags existentes.
• Análise de contexto de código: Inspeciona o código ao redor da alteração.

A ferramenta então segue um processo de pontuação:

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

Níveis de confiança

A ferramenta retorna candidatos com pontuações de confiança:

• Alta ≥0.7: Correspondência forte; a reutilização é recomendada.
• Média 0.4-0.7: Possível correspondência; revise manualmente.
• Baixa <0.4: Correspondência fraca; provavelmente crie um novo flag.

Parâmetros

• description (obrigatório): Descrição da alteração ou funcionalidade. Por exemplo, "payment processing with Stripe", "new checkout flow".
• files (opcional): Arquivos sendo modificados. Por exemplo, ["src/payments/stripe.ts", "src/checkout/flow.ts"].
• codeContext (opcional): Código próximo para verificar flags.

Exemplo de uso

Prompt do agente

Verifique se há flags existentes antes de criar um flag:

Use detect_flag with description "payment processing with Stripe"

Integrado automaticamente na avaliação:

Use evaluate_change - automatically searches for existing flags

Payload da ferramenta

{
  "description": "payment processing with Stripe",
  "files": ["src/payments/stripe.ts"]
}

Saída da ferramenta

Retorna um objeto JSON indicando se um flag foi encontrado. Se flagFound for verdadeiro, inclui um objeto candidate com o nome do flag, localização, pontuação de confiança e o motivo da correspondência.

Correspondência encontrada:

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

Nenhuma correspondência encontrada:

{
  "flagFound": false,
  "candidate": null
}

Envolver alteração

A ferramenta wrap_change gera trechos de código específicos por linguagem e orientações para envolver código com flags de funcionalidade. Ela ajuda LLMs e desenvolvedores a seguir padrões existentes no código e usar flags corretamente.

Quando usar

Use esta ferramenta depois de criar um flag de funcionalidade (com create_flag) e precisar implementá-lo no seu código. É especialmente útil quando você quer garantir que está seguindo os padrões existentes do código ou precisa de exemplos específicos de framework (ex.: React, Django).

Como funciona

Esta ferramenta é a etapa final no fluxo de trabalho evaluate_change → create_flag → wrap_change.

A ferramenta fornece as seguintes orientações na resposta:

1. Instruções de busca: Guia passo a passo para encontrar padrões de flags existentes no seu código usando grep.
2. Detecção de padrões: Identifica padrões comuns (por exemplo, imports, nomes de variáveis de cliente, nomes de métodos ou estilos de envolvimento).
3. Modelos padrão: Trechos de código de fallback se nenhum padrão for encontrado.
4. Exemplos específicos de framework: Padrões especializados para React, Express, Django e outros.
5. Múltiplos padrões: Blocos if, cláusulas de guarda, hooks, decorators, middleware e mais.

Linguagens e frameworks suportados:

• TypeScript/JavaScript: Node.js, React Hooks, middleware Express.
• Python: FastAPI, Django, decorators Flask.
• Go: Blocos if padrão, middleware HTTP.
• Ruby: Controllers Rails.
• PHP: Controllers Laravel.
• C#: Controllers .NET/ASP.NET.
• Java: Spring Boot.
• Rust: Handlers Actix/Rocket.

Parâmetros

• flagName (obrigatório): Nome do flag de funcionalidade para envolver o código. Por exemplo: "new-checkout-flow" ou "stripe-integration".
• language (opcional): Linguagem de programação (detectada automaticamente a partir de fileName se não for fornecida). Suportadas: typescript, javascript, python, go, ruby, php, csharp, java, rust
• fileName (opcional): Nome do arquivo sendo modificado (ajuda a detectar a linguagem). Por exemplo: "checkout.ts", "payment.py" ou "handler.go".
• codeContext (opcional): Código ao redor para ajudar a detectar padrões existentes.
• frameworkHint (opcional): Framework para modelos especializados. Por exemplo, "React", "Express", "Django", "Rails" ou "Spring Boot".

Exemplo de uso

Prompt do agente

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

Payload da ferramenta

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

Saída da ferramenta

Retorna uma string abrangente formatada em Markdown que orienta o usuário sobre como envolver seu código. Isso inclui um guia de início rápido, instruções de busca, instruções de envolvimento com placeholders, todos os modelos disponíveis para a linguagem e links para a documentação do 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.]

Definir rollout do flag

A ferramenta set_flag_rollout configura uma estratégia flexibleRollout em um ambiente de flag de funcionalidade. Ela define a porcentagem de rollout, a aderência (stickiness) e variantes opcionais no nível da estratégia. Isso não ativa o flag; use toggle_flag_environment para ativá-lo.

Quando usar

Use esta ferramenta depois de criar um flag com create_flag para configurar como o tráfego será distribuído antes de ativá-lo. Também use para atualizar uma porcentagem de rollout existente ou adicionar variantes.

Parâmetros

• featureName (obrigatório): Nome do flag de funcionalidade.
• environment (obrigatório): Ambiente de destino (por exemplo, "production", "development").
• rolloutPercentage (obrigatório): Porcentagem do tráfego que receberá a funcionalidade (0-100).
• projectId (opcional): ID do projeto (padrão: UNLEASH_DEFAULT_PROJECT).
• groupId (opcional): Chave de agrupamento de aderência (padrão: nome da funcionalidade).
• stickiness (opcional): Campo de aderência (padrão: "default").
• title (opcional): Título descritivo para a estratégia.
• disabled (opcional): Criar a estratégia em estado desabilitado (padrão: falso).
• variants (opcional): Lista de variantes no nível da estratégia, cada uma com name, weight (0-1000), weightType opcional ("variable" ou "fix"), stickiness e payload ({type, value}).

Exemplo de uso

Prompt do agente

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

Payload da ferramenta

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

Saída da ferramenta

Retorna uma confirmação com a porcentagem configurada, um link para o flag na interface administrativa do Unleash, a URL das estratégias da API administrativa e um link de recurso MCP para o flag.

Obter estado do flag

A ferramenta get_flag_state busca os metadados atuais de um flag de funcionalidade e as estratégias de ambiente da API administrativa do Unleash. Ela retorna o tipo do flag, status ativado/arquivado, configuração de dados de impressão e um resumo por ambiente das estratégias e variantes ativas.

Quando usar

Use esta ferramenta para inspecionar um flag antes de modificá-lo, para verificar quantas estratégias estão ativas entre ambientes ou para encontrar IDs de estratégias antes de chamar remove_flag_strategy.

Parâmetros

• featureName (obrigatório): Nome do flag de funcionalidade.
• projectId (opcional): ID do projeto (padrão: UNLEASH_DEFAULT_PROJECT).
• environment (opcional): Filtrar resultados para um único ambiente (sem diferenciar maiúsculas de minúsculas).

Exemplo de uso

Prompt do agente

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

Payload da ferramenta

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

Saída da ferramenta

Retorna um resumo em texto do flag (tipo, status ativado/arquivado/dados de impressão, projeto, resumos de ambiente com contagens de estratégias) junto com links de interface e API. A saída estruturada inclui o objeto completo da funcionalidade com todos os ambientes e detalhes de estratégias.

Listar flags

A ferramenta list_flags enumera os flags de funcionalidade em um projeto e retorna um inventário estruturado com paginação e ordem de classificação. Flags ativos e arquivados são retornados separadamente: chame-a uma vez com archived: false (o padrão) e uma vez com archived: true para montar um inventário completo para fluxos de auditoria.

Quando usar

Use esta ferramenta quando um agente precisar descobrir quais flags já existem, por exemplo, para auditar um projeto, encontrar candidatos para limpeza ou construir contexto antes de criar ou envolver um flag. É o equivalente invocável por agente do recurso unleash://projects/{projectId}/feature-flags (veja Recursos MCP).

Parâmetros

• projectId (opcional): Projeto do qual listar flags (padrão: UNLEASH_DEFAULT_PROJECT; resolvido automaticamente quando existe um único projeto).
• archived (opcional): true para listar flags arquivados em vez de ativos. Padrão: false. Flags ativos e arquivados não podem ser retornados na mesma resposta.
• limit (opcional): Máximo de flags por página (padrão: tamanho de página do servidor, normalmente 50).
• order (opcional): Ordem de classificação por nome do flag, asc ou desc (padrão: asc).
• offset (opcional): Número de flags a pular para paginação (padrão: 0).

Exemplo de uso

Prompt do agente

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

Payload da ferramenta

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

Saída da ferramenta

Retorna um resumo em texto mais conteúdo estruturado com projectId, archived, order, limit, offset, nextOffset, totalFlags e o array flags (cada um com nome, tipo, projeto, status de arquivamento e links). Use nextOffset para paginar por projetos grandes.

Listar projetos

A ferramenta list_projects enumera os projetos Unleash disponíveis para o token configurado, com paginação e ordem de classificação.

Quando usar

Use esta ferramenta quando o projeto de destino for desconhecido ou quando um agente precisar escolher um projeto antes de listar ou criar flags. É o equivalente invocável por agente do recurso unleash://projects (veja Recursos MCP).

Parâmetros

• limit (opcional): Máximo de projetos por página (padrão: tamanho de página do servidor, normalmente 20).
• order (opcional): Ordem de classificação por tempo de criação do projeto, asc ou desc (padrão: desc, mais recentes primeiro).
• offset (opcional): Número de projetos a pular para paginação (padrão: 0).

Exemplo de uso

Prompt do agente

Use list_projects to see which projects are available.

Payload da ferramenta

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

Saída da ferramenta

Retorna um resumo em texto mais conteúdo estruturado com order, limit, offset, nextOffset, totalProjects e o array projects (cada um com id, nome, descrição, modo, tempo de criação e URL).

Alternar ambiente do flag

A ferramenta toggle_flag_environment ativa ou desativa um flag de funcionalidade em um ambiente específico. Para rollouts graduais, configure uma estratégia com set_flag_rollout antes de ativar.

Quando usar

Use esta ferramenta para ativar um flag depois de configurar uma estratégia de rollout ou para desativar um flag durante um incidente ou após concluir um rollout.

Parâmetros

• featureName (obrigatório): Nome do feature flag.
• environment (obrigatório): Ambiente para alternar (por exemplo, "production").
• enabled (obrigatório): true para habilitar, false para desabilitar.
• projectId (opcional): ID do projeto (padrão: UNLEASH_DEFAULT_PROJECT).

Exemplo de uso

Prompt do agente

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

Payload da ferramenta

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

Saída da ferramenta

Retorna uma confirmação do novo estado, um resumo do ambiente (habilitado/desabilitado, contagem de estratégias) e links para o flag na interface administrativa do Unleash e na API administrativa.

Remover estratégia de flag

A ferramenta remove_flag_strategy exclui uma configuração de estratégia de um ambiente de feature flag. Use get_flag_state primeiro para descobrir o ID da estratégia.

Quando usar

Use esta ferramenta para limpar estratégias obsoletas ou para substituir uma estratégia existente removendo a antiga e configurando uma nova com set_flag_rollout.

Parâmetros

• featureName (obrigatório): Nome do feature flag.
• environment (obrigatório): Ambiente do qual remover a estratégia.
• strategyId (obrigatório): ID da estratégia a ser removida (encontre-o via get_flag_state).
• projectId (opcional): ID do projeto (padrão: UNLEASH_DEFAULT_PROJECT).

Exemplo de uso

Prompt do agente

Use get_flag_state to find strategy IDs for "new-checkout-flow" in production,
then use remove_flag_strategy to delete the old strategy.

Payload da ferramenta

{
  "featureName": "new-checkout-flow",
  "environment": "production",
  "strategyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "projectId": "ecommerce"
}

Saída da ferramenta

Retorna uma confirmação da remoção, uma contagem das estratégias restantes no ambiente e links para o flag na interface administrativa do Unleash e na API administrativa.

Limpeza de flag

A ferramenta cleanup_flag gera instruções passo a passo para remover com segurança o código do feature flag do codebase, preservando o caminho de código desejado.

Quando usar

Use esta ferramenta quando um feature flag tiver concluído seu ciclo de vida:

• Após um rollout atingir 100% e o flag não for mais necessário.
• Ao descontinuar um recurso experimental (preserve o caminho desabilitado).
• Ao remover um kill switch que não é mais necessário.
• Durante a limpeza de dívida técnica de flags antigos.

Como funciona

A ferramenta retorna instruções abrangentes de limpeza que orientam o LLM através de:

1. Encontrar todas as ocorrências do flag usando padrões de grep.
2. Identificar padrões de uso (blocos if-else, expressões ternárias, cláusulas de guarda, hooks, decorators, middleware).
3. Remover as verificações do flag preservando o caminho de código correto.
4. Limpar imports não utilizados com orientação específica para a linguagem.
5. Verificar as alterações com etapas de busca pós-limpeza e testes.

Se preservePath não for fornecido, a ferramenta retorna instruções para perguntar ao usuário qual caminho manter antes de prosseguir.

Parâmetros

• flagName (obrigatório): Nome do feature flag a ser removido (por exemplo, "new-checkout-flow").
• preservePath (opcional): "enabled" para manter o caminho de código com o flag ativado (típico para rollouts concluídos) ou "disabled" para manter o caminho com o flag desativado (para experimentos removidos). Se omitido, a ferramenta solicita que você pergunte ao usuário.
• files (opcional): Arquivos específicos para limpar. Se omitido, pesquisa todo o codebase.
• language (opcional): Linguagem de programação para orientação especializada de limpeza de imports (por exemplo, "typescript", "python"). Detectada automaticamente a partir de files se não for fornecida.

Exemplo de uso

Prompt do agente

Use cleanup_flag with:
- flagName: "new-checkout-flow"
- preservePath: "enabled"

Payload da ferramenta

{
  "flagName": "new-checkout-flow",
  "preservePath": "enabled",
  "files": ["src/components/checkout.tsx", "src/api/checkout.ts"],
  "language": "typescript"
}

Saída da ferramenta

Retorna um guia em markdown cobrindo o escopo da limpeza e o caminho preservado, comandos grep para encontrar todas as ocorrências, instruções de remoção por padrão, limpeza de imports específica da linguagem e etapas de verificação pós-limpeza (nova busca, execução de testes, revisão manual).

Recursos MCP

O servidor registra recursos MCP para leitura de dados de projetos e feature flags. Todos os recursos retornam JSON e são armazenados em cache por 60 segundos.

Template de URI	Descrição
unleash://projects{?limit,order,offset}	Lista projetos. Tamanho de página padrão: 20, ordenados por data de criação (mais recentes primeiro).
unleash://projects/{projectId}/feature-flags{?limit,order,offset}	Lista flags em um projeto. Tamanho de página padrão: 50, ordenados alfabeticamente.
unleash://projects/{projectId}/feature-flags/{flagName}	Metadados de um único feature flag.

Os dois primeiros templates aceitam parâmetros de consulta opcionais: limit (tamanho da página), order (asc ou desc) e offset (início da paginação). As respostas incluem campos fetchedAt, cached, totalProjects ou totalFlags e nextOffset.

Recursos vs. ferramentas: Os recursos MCP são controlados pelo aplicativo, portanto muitos clientes só os exibem por meio de interface orientada pelo usuário (por exemplo, menções a #) e não permitem que o agente chame resources/read por conta própria. Quando um agente precisar enumerar projetos ou flags programaticamente, use as ferramentas list_projects e list_flags, que retornam os mesmos dados por meio da interface de ferramentas. A análise de inventário detect_flag passa pelo mesmo caminho.

Exemplo de leitura de recurso

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

Retorna os primeiros 10 feature flags no projeto ecommerce, ordenados alfabeticamente, com metadados de paginação.

Arquitetura

O servidor segue um design focado e orientado a propósito.

Estrutura

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

Princípios de design

• Superfície enxuta: Apenas os endpoints necessários para as capacidades principais.
• Orientado a propósito: Cada módulo serve a um propósito específico e bem definido.
• Validação explícita: Esquemas Zod validam todas as entradas antes das chamadas de API.
• Normalização de erros: Todos os erros convertidos para o formato {code, message, hint}.
• Streaming de progresso: Operações de longa duração fornecem visibilidade.
• Integração de melhores práticas: Orientação da documentação do Unleash incorporada nas descrições das ferramentas.

Configuração

Esta seção fornece uma referência rápida para todas as opções de configuração.

Variáveis de ambiente:

• UNLEASH_BASE_URL: URL da sua instância Unleash (obrigatório). Tanto https://your-instance.getunleash.io quanto https://your-instance.getunleash.io/api são aceitos — o servidor normaliza uma barra final /api se presente, para que você possa colar o mesmo valor que a maioria dos SDKs do Unleash espera.
• UNLEASH_PAT: Token de acesso pessoal (obrigatório).
• UNLEASH_DEFAULT_PROJECT: O ID de projeto padrão que o MCP deve usar (opcional).

Flags de CLI:

• --dry-run: Simula operações sem fazer chamadas de API reais.
• --log-level: Define o nível de verbosidade do log (debug, info, warn, error).

Melhores práticas

Este servidor incentiva as melhores práticas do Unleash da documentação oficial:

Ciclo de vida do flag

1. Crie com intenção: Escolha o tipo de flag certo para sinalizar o propósito.
2. Documente claramente: Escreva descrições que expliquem o "porquê".
3. Planeje a limpeza: Feature flags são temporários; planeje sua remoção.
4. Monitore o uso: Habilite dados de impressão para flags importantes.

Tipos de flag

• Flags de release: Para rollouts graduais de recursos (remova após o rollout completo).
• Flags de experimento: Para testes A/B (remova após a análise).
• Flags operacionais: Para comportamento do sistema (maior vida útil, revise periodicamente).
• Kill switches: Para controles de emergência (mantenha até o recurso estar estável).
• Flags de permissão: Para controle de acesso (maior vida útil, revise permissões).

Convenções de nomenclatura

• Use kebab-case: new-checkout-flow
• Seja descritivo: enable-ai-recommendations em vez de flag1.
• Inclua o escopo quando necessário: mobile-push-notifications.

Referência da API

Este servidor usa a API administrativa do Unleash. Para documentação completa da API, consulte:

• Especificação OpenAPI da API administrativa do Unleash
• Documentação da API do Unleash

Endpoints usados

• GET /api/admin/projects - Listar projetos
• GET /api/admin/projects/{projectId}/features - Listar feature flags
• POST /api/admin/projects/{projectId}/features - Criar feature flag
• GET /api/admin/projects/{projectId}/features/{featureName} - Obter detalhes do flag
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - Adicionar estratégia de rollout
• DELETE /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies/{strategyId} - Remover estratégia
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/on - Habilitar flag
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - Desabilitar flag

Solução de problemas

Problemas de configuração

Erro: "UNLEASH_BASE_URL deve ser uma URL válida": Certifique-se de que sua URL base esteja completa, incluindo o protocolo. Por exemplo, https://app.unleash-hosted.com/instance. Remova quaisquer barras finais.

Erro: "UNLEASH_PAT é obrigatório": Verifique se seu arquivo .env existe e contém UNLEASH_PAT={{your-personal-access-token}}. Verifique se o token é válido no Unleash.

Problemas de API

Erro: "HTTP_401": Seu token de acesso pessoal pode ser inválido ou ter expirado. Gere um novo token em Perfil > Ver configurações do perfil > Tokens de API pessoais > Novo token.

Erro: "HTTP_403": Seu token não tem permissão para criar flags neste projeto. Revise sua função e permissões no Unleash.

Erro: "HTTP_404": O ID do projeto não existe. Confirme o ID do projeto na interface administrativa do Unleash.

Erro: "HTTP_409": Um flag com este nome já existe no projeto. Use um nome diferente ou reutilize o flag existente.

Licença

MIT

Contribuindo

Este é um projeto orientado a propósito com um escopo focado. As contribuições devem:

• Alinhar-se com a superfície de ferramentas existente e o modelo de recursos MCP.
• Manter a arquitetura enxuta e orientada a propósito.
• Seguir as melhores práticas do Unleash.
• Incluir documentação clara.