Unleash

Serveur MCP Unleash

Un serveur Model Context Protocol (MCP) dédié à la gestion des feature flags Unleash. Ce serveur permet aux assistants de codage basés sur LLM de créer et gérer des feature flags en suivant les bonnes pratiques Unleash.

Pour partager vos retours, rejoignez notre Slack communautaire ou ouvrez une issue sur GitHub.

Vue d'ensemble

Ce serveur MCP fournit des outils qui s'intègrent à l'API Admin Unleash, permettant aux assistants de codage IA de :

• Créer des feature flags avec validation et typage appropriés.
• Détecter les flags existants pour éviter les doublons ou encourager la réutilisation.
• Évaluer les changements pour décider quand un feature flag est nécessaire.
• Suivre la progression pour une visibilité pendant les opérations.
• Gérer les erreurs avec élégance et des conseils utiles.
• Suivre les bonnes pratiques de la documentation Unleash.

Outils disponibles

Le serveur MCP expose les outils suivants :

• create_flag : Crée un feature flag dans Unleash.
• evaluate_change : Évalue le risque et recommande l'utilisation d'un feature flag.
• detect_flag : Découvre les feature flags existants pour éviter les doublons.
• wrap_change : Fournit des conseils sur la façon d'envelopper un changement dans un feature flag.
• set_flag_rollout : Configure les stratégies de déploiement pour un feature flag (n'active pas le flag).
• get_flag_state : Affiche les métadonnées d'un feature flag et ses stratégies d'activation.
• list_flags : Liste tous les feature flags d'un projet, avec pagination et ordre de tri optionnels.
• list_projects : Liste les projets Unleash disponibles pour le jeton configuré, avec pagination optionnelle.
• toggle_flag_environment : Active ou désactive un feature flag dans un environnement.
• remove_flag_strategy : Supprime la stratégie d'un feature flag d'un environnement.
• cleanup_flag : Génère des instructions pour supprimer en toute sécurité les chemins de code protégés par des flags.

Flux de travail principal

Le flux de travail principal pour un assistant IA est conçu comme suit :

1. evaluate_change : D'abord, évaluer un changement de code pour voir si un flag est nécessaire.
2. detect_flag : Ceci est souvent appelé automatiquement par evaluate_change pour éviter la création de flags en double.
3. create_flag : Si un nouveau flag est requis, cet outil le crée dans Unleash.
4. wrap_change : Enfin, cet outil fournit le code spécifique au langage pour implémenter le nouveau flag.

Voir plus d'informations sur les outils du flux de travail principal dans la section Référence des outils.

Prérequis

Avant de pouvoir exécuter le serveur, vous avez besoin des éléments suivants :

• Node.js 22 ou supérieur
• Gestionnaire de paquets pnpm ou npm
• Une instance Unleash (hébergée ou auto-hébergée)
• Un jeton d'accès personnel avec les permissions pour créer des feature flags

Commencer

Cette section couvre les différentes façons d'installer et d'exécuter le serveur MCP Unleash. Vous pouvez suivre une configuration pour les agents (tels que Claude Code et Codex), exécuter le MCP comme processus autonome avec npx, ou utiliser une configuration de développement local.

Configuration pour les agents

Vous pouvez ajouter le serveur MCP directement à Claude Code ou Codex. Les configurations d'agent sont spécifiques au chemin. Vous devez exécuter la commande suivante depuis le répertoire racine du projet où vous souhaitez utiliser le MCP.

Pour 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

Pour 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

Configuration pour agent distant (expérimental)

Au lieu d'exécuter le serveur MCP localement, vous pouvez vous connecter directement au serveur MCP distant intégré de votre instance Unleash via HTTP. Cela utilise le transport Streamable HTTP — aucun processus local nécessaire.

Remarque : Le MCP distant est une fonctionnalité expérimentale qui doit être activée sur votre instance Unleash. Contactez l'équipe Unleash pour l'activer.

OAuth

Le flux OAuth ouvre votre navigateur, vous permet de vous connecter à Unleash et provisionne automatiquement un PAT à courte durée de vie. Aucune gestion manuelle de jeton requise.

Pour Claude Code :

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

Pour Codex :

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

Lors de la première utilisation, le client ouvrira automatiquement votre navigateur pour la connexion. Après l'authentification avec Unleash, un PAT est créé et utilisé pour toutes les requêtes suivantes.

Le PAT expire après 24 heures par défaut.

Jeton d'accès personnel (PAT)

Utilisez cette méthode lorsque vous avez déjà un PAT ou avez besoin d'un accès sans interface graphique/non interactif (pipelines CI, environnements de développement partagés, clients qui ne prennent pas en charge OAuth).

Pour créer un PAT : connectez-vous à votre instance Unleash, allez dans Profil > Jetons d'accès personnels, et créez un nouveau jeton.

Pour Claude Code :

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

Pour Codex :

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

Le flag --header envoie le PAT directement, contournant entièrement le flux OAuth.

Démarrage rapide avec npx

Vous pouvez exécuter le serveur MCP comme processus autonome sans cloner le dépôt en utilisant npx. Fournissez la configuration via des variables d'environnement ou un fichier .env local dans le répertoire où vous exécutez la commande :

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

Le CLI prend en charge les mêmes flags que la version locale (par exemple, --dry-run, --log-level).

Configuration de développement local

Suivez ces étapes pour configurer le projet pour le développement local.

1. Installer les dépendances

Clonez le dépôt et installez les dépendances avec pnpm. Corepack maintient tout le monde sur la même version 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

2. Exécuter en mode développement directement depuis Claude ou Codex

Évitez la sortie npm run et les bannières tsx watch car toute sortie stdout supplémentaire casse la poignée de main MCP. Deux options silencieuses :

A) Utiliser le JS compilé (le plus 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) Utiliser TypeScript directement (sans compilation)

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"

Remarques :

• node --import tsx est silencieux (pas de sortie de cycle de vie npm) et exécute TS directement ; utilisez-le lorsque vous voulez éviter la compilation.
• node dist/index.js est le choix le plus sûr ; associez-le à npm run build:watch pour recompiler lors des changements pendant que la commande de l'agent reste stable.
• Les journaux restent à la racine du dépôt (app.log, mcp-stdio.log), tous deux gitignorés.

Contrôle de la journalisation

• LOG_LEVEL (préféré) : contrôle la verbosité de la journalisation de l'application (debug, info, warn, error). Par défaut à error lorsqu'il n'est pas défini.
• Flag CLI --log-level : remplacement optionnel pour LOG_LEVEL lorsque vous voulez un changement ponctuel.
• APP_LOG_FILE (optionnel) : s'il est défini, les journaux de l'application sont écrits dans ce fichier (pas stdout). S'il n'est pas défini, les journaux vont vers stderr.
• MCP_STDIO_LOG_FILE (optionnel) : s'il est défini, les entrées/sorties MCP stdin/stdout/stderr sont redirigées dans ce fichier unique avec des préfixes de canal. Les messages de protocole circulent toujours normalement sur stdout.

Attribution du client

Lorsqu'un client MCP envoie clientInfo pendant l'initialisation (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro et autres clients conformes), le serveur enrichit l'en-tête User-Agent sur les appels sortants à l'API Admin Unleash :

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

Cela permet aux journaux d'événements Unleash de répondre "quel outil IA a créé ou basculé ce flag" sans aucun changement côté serveur. Les valeurs d'attribution sont assainies pour ne pas casser l'en-tête User-Agent.

Définissez UNLEASH_MCP_CLIENT_ATTRIBUTION=off pour désactiver l'enrichissement et revenir à unleash-mcp/<version> (MCP Server). Défaut : activé.

Référence des outils

Cette section décrit chacun des outils principaux en détail, y compris son objectif, ses paramètres et sa sortie.

Créer un flag

L'outil create_flag crée un nouveau feature flag dans Unleash avec une validation complète et un suivi de progression.

Quand l'utiliser

Utilisez cet outil lorsque vous avez déjà déterminé qu'un feature flag est requis (par exemple, après avoir exécuté evaluate_change) et que vous êtes prêt à le créer avec le type et les métadonnées corrects.

Paramètres

L'outil accepte les paramètres suivants :

• name (requis) : Nom unique du feature flag dans le projet.
• type (requis) : Type de feature flag indiquant le cycle de vie et l'intention.
  • release : Déploiements progressifs de fonctionnalités aux utilisateurs.
  • experiment : Tests A/B et expériences.
  • operational : Comportement système et bascules opérationnelles.
  • kill-switch : Arrêts d'urgence ou disjoncteurs.
  • permission : Contrôle de l'accès aux fonctionnalités selon les rôles utilisateur ou les droits.
• description (requis) : Explication claire de ce que le flag contrôle et pourquoi il existe.
• projectId (optionnel) : Projet cible (par défaut UNLEASH_DEFAULT_PROJECT).
• impressionData (optionnel) : Activer le suivi analytique (par défaut false).

Exemple d'utilisation

Invite de l'agent

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

Charge utile de l'outil

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

Sortie de l'outil

En cas de succès, l'outil renvoie un objet JSON contenant l'URL du nouveau feature flag dans l'interface Admin Unleash, un lien de ressource MCP pour l'accès programmatique, l'horodatage de création et les détails de configuration.

Évaluer un changement

L'outil evaluate_change évalue si un changement de code doit être derrière un feature flag. Il examine la structure, le contexte et le risque potentiel du changement et renvoie une recommandation avec une explication et les prochaines étapes.

Quand l'utiliser

Utilisez evaluate_change au début d'une fonctionnalité ou d'une modification lorsque vous voulez comprendre si le travail nécessite un feature flag. Cet outil est également utile lorsque vous n'êtes pas sûr du type de flag à utiliser ou que vous voulez des conseils sur la planification du déploiement.

Comment cela fonctionne

L'outil renvoie des conseils détaillés formatés en Markdown pour l'assistant LLM basés sur les bonnes pratiques Unleash.

Les conseils incluent :

• Détection de flag parent : Vérifie si le code est déjà protégé par des flags existants.
• Évaluation du risque : Analyse les modèles de code pour identifier les opérations risquées.
• Évaluation du type de code : Classe le changement (par exemple, test, configuration, fonctionnalité ou correction de bug).
• Recommandation : Suggère de créer un flag, d'utiliser un flag existant ou d'ignorer le flag.
• Actions suivantes : Fournit des instructions spécifiques sur la marche à suivre.

Lorsque evaluate_change détermine qu'un flag est nécessaire, il fournit des instructions explicites pour :

1. Appeler l'outil create_flag pour créer le feature flag.
2. Appeler l'outil wrap_change pour obtenir des conseils d'encapsulation de code spécifiques au langage.
3. Implémenter le code encapsulé en suivant les modèles détectés.

Le processus d'évaluation

L'outil suit un processus d'évaluation clair :

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)

Évaluation du risque

L'outil utilise des modèles indépendants du langage pour évaluer le risque :

• Risque critique (Score +5) : Par exemple, authentification, paiements, sécurité et opérations de base de données.
• Risque élevé (Score +3) : Par exemple, changements d'API, services externes ou nouvelles classes.
• Risque moyen (Score +2) : Par exemple, opérations asynchrones ou gestion d'état.
• Risque faible (Score +1) : Par exemple, corrections de bugs, refactorisations ou petits changements.

Les scores s'accumulent entre les catégories correspondantes. Le total correspond à un niveau de risque :

• Critique : Score ≥ 5
• Élevé : Score ≥ 3
• Moyen : Score ≥ 2
• Faible : Score < 2

La sortie inclut un score confidence (0-1) représentant la certitude auto-évaluée du LLM, qui augmente avec plus de contexte fourni.

Une catégorie exclue couvre les fichiers qui n'ont pas besoin de feature flags quel que soit leur contenu : fichiers de test (*.test.ts, *_test.go, etc.), fichiers de configuration (*.config.js, .env, *.yaml) et fichiers de documentation (*.md, docs/**). Les changements limités aux fichiers exclus ne déclencheront pas de recommandation de flag.

Les définitions complètes des modèles, y compris les mots-clés par catégorie, les globs de fichiers, les modèles de code et le raisonnement, se trouvent dans src/evaluation/riskPatterns.ts.

Détection de flag parent

L'outil recherche des modèles courants dans tous les langages, tels que :

• Conditionnels : if (isEnabled('flag')), if client.is_enabled('flag'):
• Assignations : const enabled = useFlag('flag')
• Hooks : const enabled = useFlag('flag') → {enabled && <Component />}
• Gardes : if (!isEnabled('flag')) return;
• Enveloppes : withFeatureFlag('flag', () => {...})

Paramètres

Tous les paramètres sont facultatifs, mais plus de contexte mène à de meilleures recommandations :

• repository (chaîne) : Nom ou chemin du dépôt.
• branch (chaîne) : Nom de la branche actuelle.
• files (tableau) : Liste des fichiers modifiés.
• description (chaîne) : Description du changement.
• riskLevel (énumération) : low, medium, high ou critical, tel qu'évalué par l'utilisateur.
• codeContext (chaîne) : Code environnant pour la détection du flag parent.

Exemple d'utilisation

Invite d'agent

Utilisation simple où vous laissez l'agent rassembler le contexte :

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

Instructions explicites :

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

Charge utile de l'outil

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

Sortie de l'outil

Renvoie un objet JSON avec le résultat de l'évaluation, incluant un booléen needsFlag, un recommendation (par exemple, « create_new »), un nom de flag suggéré, un niveau de risque et un explanation détaillé.

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

Détecter un flag

L'outil detect_flag trouve les feature flags existants dans le codebase afin que vous puissiez les réutiliser au lieu d'en créer des doublons. Cet outil est automatiquement intégré au flux de travail evaluate_change, mais peut également être utilisé manuellement.

Quand l'utiliser

Utilisez cet outil avant de créer un nouveau feature flag ou pendant l'évaluation du code pour vérifier l'existence de flags qui pourraient déjà couvrir votre cas d'usage. Cela permet d'éviter la duplication de flags.

Comment cela fonctionne

L'outil renvoie des instructions de recherche complètes et utilise plusieurs stratégies de détection :

• Détection basée sur les fichiers : Recherche dans les fichiers que vous modifiez les flags existants.
• Analyse de l'historique Git : Recherche des flags récemment ajoutés dans l'historique des commits.
• Correspondance sémantique des noms : Correspondance des descriptions avec les noms de flags existants.
• Analyse du contexte du code : Inspection du code autour du changement.

L'outil suit ensuite un processus de notation :

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

Niveaux de confiance

L'outil renvoie des candidats avec des scores de confiance :

• Élevé ≥0.7 : Correspondance forte ; la réutilisation est recommandée.
• Moyen 0.4-0.7 : Correspondance possible ; à examiner manuellement.
• Faible <0.4 : Correspondance faible ; il est probablement préférable de créer un nouveau flag.

Paramètres

• description (obligatoire) : Description du changement ou de la fonctionnalité. Par exemple, "payment processing with Stripe", "new checkout flow".
• files (facultatif) : Fichiers en cours de modification. Par exemple, ["src/payments/stripe.ts", "src/checkout/flow.ts"].
• codeContext (facultatif) : Code environnant à analyser pour détecter des flags.

Exemple d'utilisation

Invite d'agent

Vérifiez les flags existants avant d'en créer un :

Use detect_flag with description "payment processing with Stripe"

Intégré automatiquement dans l'évaluation :

Use evaluate_change - automatically searches for existing flags

Charge utile de l'outil

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

Sortie de l'outil

Renvoie un objet JSON indiquant si un flag a été trouvé. Si flagFound est vrai, il inclut un objet candidate avec le nom du flag, son emplacement, le score de confiance et la raison de la correspondance.

Correspondance trouvée :

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

Aucune correspondance trouvée :

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

Envelopper un changement

L'outil wrap_change génère des extraits de code et des conseils spécifiques au langage pour envelopper le code avec des feature flags. Il aide les LLM et les développeurs à suivre les modèles existants dans le codebase et à utiliser correctement les flags.

Quand l'utiliser

Utilisez cet outil après avoir créé un feature flag (avec create_flag) et lorsque vous devez l'implémenter dans votre code. Il est particulièrement utile lorsque vous souhaitez vous assurer de suivre les modèles existants du codebase ou lorsque vous avez besoin d'exemples spécifiques à un framework (par exemple, React, Django).

Comment cela fonctionne

Cet outil est l'étape finale du flux de travail evaluate_change → create_flag → wrap_change.

L'outil fournit les conseils suivants dans sa réponse :

1. Instructions de recherche : Guide étape par étape pour trouver les modèles de flags existants dans votre codebase à l'aide de grep.
2. Détection de modèles : Identifie les modèles courants (par exemple, les imports, les noms de variables client, les noms de méthodes ou les styles d'enveloppement).
3. Modèles par défaut : Extraits de code de secours si aucun modèle n'est trouvé.
4. Exemples spécifiques aux frameworks : Modèles spécialisés pour React, Express, Django et autres.
5. Modèles multiples : Blocs if, clauses de garde, hooks, décorateurs, middleware, etc.

Langages et frameworks pris en charge :

• TypeScript/JavaScript : Node.js, React Hooks, middleware Express.
• Python : FastAPI, Django, décorateurs Flask.
• Go : Blocs if standard, middleware HTTP.
• Ruby : Contrôleurs Rails.
• PHP : Contrôleurs Laravel.
• C# : Contrôleurs .NET/ASP.NET.
• Java : Spring Boot.
• Rust : Gestionnaires Actix/Rocket.

Paramètres

• flagName (obligatoire) : Nom du feature flag pour envelopper le code. Par exemple : "new-checkout-flow" ou "stripe-integration".
• language (facultatif) : Langage de programmation (détecté automatiquement à partir de fileName s'il n'est pas fourni). Pris en charge : typescript, javascript, python, go, ruby, php, csharp, java, rust
• fileName (facultatif) : Nom du fichier en cours de modification (aide à détecter le langage). Par exemple : "checkout.ts", "payment.py" ou "handler.go".
• codeContext (facultatif) : Code environnant pour aider à détecter les modèles existants.
• frameworkHint (facultatif) : Framework pour les modèles spécialisés. Par exemple, "React", "Express", "Django", "Rails" ou "Spring Boot".

Exemple d'utilisation

Invite d'agent

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

Charge utile de l'outil

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

Sortie de l'outil

Renvoie une chaîne complète formatée en Markdown qui guide l'utilisateur sur la façon d'envelopper son code. Cela inclut un guide de démarrage rapide, des instructions de recherche, des instructions d'enveloppement avec des espaces réservés, tous les modèles disponibles pour le langage et des liens vers la documentation 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.]

Configurer le déploiement d'un flag

L'outil set_flag_rollout configure une stratégie flexibleRollout sur un environnement de feature flag. Il définit le pourcentage de déploiement, la persistance (stickiness) et des variantes facultatives au niveau de la stratégie. Cela n'active pas le flag ; utilisez toggle_flag_environment pour l'activer.

Quand l'utiliser

Utilisez cet outil après avoir créé un flag avec create_flag pour configurer la distribution du trafic avant de l'activer. Utilisez-le également pour mettre à jour un pourcentage de déploiement existant ou pour ajouter des variantes.

Paramètres

• featureName (obligatoire) : Nom du feature flag.
• environment (obligatoire) : Environnement cible (par exemple, "production", "development").
• rolloutPercentage (obligatoire) : Pourcentage du trafic qui recevra la fonctionnalité (0-100).
• projectId (facultatif) : ID du projet (par défaut UNLEASH_DEFAULT_PROJECT).
• groupId (facultatif) : Clé de compartimentage de persistance (par défaut, le nom de la fonctionnalité).
• stickiness (facultatif) : Champ de persistance (par défaut "default").
• title (facultatif) : Titre descriptif de la stratégie.
• disabled (facultatif) : Créer la stratégie dans un état désactivé (par défaut, false).
• variants (facultatif) : Liste des variantes au niveau de la stratégie, chacune avec name, weight (0-1000), weightType facultatif ("variable" ou "fix"), stickiness et payload ({type, value}).

Exemple d'utilisation

Invite d'agent

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

Charge utile de l'outil

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

Sortie de l'outil

Renvoie une confirmation avec le pourcentage configuré, un lien vers le flag dans l'interface d'administration Unleash, l'URL des stratégies de l'API Admin et un lien de ressource MCP pour le flag.

Obtenir l'état d'un flag

L'outil get_flag_state récupère les métadonnées actuelles d'un feature flag et les stratégies d'environnement à partir de l'API Admin Unleash. Il renvoie le type du flag, son statut activé/archivé, le paramètre de données d'impression et un résumé par environnement des stratégies et variantes actives.

Quand l'utiliser

Utilisez cet outil pour inspecter un flag avant de le modifier, pour vérifier le nombre de stratégies actives dans les environnements ou pour trouver les ID de stratégies avant d'appeler remove_flag_strategy.

Paramètres

• featureName (obligatoire) : Nom du feature flag.
• projectId (facultatif) : ID du projet (par défaut UNLEASH_DEFAULT_PROJECT).
• environment (facultatif) : Filtrer les résultats sur un seul environnement (insensible à la casse).

Exemple d'utilisation

Invite d'agent

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

Charge utile de l'outil

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

Sortie de l'outil

Renvoie un résumé textuel du flag (type, statut activé/archivé/données d'impression, projet, résumés d'environnement avec les nombres de stratégies) ainsi que des liens vers l'interface et l'API. La sortie structurée inclut l'objet complet du flag avec tous les environnements et les détails des stratégies.

Lister les flags

L'outil list_flags énumère les feature flags d'un projet et renvoie un inventaire structuré avec pagination et ordre de tri. Les flags actifs et archivés sont renvoyés séparément : appelez-le une fois avec archived: false (la valeur par défaut) et une fois avec archived: true pour constituer un inventaire complet pour les flux de travail d'audit.

Quand l'utiliser

Utilisez cet outil lorsqu'un agent doit découvrir quels flags existent déjà, par exemple pour auditer un projet, trouver des candidats à nettoyer ou construire un contexte avant de créer ou d'envelopper un flag. C'est l'équivalent invocable par l'agent de la ressource unleash://projects/{projectId}/feature-flags (voir Ressources MCP).

Paramètres

• projectId (facultatif) : Projet dont lister les flags (par défaut UNLEASH_DEFAULT_PROJECT ; résolu automatiquement lorsqu'un seul projet existe).
• archived (facultatif) : true pour lister les flags archivés au lieu des flags actifs. Par défaut false. Les flags actifs et archivés ne peuvent pas être renvoyés dans la même réponse.
• limit (facultatif) : Nombre maximal de flags par page (par défaut : taille de page du serveur, généralement 50).
• order (facultatif) : Ordre de tri par nom de flag, asc ou desc (par défaut : asc).
• offset (facultatif) : Nombre de flags à ignorer pour la pagination (par défaut : 0).

Exemple d'utilisation

Invite d'agent

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

Charge utile de l'outil

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

Sortie de l'outil

Renvoie un résumé textuel plus un contenu structuré avec projectId, archived, order, limit, offset, nextOffset, totalFlags et le tableau flags (chacun avec nom, type, projet, statut archivé et liens). Utilisez nextOffset pour parcourir les grands projets.

Lister les projets

L'outil list_projects énumère les projets Unleash disponibles pour le jeton configuré, avec pagination et ordre de tri.

Quand l'utiliser

Utilisez cet outil lorsque le projet cible est inconnu ou lorsqu'un agent doit choisir un projet avant de lister ou de créer des flags. C'est l'équivalent invocable par l'agent de la ressource unleash://projects (voir Ressources MCP).

Paramètres

• limit (facultatif) : Nombre maximal de projets par page (par défaut : taille de page du serveur, généralement 20).
• order (facultatif) : Ordre de tri par date de création du projet, asc ou desc (par défaut : desc, du plus récent au plus ancien).
• offset (facultatif) : Nombre de projets à ignorer pour la pagination (par défaut : 0).

Exemple d'utilisation

Invite d'agent

Use list_projects to see which projects are available.

Charge utile de l'outil

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

Sortie de l'outil

Renvoie un résumé textuel plus un contenu structuré avec order, limit, offset, nextOffset, totalProjects et le tableau projects (chacun avec id, nom, description, mode, date de création et URL).

Activer/désactiver l'environnement d'un flag

L'outil toggle_flag_environment active ou désactive un feature flag dans un environnement spécifique. Pour les déploiements progressifs, configurez une stratégie avec set_flag_rollout avant l'activation.

Quand l'utiliser

Utilisez cet outil pour activer un flag après avoir configuré une stratégie de déploiement, ou pour désactiver un flag lors d'un incident ou après avoir terminé un déploiement.

Paramètres

• featureName (obligatoire) : Nom du feature flag.
• environment (obligatoire) : Environnement à basculer (par exemple, "production").
• enabled (obligatoire) : true pour activer, false pour désactiver.
• projectId (facultatif) : ID du projet (par défaut UNLEASH_DEFAULT_PROJECT).

Exemple d'utilisation

Invite de l'agent

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

Charge utile de l'outil

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

Sortie de l'outil

Renvoie une confirmation du nouvel état, un résumé de l'environnement (activé/désactivé, nombre de stratégies) et des liens vers le flag dans l'interface d'administration Unleash et l'API d'administration.

Supprimer une stratégie de flag

L'outil remove_flag_strategy supprime une configuration de stratégie d'un environnement de feature flag. Utilisez get_flag_state d'abord pour découvrir l'ID de la stratégie.

Quand l'utiliser

Utilisez cet outil pour nettoyer les stratégies obsolètes, ou pour remplacer une stratégie existante en supprimant l'ancienne et en configurant une nouvelle avec set_flag_rollout.

Paramètres

• featureName (obligatoire) : Nom du feature flag.
• environment (obligatoire) : Environnement depuis lequel supprimer la stratégie.
• strategyId (obligatoire) : ID de la stratégie à supprimer (à trouver via get_flag_state).
• projectId (facultatif) : ID du projet (par défaut UNLEASH_DEFAULT_PROJECT).

Exemple d'utilisation

Invite de l'agent

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

Charge utile de l'outil

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

Sortie de l'outil

Renvoie une confirmation de la suppression, un compte des stratégies restantes dans l'environnement et des liens vers le flag dans l'interface d'administration Unleash et l'API d'administration.

Nettoyage de flag

L'outil cleanup_flag génère des instructions étape par étape pour supprimer en toute sécurité le code du feature flag de la base de code tout en préservant le chemin de code souhaité.

Quand l'utiliser

Utilisez cet outil lorsqu'un feature flag a terminé son cycle de vie :

• Après qu'un déploiement atteint 100 % et que le flag n'est plus nécessaire.
• Lors de la dépréciation d'une fonctionnalité expérimentale (préserver le chemin désactivé).
• Lors de la suppression d'un kill switch qui n'est plus nécessaire.
• Lors du nettoyage de la dette technique des anciens flags.

Comment cela fonctionne

L'outil renvoie des instructions de nettoyage complètes qui guident le LLM à travers :

1. La recherche de toutes les occurrences du flag à l'aide de modèles grep.
2. L'identification des modèles d'utilisation (blocs if-else, expressions ternaires, clauses de garde, hooks, décorateurs, middleware).
3. La suppression des vérifications de flag tout en préservant le chemin de code correct.
4. Le nettoyage des imports inutilisés avec des conseils spécifiques au langage.
5. La vérification des modifications avec des étapes de recherche et de test après nettoyage.

Si preservePath n'est pas fourni, l'outil renvoie des instructions pour demander à l'utilisateur quel chemin conserver avant de procéder.

Paramètres

• flagName (obligatoire) : Nom du feature flag à supprimer (par exemple, "new-checkout-flow").
• preservePath (facultatif) : "enabled" pour conserver le chemin de code avec flag activé (typique pour les déploiements terminés), ou "disabled" pour conserver le chemin avec flag désactivé (pour les expériences supprimées). Si omis, l'outil vous invite à demander à l'utilisateur.
• files (facultatif) : Fichiers spécifiques à nettoyer. Si omis, recherche dans toute la base de code.
• language (facultatif) : Langage de programmation pour des conseils spécialisés de nettoyage des imports (par exemple, "typescript", "python"). Détecté automatiquement à partir de files s'il n'est pas fourni.

Exemple d'utilisation

Invite de l'agent

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

Charge utile de l'outil

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

Sortie de l'outil

Renvoie un guide Markdown couvrant la portée du nettoyage et le chemin préservé, les commandes grep pour trouver toutes les occurrences, les instructions de suppression par modèle, le nettoyage des imports spécifique au langage et les étapes de vérification après nettoyage (recherche, exécution des tests, révision manuelle).

Ressources MCP

Le serveur enregistre des ressources MCP pour lire les données des projets et des feature flags. Toutes les ressources renvoient du JSON et sont mises en cache pendant 60 secondes.

Modèle d'URI	Description
unleash://projects{?limit,order,offset}	Liste des projets. Taille de page par défaut : 20, triés par date de création (plus récents d'abord).
unleash://projects/{projectId}/feature-flags{?limit,order,offset}	Liste des flags dans un projet. Taille de page par défaut : 50, triés alphabétiquement.
unleash://projects/{projectId}/feature-flags/{flagName}	Métadonnées d'un seul feature flag.

Les deux premiers modèles acceptent des paramètres de requête facultatifs : limit (taille de page), order (asc ou desc) et offset (début de pagination). Les réponses incluent les champs fetchedAt, cached, totalProjects ou totalFlags, et nextOffset.

Ressources vs outils : Les ressources MCP sont contrôlées par l'application, donc de nombreux clients ne les présentent que via une interface utilisateur pilotée par l'utilisateur (par exemple, les mentions #) et ne permettent pas à l'agent d'appeler resources/read de lui-même. Lorsqu'un agent doit énumérer des projets ou des flags par programmation, utilisez les outils list_projects et list_flags, qui renvoient les mêmes données via l'interface d'outil. L'analyse d'inventaire detect_flag passe par le même chemin.

Exemple de lecture de ressource

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

Renvoie les 10 premiers feature flags du projet ecommerce, triés alphabétiquement, avec les métadonnées de pagination.

Architecture

Le serveur suit une conception ciblée et axée sur un objectif précis.

Structure

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

Principes de conception

• Surface fine : Seuls les points de terminaison nécessaires pour les capacités de base.
• Axé sur un objectif : Chaque module sert un objectif spécifique et bien défini.
• Validation explicite : Les schémas Zod valident toutes les entrées avant les appels API.
• Normalisation des erreurs : Toutes les erreurs converties au format {code, message, hint}.
• Diffusion de la progression : Les opérations de longue durée offrent une visibilité.
• Intégration des meilleures pratiques : Conseils de la documentation Unleash intégrés dans les descriptions des outils.

Configuration

Cette section fournit une référence rapide pour toutes les options de configuration.

Variables d'environnement :

• UNLEASH_BASE_URL : URL de votre instance Unleash (obligatoire). https://your-instance.getunleash.io et https://your-instance.getunleash.io/api sont tous deux acceptés — le serveur normalise un /api final s'il est présent, afin que vous puissiez coller la même valeur que celle attendue par la plupart des SDK Unleash.
• UNLEASH_PAT : Jeton d'accès personnel (obligatoire).
• UNLEASH_DEFAULT_PROJECT : ID de projet par défaut que le MCP doit utiliser (facultatif).

Indicateurs CLI :

• --dry-run : Simuler des opérations sans effectuer de véritables appels API.
• --log-level : Définir le niveau de verbosité des journaux (debug, info, warn, error).

Meilleures pratiques

Ce serveur encourage les meilleures pratiques Unleash issues de la documentation officielle :

Cycle de vie des flags

1. Créer avec intention : Choisissez le bon type de flag pour signaler l'objectif.
2. Documenter clairement : Rédigez des descriptions qui expliquent le « pourquoi ».
3. Planifier le nettoyage : Les feature flags sont temporaires ; planifiez leur suppression.
4. Surveiller l'utilisation : Activez les données d'impression pour les flags importants.

Types de flags

• Flags de version : Pour les déploiements progressifs de fonctionnalités (à supprimer après le déploiement complet).
• Flags d'expérimentation : Pour les tests A/B (à supprimer après analyse).
• Flags opérationnels : Pour le comportement du système (durée de vie plus longue, à réviser périodiquement).
• Kill switches : Pour les contrôles d'urgence (à maintenir jusqu'à ce que la fonctionnalité soit stable).
• Flags de permission : Pour le contrôle d'accès (durée de vie plus longue, à réviser les permissions).

Conventions de nommage

• Utilisez le kebab-case : new-checkout-flow
• Soyez descriptif : enable-ai-recommendations et non flag1.
• Incluez la portée si nécessaire : mobile-push-notifications.

Référence API

Ce serveur utilise l'API d'administration Unleash. Pour la documentation complète de l'API, voir :

• Spécification OpenAPI de l'API d'administration Unleash
• Documentation de l'API Unleash

Points de terminaison utilisés

• GET /api/admin/projects - Liste des projets
• GET /api/admin/projects/{projectId}/features - Liste des feature flags
• POST /api/admin/projects/{projectId}/features - Créer un feature flag
• GET /api/admin/projects/{projectId}/features/{featureName} - Obtenir les détails d'un flag
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - Ajouter une stratégie de déploiement
• DELETE /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies/{strategyId} - Supprimer une stratégie
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/on - Activer un flag
• POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - Désactiver un flag

Dépannage

Problèmes de configuration

Erreur : « UNLEASH_BASE_URL must be a valid URL » : Assurez-vous que votre URL de base est complète, y compris le protocole. Par exemple, https://app.unleash-hosted.com/instance. Supprimez toute barre oblique finale.

Erreur : « UNLEASH_PAT is required » : Vérifiez que votre fichier .env existe et contient UNLEASH_PAT={{your-personal-access-token}}. Vérifiez que le jeton est valide dans Unleash.

Problèmes d'API

Erreur : « HTTP_401 » : Votre jeton d'accès personnel peut être invalide ou expiré. Générez un nouveau jeton sous Profil > Paramètres du profil > Jetons API personnels > Nouveau jeton.

Erreur : « HTTP_403 » : Votre jeton n'a pas la permission de créer des flags dans ce projet. Examinez votre rôle et vos permissions dans Unleash.

Erreur : « HTTP_404 » : L'ID du projet n'existe pas. Confirmez l'ID du projet dans l'interface d'administration Unleash.

Erreur : « HTTP_409 » : Un flag portant ce nom existe déjà dans le projet. Utilisez un nom différent ou réutilisez le flag existant.

Licence

MIT

Contribution

Il s'agit d'un projet axé sur un objectif précis avec une portée ciblée. Les contributions doivent :

• S'aligner sur la surface d'outils existante et le modèle de ressources MCP.
• Maintenir l'architecture fine et axée sur un objectif.
• Suivre les meilleures pratiques Unleash.
• Inclure une documentation claire.