Unleash MCP Server

Unleash MCP Server

Um servidor Model Context Protocol (MCP) orientado a propósito para gerenciar Unleash feature flags. 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, participe do nosso Slack da comunidade ou abra uma issue no GitHub.

Visão geral

Este servidor MCP fornece ferramentas que se integram com a API Admin do Unleash, permitindo que assistentes de codificação de IA:

• Criem feature flags com validação e tipagem adequadas.
• Detectem flags existentes para evitar duplicatas ou incentivar a reutilização.
• Avaliem mudanças para decidir quando uma feature flag é necessária.
• Transmitam o progresso para visibilidade durante as operações.
• Tratem erros de forma elegante com dicas úteis.
• Sigam 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 flag.
• 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: Expõe 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 ordenaçã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 sinalizados.

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: Finalmente, esta ferramenta fornece o código específico da linguagem para implementar a nova flag.

Veja 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 do 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 do agente

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 do agente (experimental)

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

Nota: O MCP remoto é um recurso experimental que deve ser habilitado na sua instância Unleash. Entre em contato com a equipe Unleash para habilitá-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. Nenhum gerenciamento manual de token necessário.

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 autenticar 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 desenvolvedor 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 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 --log-level debug

A CLI suporta as mesmas flags que a 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 [email protected] --activate

pnpm install

2. Executar no modo dev diretamente do Claude ou Codex

Evite a saída npm run e os banners tsx watch porque qualquer stdout extra quebra o handshake 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"

Notas:

• node --import tsx é silencioso (sem saída do ciclo de vida do npm) e executa TS diretamente; use isso quando quiser evitar a compilação.
• node dist/index.js é a escolha mais segura; combine-o com npm run build:watch para recompilar nas 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 logging

• LOG_LEVEL (preferencial): controla a verbosidade do log da aplicação (debug, info, warn, error). O padrão é error quando não definido.
• Flag CLI --log-level: substituição opcional para LOG_LEVEL quando você deseja uma alteração pontual.
• APP_LOG_FILE (opcional): se definido, os logs da aplicação são gravados neste arquivo (não 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 desviados para este único arquivo com prefixos de canal. As mensagens do protocolo ainda fluem normalmente pelo stdout.

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 da API Admin 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 que não possam quebrar o cabeçalho User-Agent.

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

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 rastreamento 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 está pronto para criá-la com o tipo e 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 de feature flag indicando o ciclo de vida e a 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 do usuário.
• description (obrigatório): Explicação clara do que a flag controla e por que ela existe.
• projectId (opcional): Projeto de destino (padrão UNLEASH_DEFAULT_PROJECT).
• impressionData (opcional): Habilitar rastreamento analítico (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"

Carga útil 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 UI Admin do Unleash, um link de recurso MCP para acesso programático, carimbo de data/hora de criação e detalhes de 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 uma 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 de rollout.

Como funciona

A ferramenta retorna orientação detalhada e 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, 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 independentes 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, alterações 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 alterações.

As pontuações se acumulam nas 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 confidence (0-1) representando a certeza autoavaliada do LLM, que aumenta com mais contexto fornecido.

Uma categoria excluída abrange 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 arquivo, 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 em várias 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 quanto mais contexto, melhores as recomendações:

• repository (string): Nome ou caminho do repositório.
• branch (string): Nome da 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 de flag pai.

Exemplo de uso

Prompt do agente

Uso simples onde você deixa o agente reunir 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"

Carga 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 na base de código para que você possa reutilizá-las 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 uma nova flag de funcionalidade ou durante a avaliação de código para verificar flags existentes que já possam cobrir seu caso de uso. Isso ajuda a evitar duplicação de flags.

Como funciona

A ferramenta retorna instruções de busca abrangentes 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 flags adicionadas recentemente no histórico de commits.
• Correspondência semântica de nomes: Combina 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; reutilização recomendada.
• Média 0.4-0.7: Correspondência possível; revisar manualmente.
• Baixa <0.4: Correspondência fraca; provavelmente criar uma nova 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 escanear em busca de flags.

Exemplo de uso

Prompt do agente

Verificar flags existentes antes de criar uma flag:

Use detect_flag with description "payment processing with Stripe"

Integrado automaticamente na avaliação:

Use evaluate_change - automatically searches for existing flags

Carga da ferramenta

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

Saída da ferramenta

Retorna um objeto JSON indicando se uma flag foi encontrada. Se flagFound for verdadeiro, inclui um objeto candidate com o nome da 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 da linguagem e orientações para envolver código com flags de funcionalidade. Ela ajuda LLMs e desenvolvedores a seguir padrões existentes na base de código e usar flags corretamente.

Quando usar

Use esta ferramenta após criar uma flag de funcionalidade (com create_flag) e precisar implementá-la em seu código. É especialmente útil quando você quer garantir que está seguindo os padrões existentes na base de 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 em sua resposta:

1. Instruções de busca: Guia passo a passo para encontrar padrões de flag existentes na sua base de 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 alternativos 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, decoradores, middleware e mais.

Linguagens e frameworks suportados:

• TypeScript/JavaScript: Node.js, React Hooks, middleware Express.
• Python: FastAPI, Django, decoradores 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 da flag de funcionalidade para envolver o código. Por exemplo: "new-checkout-flow" ou "stripe-integration".
• language (opcional): Linguagem de programação (detectada automaticamente de fileName se não fornecida). Suportado: 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"

Carga 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 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 lançamento gradual da flag

A ferramenta set_flag_rollout configura uma estratégia flexibleRollout em um ambiente de flag de funcionalidade. Ela define a porcentagem de lançamento, aderência e variantes opcionais no nível da estratégia. Isso não ativa a flag; use toggle_flag_environment para ligá-la.

Quando usar

Use esta ferramenta após criar uma flag com create_flag para configurar como o tráfego é distribuído antes de ativá-la. Use também para atualizar uma porcentagem de lançamento existente ou adicionar variantes.

Parâmetros

• featureName (obrigatório): Nome da flag de funcionalidade.
• environment (obrigatório): Ambiente alvo (por exemplo, "production", "development").
• rolloutPercentage (obrigatório): Porcentagem de tráfego para receber a funcionalidade (0-100).
• projectId (opcional): ID do projeto (padrão UNLEASH_DEFAULT_PROJECT).
• groupId (opcional): Chave de bucketing 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

Carga 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 a flag na UI de Administração do Unleash, a URL de estratégias da API de Administração e um link de recurso MCP para a flag.

Obter estado da flag

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

Quando usar

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

Parâmetros

• featureName (obrigatório): Nome da flag de funcionalidade.
• projectId (opcional): ID do projeto (padrão UNLEASH_DEFAULT_PROJECT).
• environment (opcional): Filtrar resultados para um único ambiente (não sensível a maiúsculas/minúsculas).

Exemplo de uso

Prompt do agente

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

Carga da ferramenta

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

Saída da ferramenta

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

Listar flags

A ferramenta list_flags enumera as flags de funcionalidade em um projeto e retorna um inventário estruturado com paginação e ordem de classificação. Flags ativas e arquivadas são retornadas 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 trabalho de auditoria.

Quando usar

Use esta ferramenta quando um agente precisar descobrir quais flags já existem, por exemplo, para auditar um projeto, encontrar candidatas para limpeza ou construir contexto antes de criar ou envolver uma 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 arquivadas em vez de ativas. Padrão false. Flags ativas e arquivadas não podem ser retornadas na mesma resposta.
• limit (opcional): Máximo de flags por página (padrão: tamanho de página do servidor, tipicamente 50).
• order (opcional): Ordem de classificação por nome da 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

Carga 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 arquivado e links). Use nextOffset para paginar 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 alvo 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, tipicamente 20).
• order (opcional): Ordem de classificação por data de criação do projeto, asc ou desc (padrão: desc, mais recente 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.

Carga 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, data de criação e URL).

Alternar ambiente da flag

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

Quando usar

Use esta ferramenta para ligar uma flag após configurar uma estratégia de lançamento, ou para desativar uma flag durante um incidente ou após concluir um lançamento.

Parâmetros

• featureName (obrigatório): Nome da flag de funcionalidade.
• environment (obrigatório): Ambiente a ser alternado (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

Carga útil 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 a flag na UI de Administração do Unleash e na API de Administração.

Remover estratégia da flag

A ferramenta remove_flag_strategy exclui uma configuração de estratégia de um ambiente de flag de funcionalidade. 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 da flag de funcionalidade.
• environment (obrigatório): Ambiente do qual remover a estratégia.
• strategyId (obrigatório): ID da estratégia a ser removida (encontre 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.

Carga útil 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 a flag na UI de Administração do Unleash e na API de Administração.

Limpar flag

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

Quando usar

Use esta ferramenta quando uma flag de funcionalidade tiver completado seu ciclo de vida:

• Após um lançamento gradual atingir 100% e a flag não for mais necessária.
• Ao descontinuar uma funcionalidade experimental (preservar o caminho desabilitado).
• Ao remover um kill switch que não é mais necessário.
• Durante a limpeza de débito técnico de flags antigas.

Como funciona

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

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

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 da flag de funcionalidade a ser removida (por exemplo, "new-checkout-flow").
• preservePath (opcional): "enabled" para manter o caminho de código com a flag ativada (típico para lançamentos concluídos), ou "disabled" para manter o caminho com a flag desativada (para experimentos removidos). Se omitido, a ferramenta solicita que você pergunte ao usuário.
• files (opcional): Arquivos específicos para limpar. Se omitido, busca em toda a base de código.
• language (opcional): Linguagem de programação para orientação especializada de limpeza de importações (por exemplo, "typescript", "python"). Detectada automaticamente de files se não fornecida.

Exemplo de uso

Prompt do agente

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

Carga útil 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 importações específica da linguagem e etapas de verificação pós-limpeza (refazer busca, executar testes, revisão manual).

Recursos MCP

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

Modelo de URI	Descrição
unleash://projects{?limit,order,offset}	Listar projetos. Tamanho de página padrão: 20, ordenado por data de criação (mais recente primeiro).
unleash://projects/{projectId}/feature-flags{?limit,order,offset}	Listar flags em um projeto. Tamanho de página padrão: 50, ordenado alfabeticamente.
unleash://projects/{projectId}/feature-flags/{flagName}	Metadados de uma única flag de funcionalidade.

Os dois primeiros modelos 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 os campos fetchedAt, cached, totalProjects ou totalFlags e nextOffset.

Recursos vs. ferramentas: Recursos MCP são controlados pela aplicação, então muitos clientes só os expõem através de UI acionada pelo usuário (por exemplo, menções #) e não permitem que o agente chame resources/read por conta própria. Quando um agente precisa enumerar projetos ou flags programaticamente, use as ferramentas list_projects e list_flags, que retornam os mesmos dados através da interface de ferramenta. A análise de inventário detect_flag segue o mesmo caminho.

Exemplo de leitura de recurso

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

Retorna as primeiras 10 flags de funcionalidade no projeto ecommerce, ordenadas 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 reduzida: 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: Schemas 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ções da documentação do Unleash incorporadas 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). Ambos https://your-instance.getunleash.io e https://your-instance.getunleash.io/api são aceitos — o servidor normaliza uma barra final /api se presente, então você pode colar o mesmo valor que a maioria dos SDKs Unleash espera.
• UNLEASH_PAT: Token de acesso pessoal (obrigatório).
• UNLEASH_DEFAULT_PROJECT: O ID do projeto padrão que o MCP deve usar (opcional).

Flags CLI:

• --dry-run: Simular operações sem fazer chamadas de API reais.
• --log-level: Definir nível de detalhe 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 da flag

1. Criar com intenção: Escolha o tipo de flag correto para sinalizar o propósito.
2. Documentar claramente: Escreva descrições que expliquem o "porquê".
3. Planejar a limpeza: Flags de funcionalidade são temporárias; planeje sua remoção.
4. Monitorar uso: Habilite dados de impressão para flags importantes.

Tipos de flag

• Flags de lançamento: Para lançamentos graduais de funcionalidades (remover após lançamento completo).
• Flags de experimento: Para testes A/B (remover após análise).
• Flags operacionais: Para comportamento do sistema (vida mais longa, revisar periodicamente).
• Kill switches: Para controles de emergência (manter até que a funcionalidade esteja estável).
• Flags de permissão: Para controle de acesso (vida mais longa, revisar permissões).

Convenções de nomenclatura

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

Referência da API

Este servidor usa a API de Administração do Unleash. Para documentação completa da API, veja:

• Especificação OpenAPI da API de Administração do Unleash
• Documentação da API do Unleash

Endpoints utilizados

• GET /api/admin/projects - Listar projetos
• GET /api/admin/projects/{projectId}/features - Listar flags de funcionalidade
• POST /api/admin/projects/{projectId}/features - Criar flag de funcionalidade
• GET /api/admin/projects/{projectId}/features/{featureName} - Obter detalhes da flag
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - Adicionar estratégia de lançamento
• 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 must be a valid URL": 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 is required": 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 seu papel e permissões no Unleash.

Erro: "HTTP_404": O ID do projeto não existe. Confirme o ID do projeto na UI de Administração do Unleash.

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

Licença

MIT

Contribuindo

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

• Estar alinhadas 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.