Unleash

oficial

Servidor MCP para gestionar los feature flags de Unleash y automatizar las mejores prácticas.

GitHub
22

¿Qué puedes hacer con Unleash MCP?

  • Evaluar cambios de código — Solicita a evaluate_change que puntúe el riesgo y recomiende si se necesita un feature flag para un cambio de código.
  • Crear feature flags — Usa create_flag para aprovisionar un nuevo flag con tipo, descripción y segmentación de proyecto.
  • Detectar flags existentes — Ejecuta detect_flag para encontrar flags reutilizables en el código o en el historial de git y evitar duplicados.
  • Obtener orientación de envoltura — Solicita wrap_change para obtener plantillas de código específicas del lenguaje e implementar un flag.
  • Gestionar despliegue y estado — Configura porcentajes con set_flag_rollout y luego usa toggle_flag_environment para habilitar o deshabilitar flags.
  • Inspeccionar y listar flags — Usa get_flag_state o list_flags para revisar metadatos de flags, estrategias e inventarios de proyectos.

Documentación

Servidor MCP de Unleash

Un servidor Model Context Protocol (MCP) con un propósito definido para gestionar los feature flags de Unleash. Este servidor permite que los asistentes de codificación impulsados por LLM creen y gestionen feature flags siguiendo las mejores prácticas de Unleash.

Para compartir comentarios, únete a nuestro Slack comunitario o abre un issue en GitHub.

Descripción general

Este servidor MCP proporciona herramientas que se integran con la API de administración de Unleash, permitiendo a los asistentes de codificación con IA:

  • Crear feature flags con validación y tipado adecuados.
  • Detectar flags existentes para prevenir duplicados o fomentar la reutilización.
  • Evaluar cambios para decidir cuándo se necesita un feature flag.
  • Transmitir progreso para visibilidad durante las operaciones.
  • Manejar errores con elegancia y sugerencias útiles.
  • Seguir las mejores prácticas de la documentación de Unleash.

Herramientas disponibles

El servidor MCP expone las siguientes herramientas:

  • create_flag: Crea un feature flag en Unleash.
  • evaluate_change: Evalúa el riesgo y recomienda el uso de feature flags.
  • detect_flag: Descubre feature flags existentes para evitar duplicados.
  • wrap_change: Proporciona orientación sobre cómo envolver un cambio en un feature flag.
  • set_flag_rollout: Configura estrategias de despliegue para un feature flag (no activa el flag).
  • get_flag_state: Muestra los metadatos de un feature flag y sus estrategias de activación.
  • list_flags: Lista todos los feature flags en un proyecto, con paginación y orden opcionales.
  • list_projects: Lista los proyectos de Unleash disponibles para el token configurado, con paginación opcional.
  • toggle_flag_environment: Activa o desactiva un feature flag en un entorno.
  • remove_flag_strategy: Elimina la estrategia de un feature flag de un entorno.
  • cleanup_flag: Genera instrucciones para eliminar de forma segura las rutas de código con flags.

Flujo de trabajo principal

El flujo de trabajo principal para un asistente de IA está diseñado para ser:

  1. evaluate_change: Primero, evalúa un cambio de código para ver si se necesita un flag.
  2. detect_flag: Esto a menudo se llama automáticamente por evaluate_change para prevenir la creación de flags duplicados.
  3. create_flag: Si se requiere un nuevo flag, esta herramienta lo crea en Unleash.
  4. wrap_change: Finalmente, esta herramienta proporciona el código específico del lenguaje para implementar el nuevo flag.

Consulta más información sobre las herramientas del flujo de trabajo principal en la sección Referencia de herramientas.

Requisitos previos

Antes de poder ejecutar el servidor, necesitas lo siguiente:

  • Node.js 22 o superior
  • Gestor de paquetes pnpm o npm
  • Una instancia de Unleash (alojada o autoalojada)
  • Un token de acceso personal con permisos para crear feature flags

Comenzar

Esta sección cubre las diferentes formas de instalar y ejecutar el servidor MCP de Unleash. Puedes seguir una configuración para agentes (como Claude Code y Codex), ejecutar el MCP como un proceso independiente usando npx, o usar una configuración de desarrollo local.

Configuración para agentes

Puedes añadir el servidor MCP directamente a Claude Code o Codex. Las configuraciones de agentes son específicas de la ruta. Debes ejecutar el siguiente comando desde el directorio raíz del proyecto donde quieras usar el 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

Configuración remota para agentes (experimental)

En lugar de ejecutar el servidor MCP localmente, puedes conectarte directamente al servidor MCP remoto integrado de tu instancia de Unleash a través de HTTP. Esto utiliza el transporte HTTP Streamable — no se necesita un proceso local.

Nota: El MCP remoto es una característica experimental que debe estar habilitada en tu instancia de Unleash. Contacta al equipo de Unleash para activarla.

OAuth

El flujo de OAuth abre tu navegador, te permite iniciar sesión en Unleash y aprovisiona automáticamente un PAT de corta duración. No se requiere gestión 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

En el primer uso, el cliente abrirá automáticamente tu navegador para iniciar sesión. Después de autenticarte con Unleash, se crea un PAT y se utiliza para todas las solicitudes posteriores.

El PAT expira después de 24 horas por defecto.

Token de acceso personal (PAT)

Usa este método cuando ya tengas un PAT o necesites acceso headless/no interactivo (pipelines de CI, entornos de desarrollo compartidos, clientes que no soporten OAuth).

Para crear un PAT: inicia sesión en tu instancia de Unleash, ve a Perfil > Tokens de acceso personal y crea un nuevo 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}}"

El flag --header envía el PAT directamente, omitiendo por completo el flujo de OAuth.

Inicio rápido con npx

Puedes ejecutar el servidor MCP como un proceso independiente sin clonar el repositorio usando npx. Proporciona la configuración a través de variables de entorno o un archivo local .env en el directorio donde ejecutes el 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

La CLI soporta los mismos flags que la compilación local (por ejemplo, --dry-run, --log-level).

Configuración de desarrollo local

Sigue estos pasos para configurar el proyecto para el desarrollo local.

  1. Instalar dependencias

Clona el repositorio e instala las dependencias usando pnpm. Corepack mantiene a todos en la misma versión de 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
  1. Ejecutar en modo de desarrollo directamente desde Claude o Codex

Evita la salida de npm run y los banners de tsx watch porque cualquier stdout adicional rompe el handshake de MCP. Dos opciones silenciosas:

A) Usar JS compilado (más confiable)

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 directamente (sin compilación)

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 es silencioso (sin salida del ciclo de vida de npm) y ejecuta TS directamente; úsalo cuando quieras evitar compilar.
  • node dist/index.js es la opción más segura; combínalo con npm run build:watch para recompilar en cambios mientras el comando del agente permanece estable.
  • Los registros permanecen en la raíz del repositorio (app.log, mcp-stdio.log), ambos ignorados por git.

Control de registro

  • LOG_LEVEL (preferido): controla la verbosidad del registro de la aplicación (debug, info, warn, error). Por defecto es error cuando no se establece.
  • Flag CLI --log-level: anulación opcional para LOG_LEVEL cuando quieras un cambio puntual.
  • APP_LOG_FILE (opcional): si se establece, los registros de la aplicación se escriben en este archivo (no en stdout). Si no se establece, los registros van a stderr.
  • MCP_STDIO_LOG_FILE (opcional): si se establece, el stdin/stdout/stderr de MCP se registran en este único archivo con prefijos de canal. Los mensajes del protocolo aún fluyen por stdout normalmente.

Atribución del cliente

Cuando un cliente MCP envía clientInfo durante la inicialización (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro y otros clientes conformes), el servidor enriquece el encabezado User-Agent en las llamadas salientes a la API de administración de Unleash:

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

Esto hace que los registros de eventos de Unleash respondan "qué herramienta de IA creó o alternó este flag" sin cambios en el lado del servidor. Los valores de atribución se sanitizan para que no puedan romper el encabezado User-Agent.

Establece UNLEASH_MCP_CLIENT_ATTRIBUTION=off para deshabilitar el enriquecimiento y volver a unleash-mcp/<version> (MCP Server). Valor predeterminado: habilitado.

Referencia de herramientas

Esta sección describe cada una de las herramientas principales en detalle, incluyendo su propósito, parámetros y salida.

Crear flag

La herramienta create_flag crea un nuevo feature flag en Unleash con validación integral y seguimiento de progreso.

Cuándo usar

Usa esta herramienta cuando ya hayas determinado que se requiere un feature flag (por ejemplo, después de ejecutar evaluate_change) y estés listo para crearlo con el tipo y los metadatos correctos.

Parámetros

La herramienta acepta los siguientes parámetros:

  • name (obligatorio): Nombre único del feature flag dentro del proyecto.
  • type (obligatorio): Tipo de feature flag que indica el ciclo de vida y la intención.
    • release: Despliegues graduales de funciones a los usuarios.
    • experiment: Pruebas A/B y experimentos.
    • operational: Comportamiento del sistema y conmutadores operativos.
    • kill-switch: Apagados de emergencia o interruptores de circuito.
    • permission: Controlar el acceso a funciones según roles de usuario o derechos.
  • description (obligatorio): Explicación clara de qué controla el flag y por qué existe.
  • projectId (opcional): Proyecto de destino (por defecto es UNLEASH_DEFAULT_PROJECT).
  • impressionData (opcional): Habilitar seguimiento de analíticas (por defecto es falso).

Ejemplo de uso

Prompt del agente

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

Carga útil de la herramienta

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

Salida de la herramienta

En caso de éxito, la herramienta devuelve un objeto JSON que contiene la URL del nuevo feature flag en la interfaz de administración de Unleash, un enlace de recurso MCP para acceso programático, la marca de tiempo de creación y los detalles de configuración.

Evaluar cambio

La herramienta evaluate_change evalúa si un cambio de código debe estar detrás de un feature flag. Examina la estructura, el contexto y el riesgo potencial del cambio y devuelve una recomendación con una explicación y los siguientes pasos.

Cuándo usar

Usa evaluate_change al comienzo de una función o modificación cuando quieras entender si el trabajo requiere un feature flag. Esta herramienta también es útil cuando no estás seguro de qué tipo de flag usar o quieres orientación sobre la planificación del despliegue.

Cómo funciona

La herramienta devuelve orientación detallada en formato markdown para el asistente LLM basada en las mejores prácticas de Unleash.

La orientación incluye:

  • Detección de flag padre: Comprueba si el código ya está protegido por flags existentes.
  • Evaluación de riesgo: Analiza patrones de código para identificar operaciones riesgosas.
  • Evaluación del tipo de código: Clasifica el cambio (por ejemplo, prueba, configuración, función o corrección de errores).
  • Recomendación: Sugiere si crear un flag, usar un flag existente u omitir el flag.
  • Acciones siguientes: Proporciona instrucciones específicas sobre qué hacer a continuación.

Cuando evaluate_change determina que se necesita un flag, proporciona instrucciones explícitas para:

  1. Llamar a la herramienta create_flag para crear el feature flag.
  2. Llamar a la herramienta wrap_change para obtener orientación de envoltura de código específica del lenguaje.
  3. Implementar el código envuelto siguiendo los patrones detectados.

El proceso de evaluación

La herramienta sigue un proceso de evaluación 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)

Evaluación de riesgo

La herramienta utiliza patrones independientes del lenguaje para puntuar el riesgo:

  • Riesgo crítico (Puntuación +5): Por ejemplo, autenticación, pagos, seguridad y operaciones de base de datos.
  • Riesgo alto (Puntuación +3): Por ejemplo, cambios de API, servicios externos o nuevas clases.
  • Riesgo medio (Puntuación +2): Por ejemplo, operaciones asíncronas o gestión de estado.
  • Riesgo bajo (Puntuación +1): Por ejemplo, correcciones de errores, refactorizaciones o cambios pequeños.

Las puntuaciones se acumulan entre categorías coincidentes. El total se asigna a un nivel de riesgo:

  • Crítico: Puntuación ≥ 5
  • Alto: Puntuación ≥ 3
  • Medio: Puntuación ≥ 2
  • Bajo: Puntuación < 2

La salida incluye una puntuación de confidence (0-1) que representa la certeza autoevaluada del LLM, que aumenta con más contexto proporcionado.

Una categoría excluida cubre archivos que no necesitan feature flags independientemente del contenido: archivos de prueba (*.test.ts, *_test.go, etc.), archivos de configuración (*.config.js, .env, *.yaml) y archivos de documentación (*.md, docs/**). Los cambios limitados a archivos excluidos no activarán una recomendación de flag.

Las definiciones completas de patrones, incluyendo palabras clave por categoría, globs de archivos, patrones de código y razonamiento, están en src/evaluation/riskPatterns.ts.

Detección de flag padre

La herramienta busca patrones comunes en todos los lenguajes, como:

  • Condicionales: if (isEnabled('flag')), if client.is_enabled('flag'):
  • Asignaciones: const enabled = useFlag('flag')
  • Hooks: const enabled = useFlag('flag') → {enabled && <Component />}
  • Guardas: if (!isEnabled('flag')) return;
  • Envoltorios: withFeatureFlag('flag', () => {...})

Parámetros

Todos los parámetros son opcionales, pero más contexto conduce a mejores recomendaciones:

  • repository (string): Nombre o ruta del repositorio.
  • branch (string): Nombre de la rama actual.
  • files (array): Lista de archivos que se están modificando.
  • description (string): Descripción del cambio.
  • riskLevel (enum): low, medium, high o critical, según lo evaluado por el usuario.
  • codeContext (string): Código circundante para la detección de la bandera principal.

Ejemplo de uso

Prompt del agente

Uso simple donde dejas que el agente recopile contexto:

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

Instrucciones explícitas:

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

Carga útil de la herramienta

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

Salida de la herramienta

Devuelve un objeto JSON con el resultado de la evaluación, incluyendo un booleano needsFlag, un recommendation (por ejemplo, "create_new"), un nombre de bandera sugerido, el nivel de riesgo y un explanation detallado.

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

La herramienta detect_flag encuentra banderas de funciones existentes en el código base para que puedas reutilizarlas en lugar de crear duplicados. Esta herramienta está integrada automáticamente en el flujo de trabajo de evaluate_change, pero también se puede usar manualmente.

Cuándo usarla

Usa esta herramienta antes de crear una nueva bandera de funciones o durante la evaluación del código para verificar si ya existen banderas que podrían cubrir tu caso de uso. Esto ayuda a prevenir la duplicación de banderas.

Cómo funciona

La herramienta devuelve instrucciones de búsqueda exhaustivas y utiliza múltiples estrategias de detección:

  • Detección basada en archivos: Busca en los archivos que estás modificando banderas existentes.
  • Análisis del historial de Git: Busca banderas agregadas recientemente en el historial de confirmaciones.
  • Coincidencia semántica de nombres: Compara descripciones con nombres de banderas existentes.
  • Análisis del contexto del código: Inspecciona el código alrededor del cambio.

Luego, la herramienta sigue un proceso de puntuación:

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

Niveles de confianza

La herramienta devuelve candidatos con puntuaciones de confianza:

  • Alta ≥0.7: Coincidencia fuerte; se recomienda reutilizar.
  • Media 0.4-0.7: Posible coincidencia; revisar manualmente.
  • Baja <0.4: Coincidencia débil; probablemente crear una nueva bandera.

Parámetros

  • description (obligatorio): Descripción del cambio o funcionalidad. Por ejemplo, "payment processing with Stripe", "new checkout flow".
  • files (opcional): Archivos que se están modificando. Por ejemplo, ["src/payments/stripe.ts", "src/checkout/flow.ts"].
  • codeContext (opcional): Código cercano para escanear en busca de banderas.

Ejemplo de uso

Prompt del agente

Verifica si existen banderas antes de crear una:

Use detect_flag with description "payment processing with Stripe"

Integrado automáticamente en la evaluación:

Use evaluate_change - automatically searches for existing flags

Carga útil de la herramienta

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

Salida de la herramienta

Devuelve un objeto JSON que indica si se encontró una bandera. Si flagFound es verdadero, incluye un objeto candidate con el nombre de la bandera, su ubicación, la puntuación de confianza y el motivo de la coincidencia.

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

No se encontró coincidencia:

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

Envolver cambio

La herramienta wrap_change genera fragmentos de código y orientación específicos del lenguaje para envolver código con banderas de funciones. Ayuda a los LLM y desarrolladores a seguir los patrones existentes en el código base y a usar las banderas correctamente.

Cuándo usarla

Usa esta herramienta después de haber creado una bandera de funciones (con create_flag) y necesites implementarla en tu código. Es especialmente útil cuando quieres asegurarte de seguir los patrones existentes del código base o necesitas ejemplos específicos de un framework (por ejemplo, React, Django).

Cómo funciona

Esta herramienta es el paso final en el flujo de trabajo evaluate_change → create_flag → wrap_change.

La herramienta proporciona la siguiente orientación en su respuesta:

  1. Instrucciones de búsqueda: Guía paso a paso para encontrar patrones de banderas existentes en tu código base usando grep.
  2. Detección de patrones: Identifica patrones comunes (por ejemplo, importaciones, nombres de variables de cliente, nombres de métodos o estilos de envoltura).
  3. Plantillas predeterminadas: Fragmentos de código de respaldo si no se encuentran patrones.
  4. Ejemplos específicos de frameworks: Patrones especializados para React, Express, Django y otros.
  5. Múltiples patrones: Bloques if, cláusulas de guarda, hooks, decoradores, middleware y más.

Lenguajes y frameworks compatibles:

  • TypeScript/JavaScript: Node.js, React Hooks, middleware de Express.
  • Python: FastAPI, Django, decoradores de Flask.
  • Go: Bloques if estándar, middleware HTTP.
  • Ruby: Controladores de Rails.
  • PHP: Controladores de Laravel.
  • C#: Controladores de .NET/ASP.NET.
  • Java: Spring Boot.
  • Rust: Manejadores de Actix/Rocket.

Parámetros

  • flagName (obligatorio): Nombre de la bandera de funciones para envolver el código. Por ejemplo: "new-checkout-flow" o "stripe-integration".
  • language (opcional): Lenguaje de programación (se detecta automáticamente desde fileName si no se proporciona). Compatibles: typescript, javascript, python, go, ruby, php, csharp, java, rust
  • fileName (opcional): Nombre del archivo que se está modificando (ayuda a detectar el lenguaje). Por ejemplo: "checkout.ts", "payment.py" o "handler.go".
  • codeContext (opcional): Código circundante para ayudar a detectar patrones existentes.
  • frameworkHint (opcional): Framework para plantillas especializadas. Por ejemplo, "React", "Express", "Django", "Rails" o "Spring Boot".

Ejemplo de uso

Prompt del agente

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

Carga útil de la herramienta

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

Salida de la herramienta

Devuelve una cadena completa con formato Markdown que guía al usuario sobre cómo envolver su código. Esto incluye un inicio rápido, instrucciones de búsqueda, instrucciones de envoltura con marcadores de posición, todas las plantillas disponibles para el lenguaje y enlaces a la documentación del 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.]

Configurar despliegue de bandera

La herramienta set_flag_rollout configura una estrategia flexibleRollout en un entorno de bandera de funciones. Establece el porcentaje de despliegue, la adherencia y variantes opcionales a nivel de estrategia. Esto no habilita la bandera; usa toggle_flag_environment para activarla.

Cuándo usarla

Usa esta herramienta después de crear una bandera con create_flag para configurar cómo se distribuye el tráfico antes de habilitarla. También úsala para actualizar un porcentaje de despliegue existente o agregar variantes.

Parámetros

  • featureName (obligatorio): Nombre de la bandera de funciones.
  • environment (obligatorio): Entorno objetivo (por ejemplo, "production", "development").
  • rolloutPercentage (obligatorio): Porcentaje de tráfico que recibirá la funcionalidad (0-100).
  • projectId (opcional): ID del proyecto (por defecto UNLEASH_DEFAULT_PROJECT).
  • groupId (opcional): Clave de agrupación de adherencia (por defecto el nombre de la funcionalidad).
  • stickiness (opcional): Campo de adherencia (por defecto "default").
  • title (opcional): Título descriptivo para la estrategia.
  • disabled (opcional): Crear la estrategia en estado deshabilitado (por defecto false).
  • variants (opcional): Lista de variantes a nivel de estrategia, cada una con name, weight (0-1000), weightType opcional ("variable" o "fix"), stickiness y payload ({type, value}).

Ejemplo de uso

Prompt del agente

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

Carga útil de la herramienta

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

Salida de la herramienta

Devuelve una confirmación con el porcentaje configurado, un enlace a la bandera en la interfaz de administración de Unleash, la URL de estrategias de la API de administración y un enlace de recurso MCP para la bandera.

Obtener estado de la bandera

La herramienta get_flag_state obtiene los metadatos actuales de una bandera de funciones y las estrategias de entorno de la API de administración de Unleash. Devuelve el tipo de la bandera, su estado habilitado/archivado, la configuración de datos de impresión y un resumen por entorno de las estrategias y variantes activas.

Cuándo usarla

Usa esta herramienta para inspeccionar una bandera antes de modificarla, para verificar cuántas estrategias están activas en los entornos o para encontrar IDs de estrategias antes de llamar a remove_flag_strategy.

Parámetros

  • featureName (obligatorio): Nombre de la bandera de funciones.
  • projectId (opcional): ID del proyecto (por defecto UNLEASH_DEFAULT_PROJECT).
  • environment (opcional): Filtrar resultados a un solo entorno (no distingue mayúsculas y minúsculas).

Ejemplo de uso

Prompt del agente

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

Carga útil de la herramienta

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

Salida de la herramienta

Devuelve un resumen de texto de la bandera (tipo, estado habilitado/archivado/datos de impresión, proyecto, resúmenes de entorno con conteos de estrategias) junto con enlaces de interfaz y API. La salida estructurada incluye el objeto completo de la funcionalidad con todos los entornos y detalles de estrategias.

Listar banderas

La herramienta list_flags enumera las banderas de funciones en un proyecto y devuelve un inventario estructurado con paginación y orden. Las banderas activas y archivadas se devuelven por separado: llámala una vez con archived: false (el valor predeterminado) y una vez con archived: true para armar un inventario completo para flujos de trabajo de auditoría.

Cuándo usarla

Usa esta herramienta cuando un agente necesite descubrir qué banderas ya existen, por ejemplo para auditar un proyecto, encontrar candidatas para limpieza o construir contexto antes de crear o envolver una bandera. Es el equivalente invocable por el agente del recurso unleash://projects/{projectId}/feature-flags (consulta Recursos MCP).

Parámetros

  • projectId (opcional): Proyecto del que listar banderas (por defecto UNLEASH_DEFAULT_PROJECT; se resuelve automáticamente cuando existe un solo proyecto).
  • archived (opcional): true para listar banderas archivadas en lugar de activas. Por defecto false. Las banderas activas y archivadas no se pueden devolver en la misma respuesta.
  • limit (opcional): Máximo de banderas por página (por defecto: tamaño de página del servidor, típicamente 50).
  • order (opcional): Orden por nombre de bandera, asc o desc (por defecto: asc).
  • offset (opcional): Número de banderas a omitir para paginación (por defecto: 0).

Ejemplo de uso

Prompt del agente

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

Carga útil de la herramienta

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

Salida de la herramienta

Devuelve un resumen de texto más contenido estructurado con projectId, archived, order, limit, offset, nextOffset, totalFlags y el array flags (cada uno con nombre, tipo, proyecto, estado archivado y enlaces). Usa nextOffset para paginar proyectos grandes.

Listar proyectos

La herramienta list_projects enumera los proyectos de Unleash disponibles para el token configurado, con paginación y orden.

Cuándo usarla

Usa esta herramienta cuando el proyecto objetivo sea desconocido o cuando un agente necesite elegir un proyecto antes de listar o crear banderas. Es el equivalente invocable por el agente del recurso unleash://projects (consulta Recursos MCP).

Parámetros

  • limit (opcional): Máximo de proyectos por página (por defecto: tamaño de página del servidor, típicamente 20).
  • order (opcional): Orden por tiempo de creación del proyecto, asc o desc (por defecto: desc, más recientes primero).
  • offset (opcional): Número de proyectos a omitir para paginación (por defecto: 0).

Ejemplo de uso

Prompt del agente

Use list_projects to see which projects are available.

Carga útil de la herramienta

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

Salida de la herramienta

Devuelve un resumen de texto más contenido estructurado con order, limit, offset, nextOffset, totalProjects y el array projects (cada uno con id, nombre, descripción, modo, tiempo de creación y URL).

Alternar entorno de bandera

La herramienta toggle_flag_environment habilita o deshabilita una bandera de funciones en un entorno específico. Para despliegues graduales, configura una estrategia con set_flag_rollout antes de habilitar.

Cuándo usarla

Usa esta herramienta para activar una bandera después de configurar una estrategia de despliegue, o para deshabilitar una bandera durante un incidente o después de completar un despliegue.

Parámetros

  • featureName (obligatorio): Nombre del feature flag.
  • environment (obligatorio): Entorno a alternar (por ejemplo, "production").
  • enabled (obligatorio): true para habilitar, false para deshabilitar.
  • projectId (opcional): ID del proyecto (por defecto UNLEASH_DEFAULT_PROJECT).

Ejemplo de uso

Prompt del agente

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

Carga útil de la herramienta

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

Salida de la herramienta

Devuelve una confirmación del nuevo estado, un resumen del entorno (habilitado/deshabilitado, número de estrategias) y enlaces al flag en la interfaz de administración de Unleash y en la API de administración.

Eliminar estrategia de flag

La herramienta remove_flag_strategy elimina una configuración de estrategia de un entorno de feature flag. Usa get_flag_state primero para descubrir el ID de la estrategia.

Cuándo usarla

Usa esta herramienta para limpiar estrategias obsoletas, o para reemplazar una estrategia existente eliminando la anterior y configurando una nueva con set_flag_rollout.

Parámetros

  • featureName (obligatorio): Nombre del feature flag.
  • environment (obligatorio): Entorno del que se elimina la estrategia.
  • strategyId (obligatorio): ID de la estrategia a eliminar (encuéntralo mediante get_flag_state).
  • projectId (opcional): ID del proyecto (por defecto UNLEASH_DEFAULT_PROJECT).

Ejemplo de uso

Prompt del 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 de la herramienta

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

Salida de la herramienta

Devuelve una confirmación de la eliminación, un recuento de las estrategias restantes en el entorno y enlaces al flag en la interfaz de administración de Unleash y en la API de administración.

Limpieza de flag

La herramienta cleanup_flag genera instrucciones paso a paso para eliminar de forma segura el código del feature flag del código base, preservando la ruta de código deseada.

Cuándo usarla

Usa esta herramienta cuando un feature flag haya completado su ciclo de vida:

  • Después de que un despliegue alcance el 100% y el flag ya no sea necesario.
  • Al deprecar una función experimental (preserva la ruta deshabilitada).
  • Al eliminar un interruptor de emergencia que ya no sea necesario.
  • Durante la limpieza de deuda técnica de flags antiguos.

Cómo funciona

La herramienta devuelve instrucciones de limpieza exhaustivas que guían al LLM a través de:

  1. Encontrar todas las apariciones del flag usando patrones de grep.
  2. Identificar patrones de uso (bloques if-else, expresiones ternarias, cláusulas de guarda, hooks, decoradores, middleware).
  3. Eliminar las comprobaciones del flag preservando la ruta de código correcta.
  4. Limpiar importaciones no utilizadas con orientación específica para cada lenguaje.
  5. Verificar los cambios con pasos de búsqueda y pruebas posteriores a la limpieza.

Si preservePath no se proporciona, la herramienta devuelve instrucciones para preguntar al usuario qué ruta conservar antes de continuar.

Parámetros

  • flagName (obligatorio): Nombre del feature flag a eliminar (por ejemplo, "new-checkout-flow").
  • preservePath (opcional): "enabled" para conservar la ruta de código con el flag activado (típico para despliegues completados), o "disabled" para conservar la ruta con el flag desactivado (para experimentos eliminados). Si se omite, la herramienta te indica que preguntes al usuario.
  • files (opcional): Archivos específicos a limpiar. Si se omite, busca en todo el código base.
  • language (opcional): Lenguaje de programación para orientación especializada en limpieza de importaciones (por ejemplo, "typescript", "python"). Se detecta automáticamente desde files si no se proporciona.

Ejemplo de uso

Prompt del agente

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

Carga útil de la herramienta

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

Salida de la herramienta

Devuelve una guía en Markdown que cubre el alcance de la limpieza y la ruta preservada, comandos grep para encontrar todas las apariciones, instrucciones de eliminación por patrón, limpieza de importaciones específica del lenguaje y pasos de verificación posteriores a la limpieza (re-búsqueda, ejecución de pruebas, revisión manual).

Recursos MCP

El servidor registra recursos de MCP para leer datos de proyectos y feature flags. Todos los recursos devuelven JSON y se almacenan en caché durante 60 segundos.

Plantilla de URIDescripción
unleash://projects{?limit,order,offset}Lista de proyectos. Tamaño de página predeterminado: 20, ordenados por fecha de creación (más recientes primero).
unleash://projects/{projectId}/feature-flags{?limit,order,offset}Lista de flags en un proyecto. Tamaño de página predeterminado: 50, ordenados alfabéticamente.
unleash://projects/{projectId}/feature-flags/{flagName}Metadatos de un solo feature flag.

Las dos primeras plantillas aceptan parámetros de consulta opcionales: limit (tamaño de página), order (asc o desc) y offset (inicio de paginación). Las respuestas incluyen campos fetchedAt, cached, totalProjects o totalFlags, y nextOffset.

Recursos vs. herramientas: Los recursos MCP están controlados por la aplicación, por lo que muchos clientes solo los muestran a través de la interfaz de usuario (por ejemplo, menciones con #) y no permiten que el agente llame a resources/read por su cuenta. Cuando un agente necesite enumerar proyectos o flags programáticamente, usa las herramientas list_projects y list_flags, que devuelven los mismos datos a través de la interfaz de herramientas. El análisis de inventario de detect_flag pasa por la misma ruta.

Ejemplo de lectura de recurso

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

Devuelve los primeros 10 feature flags en el proyecto ecommerce, ordenados alfabéticamente, con metadatos de paginación.

Arquitectura

El servidor sigue un diseño enfocado y orientado a un propósito.

Estructura

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

Principios de diseño

  • Superficie reducida: Solo los endpoints necesarios para las capacidades principales.
  • Orientado a un propósito: Cada módulo cumple un propósito específico y bien definido.
  • Validación explícita: Los esquemas Zod validan todas las entradas antes de las llamadas a la API.
  • Normalización de errores: Todos los errores se convierten al formato {code, message, hint}.
  • Transmisión de progreso: Las operaciones de larga duración proporcionan visibilidad.
  • Integración de mejores prácticas: Orientación de la documentación de Unleash integrada en las descripciones de las herramientas.

Configuración

Esta sección proporciona una referencia rápida de todas las opciones de configuración.

Variables de entorno:

  • UNLEASH_BASE_URL: URL de tu instancia de Unleash (obligatorio). Se aceptan tanto https://your-instance.getunleash.io como https://your-instance.getunleash.io/api — el servidor normaliza una barra final /api si está presente, para que puedas pegar el mismo valor que esperan la mayoría de los SDK de Unleash.
  • UNLEASH_PAT: Token de acceso personal (obligatorio).
  • UNLEASH_DEFAULT_PROJECT: El ID de proyecto predeterminado que debe usar el MCP (opcional).

Banderas de CLI:

  • --dry-run: Simular operaciones sin realizar llamadas reales a la API.
  • --log-level: Establecer el nivel de verbosidad del registro (debug, info, warn, error).

Mejores prácticas

Este servidor fomenta las mejores prácticas de Unleash de la documentación oficial:

Ciclo de vida del flag

  1. Crear con intención: Elige el tipo de flag adecuado para indicar el propósito.
  2. Documentar claramente: Escribe descripciones que expliquen el "por qué".
  3. Planificar la limpieza: Los feature flags son temporales; planifica su eliminación.
  4. Supervisar el uso: Habilita los datos de impresión para flags importantes.

Tipos de flags

  • Flags de lanzamiento: Para despliegues graduales de funciones (eliminar después del despliegue completo).
  • Flags de experimento: Para pruebas A/B (eliminar después del análisis).
  • Flags operativos: Para el comportamiento del sistema (mayor duración, revisar periódicamente).
  • Interruptores de emergencia: Para controles de emergencia (mantener hasta que la función sea estable).
  • Flags de permisos: Para control de acceso (mayor duración, revisar permisos).

Convenciones de nomenclatura

  • Usa kebab-case: new-checkout-flow
  • Sé descriptivo: enable-ai-recommendations no flag1.
  • Incluye el alcance cuando sea necesario: mobile-push-notifications.

Referencia de la API

Este servidor usa la API de administración de Unleash. Para la documentación completa de la API, consulta:

Endpoints utilizados

  • GET /api/admin/projects - Listar proyectos
  • GET /api/admin/projects/{projectId}/features - Listar feature flags
  • POST /api/admin/projects/{projectId}/features - Crear feature flag
  • GET /api/admin/projects/{projectId}/features/{featureName} - Obtener detalles del flag
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - Añadir estrategia de despliegue
  • DELETE /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies/{strategyId} - Eliminar estrategia
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/on - Habilitar flag
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - Deshabilitar flag

Solución de problemas

Problemas de configuración

Error: "UNLEASH_BASE_URL must be a valid URL": Asegúrate de que tu URL base esté completa, incluido el protocolo. Por ejemplo, https://app.unleash-hosted.com/instance. Elimina cualquier barra final.

Error: "UNLEASH_PAT is required": Comprueba que tu archivo .env exista y contenga UNLEASH_PAT={{your-personal-access-token}}. Verifica que el token sea válido en Unleash.

Problemas de API

Error: "HTTP_401": Tu token de acceso personal puede ser inválido o haber caducado. Genera un nuevo token en Perfil > Ver configuración del perfil > Tokens de API personales > Nuevo token.

Error: "HTTP_403": Tu token no tiene permiso para crear flags en este proyecto. Revisa tu rol y permisos en Unleash.

Error: "HTTP_404": El ID del proyecto no existe. Confirma el ID del proyecto en la interfaz de administración de Unleash.

Error: "HTTP_409": Ya existe un flag con este nombre en el proyecto. Usa un nombre diferente o reutiliza el flag existente.

Licencia

MIT

Contribuciones

Este es un proyecto orientado a un propósito con un alcance enfocado. Las contribuciones deben:

  • Alinearse con la superficie de herramientas existente y el modelo de recursos MCP.
  • Mantener la arquitectura reducida y orientada a un propósito.
  • Seguir las mejores prácticas de Unleash.
  • Incluir documentación clara.