Skip to content

optimal-usage-guide.md

Latest commit

 

History

History
240 lines (171 loc) · 12.8 KB

optimal-usage-guide.md

File metadata and controls

240 lines (171 loc) · 12.8 KB

Agile Planner: Optimal Workflow avec les clients MCP (v1.7.3)

Date de dernière modification: 13/05/2025
Version actuelle: 1.7.3

1. Introduction

Ce document décrit la méthode la plus efficace pour utiliser le serveur Agile Planner MCP avec différents clients compatibles MCP comme Windsurf Cascade, Claude.ai et Cursor. L'accent est mis sur un workflow synergique qui tire parti d'autres serveurs MCP puissants comme Context7 (pour la documentation et le contexte) et SequentialThinking (pour la planification d'entrées complexes) afin de maximiser la qualité et la pertinence des artefacts générés par Agile Planner (generateBacklog et generateFeature).

Plutôt que d'appeler directement les outils d'Agile Planner avec des descriptions basiques, ce workflow met l'accent sur l'élaboration, la recherche et la planification structurée comme étapes préliminaires avec votre assistant IA.

2. Le workflow synergique expliqué

Ce workflow recommandé s'intègre parfaitement dans une conversation avec n'importe quel client MCP compatible:

  1. Idea / Requirement (User Input):

    • The user expresses a need (new project backlog, new feature).
    • Example: "Cascade, we need a feature for user profile editing."

  2. Elaboration / Research (Cascade + Context7 / Brave Search / Memories):

    • Cascade gathers context for the request.
    • Crucially, check for existing plans/constraints: Use Context7 (if docs are indexed), retrieve relevant Cascade Memories, or ask the user about existing architectural decisions or implementation guidelines related to this area.
    • Use Context7/Brave Search for external best practices or API docs if needed.
    • Example Cascade Action: "Understood. Before planning, let me check our project memories and Context7 for any existing decisions regarding user data handling or preferred UI libraries for profile sections... Found a memory indicating we use React Hook Form for forms."

  3. Structured Planning (Cascade + SequentialThinking):

    • Cascade uses SequentialThinking to break down the requirement, incorporating research findings and existing constraints/plans identified in the previous step.
    • This creates a detailed, context-aware projectDescription or featureDescription.
    • Example Cascade Action: "Okay, planning with SequentialThinking, considering the requirement to use React Hook Form..."

  4. Generation (Cascade + Agile Planner MCP):

    • Cascade calls mcp0_generateBacklog or mcp0_generateFeature with the rich, structured description.
    • Example Cascade Action: "Calling mcp0_generateFeature with the detailed plan for profile editing, including React Hook Form considerations."

  5. Review & Refinement (User + Cascade + edit_file):

    • User reviews the output.
    • Cascade uses edit_file for adjustments. Optionally, Cascade could be asked to add an initial status marker like [Status: Generated] here, but ongoing tracking is separate.

3. Structure hiérarchique (v1.7.1)

Depuis la version 1.7.1, Agile Planner organise vos éléments dans une structure hiérarchique claire conforme à la RULE 3:

.agile-planner-backlog/
├── backlog.json
├── epics/
│   └── [epic-slug]/
│       ├── epic.md
│       └── features/
│           └── [feature-slug]/
│               ├── feature.md
│               └── user-stories/
│                   └── [story-slug].md
└── orphan-stories/
    └── [story-slug].md

Cette organisation hiérarchique améliore considérablement la traçabilité et facilite la navigation entre les différents niveaux du backlog.

Améliorations de la version 1.7.1

La version 1.7.1 apporte des améliorations significatives :

  • Architecture MCP complète : Support complet du protocole JSON-RPC 2.0
  • Compatibilité multi-client : Claude.ai, Cursor et Windsurf IDE
  • Génération markdown améliorée : Architecture modulaire pour une meilleure maintenabilité
  • Réduction de la complexité cognitive : Refactorisation des modules critiques
  • Documentation complète : Guides détaillés pour l'intégration et l'utilisation
  • Tests E2E optimisés : Validation automatique des flux MCP
  • Une meilleure gestion des chemins de fichiers (utilisation systématique de chemins absolus)
  • Une validation renforcée des données d'entrée
  • L'utilisation des IDs directs au lieu des slugs générés

Important: La version 1.2.0 corrige un problème critique avec l'outil MCP generateBacklog qui empêchait parfois la création correcte de la structure hiérarchique. Si vous utilisiez une version antérieure, assurez-vous de mettre à jour vers cette version pour bénéficier d'une génération de backlog plus fiable.

4. Pragmatic Example: Generating a Feature Aligned with Plans

(Adapting the previous Stripe example slightly to show plan adherence)

USER: "Cascade, let's plan the feature for adding Stripe payments to our checkout page."

CASCADE: "Okay. First, let me check project documentation via Context7 and our memories for any specific guidelines on payment integrations... Found a guideline: 'All external payment processing must happen server-side for security compliance'. Now, shall I consult the Stripe Node.js docs via Context7 for the standard server-side Payment Intent flow?"

USER: "Yes, please do."

CASCADE: (Hypothetically uses Context7) "Got it. Now, let's use SequentialThinking to structure the feature plan, incorporating the server-side processing requirement and the Stripe flow details..."

CASCADE: (Hypothetically uses SequentialThinking) "Okay, the detailed description is ready, emphasizing server-side PaymentIntent creation. Shall I generate the feature using mcp0_generateFeature?"

USER: "Yes, proceed."

CASCADE: (Calls mcp0_generateFeature) "Done. Generated files are in the hierarchical structure under .agile-planner-backlog/epics/[epic-name]/features/stripe-payments/. Please review."

USER: "Looks aligned. Can you add [Status: Generated] to each user story title?"

CASCADE: (Calls edit_file to add the status marker) "Done. I've updated all user stories in the .agile-planner-backlog/epics/[epic-name]/features/stripe-payments/user-stories/ directory."

5. Intégration MCP avec différents clients

Depuis la version 1.7.1, Agile Planner peut être utilisé avec plusieurs clients MCP. Voici comment l'intégrer avec chacun d'eux :

Workspace Rules are generally preferred here as they associate this specific synergistic behavior with the Agile Planner project/workspace, rather than applying it globally to all Cascade interactions.

Windsurf IDE / Cascade

  1. Ouvrez les paramètres de Windsurf IDE
  2. Allez dans "IA > Cascade > Serveurs MCP"
  3. Ajoutez Agile Planner avec la commande : npx agile-planner --mcp
  4. Ajoutez dans le champ Description : Générateur d'artefacts Agile (backlog, features, stories)
  5. Options avancées : Vous pouvez ajouter des arguments comme --config=./config.json pour personnaliser la configuration

Exemple d'utilisation en conversation :

USER: Générer un backlog pour notre application de gestion de tâches

CASCADE: Je vais vous aider à générer un backlog pour votre application. Pourriez-vous me donner plus de détails sur les fonctionnalités souhaitées?

USER: L'application doit permettre aux utilisateurs de créer des tâches, les organiser en projets, définir des priorités et des échéances, et suivre la progression.

CASCADE: Je vais générer un backlog complet pour votre application de gestion de tâches avec ces fonctionnalités.  

[Utilise mcp0_tools/call avec { "name": "generateBacklog", "arguments": { "projectName": "Gestionnaire de tâches", "projectDescription": "...", "outputPath": "./.agile-planner-backlog" } }]

Claude.ai

  1. Allez dans les paramètres de Claude
  2. Sélectionnez "Outils > Gérer les outils"
  3. Ajoutez Agile Planner avec la commande : npx agile-planner --mcp

Cursor

  1. Ouvrez les paramètres de Cursor
  2. Accédez à "AI > MCP Tools"
  3. Ajoutez Agile Planner avec la commande : npx agile-planner --mcp

Règles suggérées pour Windsurf

Pour une utilisation optimale avec Cascade dans Windsurf, considérez l'ajout de ces règles dans vos paramètres Workspace :

# RULE 1: Recherche avant génération
- Lorsqu'on vous demande d'utiliser `mcp0_generateFeature`, si la requête mentionne des technologies spécifiques ou des concepts complexes, suggérez d'abord d'utiliser `Context7` ou `Brave Search` pour rassembler du contexte.  

# RULE 2: Planification pour les features/backlogs complexes
- Après avoir rassemblé le contexte, suggérez d'utiliser `SequentialThinking` pour structurer une description détaillée avant d'appeler l'outil Agile Planner approprié.

# RULE 3: Priorité à Context7 pour la documentation
- Lorsque des recherches sont nécessaires pour une bibliothèque ou un framework connu, privilégiez l'utilisation de `Context7`.

(Note : Ce sont des exemples ; adaptez-les à vos besoins spécifiques et à votre style d'interaction.)

Communication avec le protocole MCP

Les clients MCP communiquent avec Agile Planner via le protocole JSON-RPC 2.0. Voici un exemple de requête et réponse :

Requête :

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "generateBacklog",
    "arguments": {
      "projectName": "Task Manager",
      "projectDescription": "Application de gestion de tâches...",
      "outputPath": "./.agile-planner-backlog/task-manager"
    }
  },
  "id": 1
}

Réponse :

{
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "message": "Backlog généré avec succès",
    "outputPath": "./.agile-planner-backlog/task-manager",
    "backlog": { ... }
  },
  "id": 1
}

Note sur le suivi de progression :

Agile Planner MCP ne gère pas automatiquement le suivi de l'état d'implémentation des user stories ou features générées. Le suivi continu (passage des éléments à "En cours" ou "Terminé") devrait typiquement être géré dans votre système de gestion de projet principal (Jira, Trello, Asana, etc.).

6. Conclusion

En adoptant ce workflow synergique avec Agile Planner MCP 1.7.1, vous pouvez :

  1. Intégrer facilement la génération de backlog dans n'importe quel environnement compatible MCP
  2. Améliorer la qualité des backlogs générés grâce à une recherche et une planification préalables
  3. Maintenir la cohérence entre les différentes parties de votre projet
  4. Accélérer considérablement le processus de planification agile

Cette approche transforme votre client MCP et Agile Planner en un assistant de planification plus puissant et conscient du contexte, que ce soit avec Windsurf Cascade, Claude.ai ou Cursor.

Appendix: Agile Planner MCP Tool Reference

(Details moved from the main body for clarity)

A.1. generateBacklog

  • Description: Génère un backlog complet de projet agile (epics, features, user stories) à partir d'une description de projet.
  • Code Source: server/lib/backlog-generator.js
  • Paramètres d'entrée:
    • projectName (string, requis): Nom du projet.
    • projectDescription (string, requis): Description détaillée des objectifs/champ d'application.
    • outputPath (string, optionnel): Répertoire de sortie personnalisé. Par défaut, utilise la variable d'environnement AGILE_PLANNER_OUTPUT_ROOT ou ./.agile-planner-backlog.
  • Sortie: Fichiers Markdown/JSON du backlog dans outputPath.
  • Exemple MCP: Voir le Guide d'intégration MCP pour des exemples complets de requêtes et réponses.

A.2. generateFeature

  • Description: Génère une feature spécifique avec des user stories.
  • Code Source: server/lib/feature-generator.js
  • Paramètres d'entrée:
    • featureDescription (string, requis): Description détaillée de la feature.
    • businessValue (string, optionnel): Proposition de valeur business.
    • storyCount (integer, optionnel, défaut: 3, min: 3): Nombre de user stories.
    • epicName (string, optionnel): Nom de l'epic associé (en sera créé un si non spécifié).
    • outputPath (string, optionnel): Répertoire de sortie personnalisé.
  • Sortie: Fichiers Markdown/JSON de la feature dans outputPath.
  • Exemple MCP: Voir le Guide d'intégration MCP pour des exemples complets.

A.3. getStatus

  • Description: Vérifie le statut du serveur MCP Agile Planner.
  • Code Source: server/lib/mcp-router.js
  • Paramètres d'entrée: Aucun
  • Sortie: État actuel du serveur avec informations de version.
  • Exemple MCP: Voir le Guide d'intégration MCP.