Unleash MCP Server

oficial

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

GitHub
18

Documentación

Unleash MCP Server

Un servidor Model Context Protocol (MCP) orientado a un propósito específico para gestionar Unleash feature flags. Este servidor permite a los asistentes de codificación potenciados por LLM crear y gestionar 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 de IA:

  • Crear feature flags con validación y tipado adecuados.
  • Detectar flags existentes para evitar duplicados o fomentar la reutilización.
  • Evaluar cambios para decidir cuándo se necesita un feature flag.
  • Transmitir el 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 habilita 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 de 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: Habilita o deshabilita 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 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: A menudo se llama automáticamente mediante evaluate_change para evitar 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 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

Primeros pasos

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 agente 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 transmitible — sin necesidad de proceso local.

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

OAuth

El flujo OAuth abre tu navegador, te permite iniciar sesión en Unleash y aprovisiona automáticamente un PAT de corta duración. Sin 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 usa 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 no interactivo/desatendido (pipelines de CI, entornos de desarrollo compartidos, clientes que no soportan 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 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 --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 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 [email protected] --activate

pnpm install
  1. Ejecutar en modo desarrollo directamente desde Claude o Codex

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

A) Usar JS compilado (más fiable)

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 la compilación.
  • node dist/index.js es la opción más segura; combínalo con npm run build:watch para recompilar ante cambios mientras el comando del agente se mantiene 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, stdin/stdout/stderr del MCP se copian en este único archivo con prefijos de canal. Los mensajes del protocolo aún fluyen normalmente por stdout.

Atribución de cliente

Cuando un cliente MCP envía clientInfo durante la inicialización (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro y otros clientes compatibles), el servidor enriquece la cabecera 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 activó este flag" sin cambios en el lado del servidor. Los valores de atribución se sanean para que no puedan romper la cabecera User-Agent.

Establece UNLEASH_MCP_CLIENT_ATTRIBUTION=off para deshabilitar el enriquecimiento y volver a unleash-mcp/<version> (MCP Server). Por defecto: 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 completa y seguimiento del 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 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 funcionalidades a usuarios.
    • experiment: Pruebas A/B y experimentos.
    • operational: Comportamiento del sistema e interruptores operativos.
    • kill-switch: Apagados de emergencia o cortacircuitos.
    • permission: Control de acceso a funcionalidades basado en roles o derechos de usuario.
  • description (obligatorio): Explicación clara de qué controla el flag y por qué existe.
  • projectId (opcional): Proyecto de destino (por defecto UNLEASH_DEFAULT_PROJECT).
  • impressionData (opcional): Habilitar seguimiento analítico (por defecto false).

Ejemplo de uso

Indicación 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 debería 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 inicio de una funcionalidad 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 una guía detallada, formateada en markdown, para el asistente LLM basada en las mejores prácticas de Unleash.

La guía incluye:

  • Detección de flags padre: Comprueba si el código ya está protegido por flags existentes.
  • Evaluación de riesgos: Analiza patrones de código para identificar operaciones riesgosas.
  • Evaluación del tipo de código: Clasifica el cambio (por ejemplo, prueba, configuración, funcionalidad o corrección de errores).
  • Recomendación: Sugiere si crear un flag, usar un flag existente u omitir el flag.
  • Próximas acciones: 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 sobre cómo envolver el código específico 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 riesgos

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 en 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 en las 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 confidence (0-1) que representa la certeza autoevaluada del LLM, la cual aumenta con más contexto proporcionado.

Una categoría excluida cubre archivos que no necesitan feature flags independientemente de su 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 generará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 flags padre

La herramienta busca patrones comunes en varios lenguajes, tales 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 un mayor 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 la evaluación del usuario.
  • codeContext (string): Código circundante para la detección del flag padre.

Ejemplo de uso

Indicación para el agente

Uso simple donde se deja que el agente reúna el 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, que incluye un booleano needsFlag, un recommendation (p. ej., "create_new"), un nombre de flag sugerido, 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 flag

La herramienta detect_flag encuentra flags de funcionalidad existentes en el código base para que puedas reutilizarlos en lugar de crear duplicados. Esta herramienta se integra automáticamente en el flujo de trabajo evaluate_change, pero también se puede usar manualmente.

Cuándo usarla

Usa esta herramienta antes de crear un nuevo flag de funcionalidad o durante la evaluación de código para verificar si hay flags existentes que ya cubran tu caso de uso. Esto ayuda a prevenir la duplicación de flags.

Cómo funciona

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

  • Detección basada en archivos: Busca flags existentes en los archivos que estás modificando.
  • Análisis del historial de Git: Busca flags añadidos recientemente en el historial de commits.
  • Coincidencia semántica de nombres: Relaciona descripciones con nombres de flags 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 la reutilización.
  • Media 0.4-0.7: Posible coincidencia; revisar manualmente.
  • Baja <0.4: Coincidencia débil; probablemente crear un nuevo flag.

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 flags.

Ejemplo de uso

Indicación para el agente

Verificar flags existentes antes de crear uno:

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ó un flag. Si flagFound es verdadero, incluye un objeto candidate con el nombre del flag, ubicación, puntuación de confianza y la razón 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 específicos del lenguaje y orientación para envolver código con flags de funcionalidad. Ayuda a los LLMs y desarrolladores a seguir patrones existentes en el código base y usar los flags correctamente.

Cuándo usarla

Usa esta herramienta después de haber creado un flag de funcionalidad (con create_flag) y necesites implementarlo en tu código. Es especialmente útil cuando quieres asegurarte de seguir patrones existentes en el código base o necesitas ejemplos específicos del framework (p. ej., 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 flags 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 del framework: 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 soportados:

  • 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 del flag de funcionalidad con el que 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). Soportados: 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

Indicación para el 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 formateada en 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.]

Establecer despliegue del flag

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

Cuándo usarla

Usa esta herramienta después de crear un flag con create_flag para configurar cómo se distribuye el tráfico antes de habilitarlo. También úsala para actualizar un porcentaje de despliegue existente o añadir variantes.

Parámetros

  • featureName (obligatorio): Nombre del flag de funcionalidad.
  • environment (obligatorio): Entorno de destino (por ejemplo, "production", "development").
  • rolloutPercentage (obligatorio): Porcentaje de tráfico que recibe 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 falso).
  • 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

Indicación para el 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 al flag en la UI de administración de Unleash, la URL de estrategias de la API de administración y un enlace de recurso MCP para el flag.

Obtener estado del flag

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

Cuándo usarla

Usa esta herramienta para inspeccionar un flag antes de modificarlo, para verificar cuántas estrategias están activas en los entornos o para encontrar IDs de estrategia antes de llamar a remove_flag_strategy.

Parámetros

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

Ejemplo de uso

Indicación para el 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 del flag (tipo, habilitado/archivado/datos de impresión, proyecto, resúmenes de entorno con recuentos de estrategias) junto con enlaces de UI y API. La salida estructurada incluye el objeto completo de la funcionalidad con todos los entornos y detalles de estrategia.

Listar flags

La herramienta list_flags enumera los flags de funcionalidad en un proyecto y devuelve un inventario estructurado con paginación y orden. Los flags activos y archivados se devuelven por separado: llámala una vez con archived: false (el valor predeterminado) y otra con archived: true para ensamblar un inventario completo para flujos de trabajo de auditoría.

Cuándo usarla

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

Parámetros

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

Ejemplo de uso

Indicación para el 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 a través de 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 de destino sea desconocido, o cuando un agente necesite elegir un proyecto antes de listar o crear flags. Es el equivalente invocable por el agente del recurso unleash://projects (ver 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 reciente primero).
  • offset (opcional): Número de proyectos a omitir para paginación (por defecto: 0).

Ejemplo de uso

Indicación para el 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 del flag

La herramienta toggle_flag_environment habilita o deshabilita un flag de funcionalidad 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 un flag después de configurar una estrategia de despliegue, o para deshabilitar un flag durante un incidente o después de completar un despliegue.

Parámetros

  • featureName (obligatorio): Nombre de la bandera de funcionalidad.
  • 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

Indicación 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 a la bandera en la interfaz de administración de Unleash y la API de administración.

Eliminar estrategia de bandera

La herramienta remove_flag_strategy elimina una configuración de estrategia de un entorno de bandera de funcionalidad. Use get_flag_state primero para descubrir el ID de la estrategia.

Cuándo usar

Use 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 de la bandera de funcionalidad.
  • environment (obligatorio): Entorno del cual eliminar la estrategia.
  • strategyId (obligatorio): ID de la estrategia a eliminar (encuéntrelo mediante get_flag_state).
  • projectId (opcional): ID del proyecto (por defecto UNLEASH_DEFAULT_PROJECT).

Ejemplo de uso

Indicación 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 a la bandera en la interfaz de administración de Unleash y la API de administración.

Limpiar bandera

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

Cuándo usar

Use esta herramienta cuando una bandera de funcionalidad haya completado su ciclo de vida:

  • Después de que un despliegue alcance el 100% y la bandera ya no sea necesaria.
  • Al descontinuar una funcionalidad experimental (preservar la ruta deshabilitada).
  • Al eliminar un interruptor de emergencia que ya no es necesario.
  • Durante la limpieza de deuda técnica de banderas antiguas.

Cómo funciona

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

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

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

Parámetros

  • flagName (obligatorio): Nombre de la bandera de funcionalidad a eliminar (por ejemplo, "new-checkout-flow").
  • preservePath (opcional): "enabled" para conservar la ruta de código con la bandera activada (típico para despliegues completados), o "disabled" para conservar la ruta con la bandera desactivada (para experimentos eliminados). Si se omite, la herramienta le solicita que pregunte 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

Indicación 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 ocurrencias, instrucciones de eliminación por patrón, limpieza de importaciones específica del lenguaje y pasos de verificación posteriores a la limpieza (volver a buscar, ejecutar pruebas, revisión manual).

Recursos MCP

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

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

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 los 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 controlada por el usuario (por ejemplo, menciones #) y no permiten que el agente llame a resources/read por sí mismo. Cuando un agente necesita enumerar proyectos o banderas mediante programación, use 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 detect_flag se enruta por la misma vía.

Ejemplo de lectura de recurso

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

Devuelve las primeras 10 banderas de funcionalidad en el proyecto ecommerce, ordenadas 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 sirve a 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 para todas las opciones de configuración.

Variables de entorno:

  • UNLEASH_BASE_URL: Su URL de instancia de Unleash (obligatorio). Se aceptan tanto https://your-instance.getunleash.io como https://your-instance.getunleash.io/api — el servidor normaliza una barra diagonal final /api si está presente, por lo que puede 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 el MCP debe usar (opcional).

Indicadores CLI:

  • --dry-run: Simular operaciones sin realizar llamadas reales a la API.
  • --log-level: Establecer el nivel de detalle 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 de la bandera

  1. Crear con intención: Elija el tipo de bandera correcto para señalar el propósito.
  2. Documentar claramente: Escriba descripciones que expliquen el "por qué".
  3. Planificar la limpieza: Las banderas de funcionalidad son temporales; planifique su eliminación.
  4. Monitorear el uso: Habilite los datos de impresión para banderas importantes.

Tipos de banderas

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

Convenciones de nomenclatura

  • Use kebab-case: new-checkout-flow
  • Sea descriptivo: enable-ai-recommendations no flag1.
  • Incluya el alcance cuando sea necesario: mobile-push-notifications.

Referencia de la API

Este servidor utiliza la API de administración de Unleash. Para obtener documentación completa de la API, consulte:

Endpoints utilizados

  • GET /api/admin/projects - Listar proyectos
  • GET /api/admin/projects/{projectId}/features - Listar banderas de funcionalidad
  • POST /api/admin/projects/{projectId}/features - Crear bandera de funcionalidad
  • GET /api/admin/projects/{projectId}/features/{featureName} - Obtener detalles de la bandera
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - Agregar 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 bandera
  • POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - Deshabilitar bandera

Solución de problemas

Problemas de configuración

Error: "UNLEASH_BASE_URL debe ser una URL válida": Asegúrese de que su URL base esté completa, incluyendo el protocolo. Por ejemplo, https://app.unleash-hosted.com/instance. Elimine cualquier barra diagonal final.

Error: "UNLEASH_PAT es obligatorio": Verifique que su archivo .env exista y contenga UNLEASH_PAT={{your-personal-access-token}}. Verifique que el token sea válido en Unleash.

Problemas de la API

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

Error: "HTTP_403": Su token no tiene permiso para crear banderas en este proyecto. Revise su rol y permisos en Unleash.

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

Error: "HTTP_409": Ya existe una bandera con este nombre en el proyecto. Use un nombre diferente o reutilice la bandera 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 delgada y orientada a un propósito.
  • Seguir las mejores prácticas de Unleash.
  • Incluir documentación clara.