Unleash

Serveur MCP Unleash

Un serveur Model Context Protocol (MCP) conçu pour gérer les indicateurs de fonctionnalité Unleash. Ce serveur permet aux assistants de codage basés sur des LLM de créer et gérer des indicateurs de fonctionnalité en suivant les bonnes pratiques d'Unleash.

Pour partager vos commentaires, rejoignez notre Slack communautaire ou ouvrez un ticket sur GitHub.

Aperçu

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

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

Outils disponibles

Le serveur MCP expose les outils suivants :

• create_flag : Crée un indicateur de fonctionnalité dans Unleash.
• evaluate_change : Évalue le risque et recommande l'utilisation d'un indicateur de fonctionnalité.
• detect_flag : Découvre les indicateurs de fonctionnalité existants pour éviter les doublons.
• wrap_change : Fournit des conseils sur la manière d'encapsuler une modification dans un indicateur de fonctionnalité.
• set_flag_rollout : Configure les stratégies de déploiement pour un indicateur de fonctionnalité (ne l'active pas).
• get_flag_state : Affiche les métadonnées d'un indicateur de fonctionnalité et ses stratégies d'activation.
• list_flags : Liste tous les indicateurs de fonctionnalité d'un projet, avec pagination et ordre de tri optionnels.
• list_projects : Liste les projets Unleash accessibles au jeton configuré, avec pagination optionnelle.
• toggle_flag_environment : Active ou désactive un indicateur de fonctionnalité dans un environnement.
• remove_flag_strategy : Supprime la stratégie d'un indicateur de fonctionnalité d'un environnement.
• cleanup_flag : Génère des instructions pour supprimer en toute sécurité les chemins de code sous indicateur.

Flux de travail principal

Le flux de travail principal pour un assistant IA est conçu pour être :

1. evaluate_change : D'abord, évaluer une modification de code pour voir si un indicateur est nécessaire.
2. detect_flag : Ceci est souvent appelé automatiquement par evaluate_change pour éviter de créer des indicateurs en double.
3. create_flag : Si un nouvel indicateur 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 nouvel indicateur.

Consultez 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 de ce qui suit :

• Node.js 22 ou supérieur
• Le 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 de créer des indicateurs de fonctionnalité

Démarrage

Cette section couvre les différentes manières d'installer et d'exécuter le serveur MCP Unleash. Vous pouvez soit suivre une configuration pour les agents (tels que Claude Code et Codex), exécuter le MCP en tant que processus autonome en utilisant npx, ou utiliser une configuration de développement local.

Configuration pour agent

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 HTTP Streamable — 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 de courte durée. 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 authentification auprès d'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/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 drapeau --header envoie directement le PAT, contournant entièrement le flux OAuth.

Démarrage rapide avec npx

Vous pouvez exécuter le serveur MCP en tant que processus autonome sans cloner le dépôt en utilisant npx. Fournissez la configuration via des variables d'environnement ou un fichier local .env 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 --log-level debug

La CLI prend en charge les mêmes drapeaux que la construction 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 en utilisant 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 interrompt la négociation 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 construction)

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 du cycle de vie npm) et exécute TS directement ; utilisez ceci lorsque vous voulez éviter la construction.
• node dist/index.js est le choix le plus sûr ; associez-le à npm run build:watch pour reconstruire lors des modifications pendant que la commande de l'agent reste stable.
• Les journaux restent dans la racine du dépôt (app.log, mcp-stdio.log), tous deux ignorés par git.

Contrôle de la journalisation

• LOG_LEVEL (recommandé) : contrôle la verbosité de la journalisation applicative (debug, info, warn, error). Par défaut error si non défini.
• Drapeau CLI --log-level : remplacement optionnel pour LOG_LEVEL lorsque vous voulez un changement ponctuel.
• APP_LOG_FILE (optionnel) : si défini, les journaux applicatifs sont écrits dans ce fichier (pas stdout). Si non défini, les journaux vont vers stderr.
• MCP_STDIO_LOG_FILE (optionnel) : si défini, stdin/stdout/stderr MCP sont redirigés dans ce fichier unique avec des préfixes de canal. Les messages de protocole circulent toujours normalement via 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 lors des appels sortants à l'API d'administration 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 à la question "quel outil IA a créé ou basculé cet indicateur" sans aucune modification côté serveur. Les valeurs d'attribution sont nettoyées afin de 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). Par défaut : activé.

Référence des outils

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

Créer un indicateur

L'outil create_flag crée un nouvel indicateur de fonctionnalité dans Unleash avec une validation complète et un suivi de la progression.

Quand l'utiliser

Utilisez cet outil lorsque vous avez déjà déterminé qu'un indicateur de fonctionnalité 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 de l'indicateur de fonctionnalité au sein du projet.
• type (requis) : Type d'indicateur de fonctionnalité 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 basé sur les rôles ou droits des utilisateurs.
• description (requis) : Explication claire de ce que l'indicateur 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 retourne un objet JSON contenant l'URL du nouvel indicateur de fonctionnalité dans l'interface d'administration Unleash, un lien de ressource MCP pour un accès programmatique, l'horodatage de création et les détails de configuration.

Évaluer la modification

L'outil evaluate_change évalue si une modification de code devrait être placée derrière un indicateur de fonctionnalité. Il examine la structure, le contexte et le risque potentiel de la modification et retourne 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 indicateur de fonctionnalité. Cet outil est également utile lorsque vous n'êtes pas sûr du type d'indicateur à utiliser ou souhaitez des conseils sur la planification du déploiement.

Comment ça fonctionne

L'outil retourne 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 d'indicateur parent : Vérifie si le code est déjà protégé par des indicateurs existants.
• Évaluation des risques : Analyse les motifs de code pour identifier les opérations risquées.
• Évaluation du type de code : Classifie la modification (par exemple, test, configuration, fonctionnalité ou correction de bogue).
• Recommandation : Suggère de créer un indicateur, d'utiliser un indicateur existant ou de ne pas utiliser d'indicateur.
• Prochaines actions : Fournit des instructions spécifiques sur la marche à suivre.

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

1. Appeler l'outil create_flag pour créer l'indicateur de fonctionnalité.
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 motifs 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 des risques

L'outil utilise des motifs 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, modifications 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 bogues, refactorisations ou petites modifications.

Les scores s'accumulent à travers 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 d'indicateurs de fonctionnalité 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 modifications limitées aux fichiers exclus ne déclencheront pas de recommandation d'indicateur.

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

Détection d'indicateur parent

L'outil recherche des motifs communs à travers les langages, tels que :

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

Paramètres

Tous les paramètres sont facultatifs, mais plus de contexte permet d’obtenir 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 en cours de modification.
• description (chaîne) : Description de la modification.
• riskLevel (énumération) : low, medium, high ou critical, selon l’évaluation de l’utilisateur.
• codeContext (chaîne) : Code environnant pour la détection du flag parent.

Exemple d’utilisation

Invite de l’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é, le 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 recherche les feature flags existants dans la base de code afin que vous puissiez les réutiliser au lieu de 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 s’il existe déjà des flags qui pourraient couvrir votre cas d’usage. Cela permet d’éviter la duplication des flags.

Comment ça 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 : Fait correspondre les descriptions aux noms de flags existants.
• Analyse du contexte du code : Inspecte le code autour de la modification.

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 ; à vérifier manuellement.
• Faible <0.4 : Correspondance faible ; il est probablement préférable de créer un nouveau flag.

Paramètres

• description (obligatoire) : Description de la modification 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 à proximité pour rechercher des flags.

Exemple d’utilisation

Invite de l’agent

Vérifier 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 la modification

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

Quand l’utiliser

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

Comment ça fonctionne

Cet outil est la dernière étape 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 base de code en utilisant 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. Templates 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, et plus encore.

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 avec lequel envelopper le code. Par exemple : "new-checkout-flow" ou "stripe-integration".
• language (facultatif) : Langage de programmation (auto-détecté à 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 templates spécialisés. Par exemple, "React", "Express", "Django", "Rails" ou "Spring Boot".

Exemple d’utilisation

Invite de l’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 au format markdown qui guide l’utilisateur sur la façon d’envelopper son code. Cela inclut un démarrage rapide, des instructions de recherche, des instructions d’enveloppement avec des espaces réservés, tous les templates disponibles pour le langage et des liens vers la documentation du 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.]

Définir le déploiement du 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 les 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 ajouter des variantes.

Paramètres

• featureName (obligatoire) : Nom du feature flag.
• environment (obligatoire) : Environnement cible (par exemple, "production", "development").
• rolloutPercentage (obligatoire) : Pourcentage de trafic devant recevoir la fonctionnalité (0-100).
• projectId (facultatif) : ID du projet (par défaut UNLEASH_DEFAULT_PROJECT).
• groupId (facultatif) : Clé de regroupement pour la 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 de l’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 du flag

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

Quand l’utiliser

Utilisez cet outil pour inspecter un flag avant de le modifier, pour vérifier combien de stratégies sont actives dans les environnements ou pour trouver les ID de stratégie 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 de l’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, activé/archivé/données d’impression, projet, résumés d’environnement avec le nombre de stratégies) ainsi que des liens vers l’interface utilisateur et l’API. La sortie structurée inclut l’objet feature complet 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 (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 a besoin de découvrir quels flags existent déjà, par exemple pour auditer un projet, trouver des candidats au nettoyage 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 à partir duquel 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 maximum 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 de l’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 le nom, le type, le projet, l’état archivé et les liens). Utilisez nextOffset pour paginer dans 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 maximum 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, le plus récent en premier).
• offset (facultatif) : Nombre de projets à ignorer pour la pagination (par défaut : 0).

Exemple d’utilisation

Invite de l’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 l’id, le nom, la description, le mode, la date de création et l’URL).

Activer/Désactiver l’environnement du 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 (optionnel) : 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 d'abord get_flag_state 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 duquel supprimer la stratégie.
• strategyId (obligatoire) : ID de la stratégie à supprimer (à trouver via get_flag_state).
• projectId (optionnel) : 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.

Nettoyer un flag

L'outil cleanup_flag génère des instructions étape par étape pour supprimer en toute sécurité le code d'un 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 (conserver 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 ça fonctionne

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

1. La recherche de toutes les occurrences du flag en utilisant des motifs grep.
2. L'identification des motifs 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 post-nettoyage et de test.

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

Paramètres

• flagName (obligatoire) : Nom du feature flag à supprimer (par exemple, "new-checkout-flow").
• preservePath (optionnel) : "enabled" pour conserver le chemin de code flag activé (typique pour les déploiements terminés), ou "disabled" pour conserver le chemin flag désactivé (pour les expériences supprimées). Si omis, l'outil vous invite à demander à l'utilisateur.
• files (optionnel) : Fichiers spécifiques à nettoyer. Si omis, recherche dans toute la base de code.
• language (optionnel) : Langage de programmation pour des conseils spécialisés de nettoyage d'imports (par exemple, "typescript", "python"). Auto-détecté à 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 en 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 motif, le nettoyage d'imports spécifique au langage et les étapes de vérification post-nettoyage (rechercher à nouveau, exécuter les tests, révision manuelle).

Ressources MCP

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

Modèle d'URI	Description
unleash://projects{?limit,order,offset}	Lister les projets. Taille de page par défaut : 20, triés par date de création (les plus récents en premier).
unleash://projects/{projectId}/feature-flags{?limit,order,offset}	Lister les flags dans un projet. Taille de page par défaut : 50, triés par ordre alphabétique.
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 optionnels : 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 exposent qu'à travers 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 a besoin d'énumérer des projets ou des flags de manière programmatique, utilisez les outils list_projects et list_flags, qui renvoient les mêmes données via l'interface 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 par ordre alphabétique, avec les métadonnées de pagination.

Architecture

Le serveur suit une conception ciblée et axée sur un but 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 d'attaque réduite : Seuls les points de terminaison nécessaires aux capacités de base.
• Axé sur un but : 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 sont converties au format {code, message, hint}.
• Streaming de progression : Les opérations de longue durée offrent une visibilité.
• Intégration des meilleures pratiques : Les conseils de la documentation Unleash sont 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 : Votre URL d'instance Unleash (obligatoire). Les formats https://your-instance.getunleash.io et https://your-instance.getunleash.io/api sont acceptés — le serveur normalise un /api final s'il est présent, vous pouvez donc 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 : L'ID de projet par défaut que le MCP doit utiliser (optionnel).

Options CLI :

• --dry-run : Simuler les opérations sans effectuer d'appels API réels.
• --log-level : Définir la verbosité de la journalisation (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 release : 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 (plus durables, à revoir 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 (plus durables, à revoir 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 une 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 - Lister les projets
• GET /api/admin/projects/{projectId}/features - Lister les 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 doit être une URL valide » : Assurez-vous que votre URL de base est complète, y compris le protocole. Par exemple, https://app.unleash-hosted.com/instance. Supprimez tout slash final.

Erreur : « UNLEASH_PAT est requis » : 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 est peut-être invalide ou expiré. Générez un nouveau jeton sous Profil > Voir les paramètres du profil > Jetons d'API personnels > Nouveau jeton.

Erreur : « HTTP_403 » : Votre jeton n'a pas la permission de créer des flags dans ce projet. Vérifiez 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 avec 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 but 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 légère et axée sur un but.
• Suivre les meilleures pratiques Unleash.
• Inclure une documentation claire.