--- description: Architecture macro et détaillée - Agile Planner MCP Server --- # Architecture Macro - Agile Planner MCP Server v1.7.3 ```mermaid flowchart TD subgraph UserInput["User Input"] direction LR CLI_Input[CLI Command: node server/index.js generateBacklog/Feature ...] MCP_Stdio_Input[MCP Client via Stdio: JSON-RPC Request] end subgraph ServerCore["Agile Planner MCP Server"] direction TB EntryPoint[server/index.js] Router[mcp-router.js] ApiClient[api-client.js] BacklogGen[backlog-generator.js] FeatureGen[feature-generator.js] MarkdownGen[markdown-generator.js] Rule3Structure[createRule3Structure] end subgraph FileSystemOutput["File System Output (.agile-planner-backlog/)"] direction LR BacklogJSON[backlog.json] BacklogDumpJSON[backlog-last-dump.json] ReadmeMD[README.md] EpicsDir[epics/] FeaturesDir["features/ (under epics)"] UserStoriesDir["user-stories/ (under features)"] OrphanStoriesDir[orphan-stories/] end CLI_Input --> EntryPoint MCP_Stdio_Input --> EntryPoint EntryPoint -- args --> CLI_Input_Handler{Is CLI mode?} EntryPoint -- stdio data --> Router CLI_Input_Handler -- Yes --> ApiClient Router -- process request --> RequestRouter{Request Type?} RequestRouter -- generateBacklog --> HandleGenerateBacklog[handleGenerateBacklog()] RequestRouter -- generateFeature --> HandleGenerateFeature[handleGenerateFeature()] HandleGenerateBacklog --> ApiClient HandleGenerateFeature --> ApiClient ApiClient --> LLM[LLM API Call] LLM --> ApiClient ApiClient -- backlog request --> BacklogGen ApiClient -- feature request --> FeatureGen BacklogGen -- raw backlog data --> HandleGenerateBacklog FeatureGen -- raw feature data --> HandleGenerateFeature HandleGenerateBacklog -- raw backlog data --> MarkdownGen HandleGenerateFeature -- raw feature data --> MarkdownGen HandleGenerateBacklog -- writes --> BacklogDumpJSON MarkdownGen -- RULE 3 structure --> Rule3Structure Rule3Structure -- writes --> EpicsDir Rule3Structure -- writes --> FeaturesDir Rule3Structure -- writes --> UserStoriesDir Rule3Structure -- writes --> OrphanStoriesDir BacklogGen -- processed data --> MarkdownGen MarkdownGen -- generates files --> BacklogJSON MarkdownGen -- generates files --> ReadmeMD MarkdownGen -- generates structure & files --> EpicsDir EpicsDir --> FeaturesDir FeaturesDir --> UserStoriesDir MarkdownGen -- generates structure & files --> OrphanStoriesDir ``` ## Légende (Macro Architecture) - **User Input**: Represents the different ways a user can trigger backlog generation. - **CLI Command**: Direct command line execution. - **MCP Client via Stdio**: Interaction through a compatible MCP client using standard input/output for JSON-RPC. - **Server Core**: Main components of the Agile Planner server involved in the process. - **EntryPoint (`server/index.js`)**: Initial script that receives requests and routes them based on mode (CLI or MCP). - **Router (`mcp-router.js`)**: Handles MCP requests, including `generateBacklog` via `handleGenerateBacklog()`. - **ApiClient (`api-client.js`)**: Manages communication with the Large Language Model (LLM). - **BacklogGen (`backlog-generator.js`)**: Core logic for interpreting LLM output and structuring the raw backlog data. - **MarkdownGen (`markdown-generator.js`)**: Generates all markdown files and the `backlog.json` from the structured data. - **File System Output**: The files and directory structure created in `.agile-planner-backlog/`. - **`backlog.json`**: The structured backlog in JSON format (generated by `markdown-generator.js` after processing). - **`backlog-last-dump.json`**: The raw JSON output from the LLM, saved by `mcp-router.js` or `cli.js` for audit/debugging. - **`README.md`**: A summary README file for the generated backlog. - **`epics/`, `features/`, `user-stories/`, `orphan-stories/`**: Directories and markdown files as per RULE 3. - **LLM**: The external Large Language Model providing the initial backlog content. --- # Architecture détaillée ## Processus `generateBacklog` (via MCP/stdio) ### Flowchart: `generateBacklog` MCP/stdio ```mermaid flowchart TD A[MCP Client sends JSON-RPC request via Stdio: {method: "generateBacklog", params: {...}}] --> B(server/index.js) B -- Detects MCP mode --> C(mcp-router.js) C -- Invokes --> D(handleGenerateBacklog) D -- Project Name, Description --> E(api-client.js: getCompletion) E -- Forms prompt & calls LLM --> LLM((LLM API)) LLM -- Raw LLM Response (JSON string) --> E E -- Raw JSON string --> D D -- Saves raw LLM output --> F[/audit/backlog-last-dump.json] D -- Parses JSON string to object --> G{Raw Backlog Object} G -- Raw Backlog Object & output path --> H(backlog-generator.js: generateBacklogFromJson) H -- Processes & structures data (epics, features, stories) --> I{Structured Backlog Object} I -- Structured Backlog & output path --> J(markdown-generator.js: generateMarkdownFilesFromResult) J -- Creates directory structure --> K[FS: .agile-planner-backlog/epics, features, user-stories, orphan-stories] J -- Generates individual .md files --> L[FS: epic.md, feature.md, story.md for each item] J -- Generates consolidated backlog --> M[FS: .agile-planner-backlog/backlog.json] J -- Generates summary --> N[FS: .agile-planner-backlog/README.md] D -- Returns success/error to MCP client --> O(MCP Client receives response) style F fill:#lightgrey,stroke:#333,stroke-width:2px style K fill:#lightgrey,stroke:#333,stroke-width:2px style L fill:#lightgrey,stroke:#333,stroke-width:2px style M fill:#lightgrey,stroke:#333,stroke-width:2px style N fill:#lightgrey,stroke:#333,stroke-width:2px ``` ### Diagramme de Séquence: `handleGenerateBacklog` Interactions ```mermaid sequenceDiagram participant Client as MCP Client (stdio) participant Index as server/index.js participant Router as mcp-router.js participant APIClient as api-client.js participant LLMAPI as LLM API participant BacklogGen as backlog-generator.js participant MarkdownGen as markdown-generator.js participant FS as File System Client ->> Index: JSON-RPC Request (generateBacklog, params) Index ->> Router: routeRequest(request) Router ->> Router: handleGenerateBacklog(params) Router ->> APIClient: getCompletion(projectName, projectDesc) APIClient ->> LLMAPI: Request for backlog generation LLMAPI -->> APIClient: Raw JSON String Response APIClient -->> Router: Raw JSON String Router ->> FS: saveRawBacklog(rawJsonString, outputPath, 'backlog-last-dump.json') FS -->> Router: Path to backlog-last-dump.json Router ->> BacklogGen: generateBacklogFromJson(parsedJson, outputPath) Note over Router,BacklogGen: parsedJson is the JS object from raw JSON string BacklogGen -->> Router: structuredBacklogData (JS Object) Router ->> MarkdownGen: generateMarkdownFilesFromResult(structuredBacklogData, outputPath) MarkdownGen ->> FS: Create .agile-planner-backlog/ directory MarkdownGen ->> FS: Create epics/, features/, user-stories/, orphan-stories/ MarkdownGen ->> FS: Write epic.md, feature.md, [story-slug].md files MarkdownGen ->> FS: Write backlog.json MarkdownGen ->> FS: Write README.md MarkdownGen -->> Router: { success: true, path: outputPath } Router -->> Index: Success/Error Response Index -->> Client: JSON-RPC Response ``` ## Générateur de Feature ```mermaid flowchart TD FDesc[Description de la feature] --> FParse[Parsing & Validation] FParse --> FStruct[Structuration user stories] FStruct --> FGenMd[Génération feature.md] FStruct --> FGenStories[Génération user-stories] FGenMd -->|Écriture| FS[(.agile-planner-backlog/)] FGenStories -->|Écriture| FS ``` ### Séquence complète generateFeature ```mermaid sequenceDiagram participant Client participant MCPServer participant FeatureGenerator participant MarkdownGenerator participant Validator Client->>MCPServer: JSON-RPC { method: "generateFeature", params } MCPServer->>FeatureGenerator: generateFeature(params) FeatureGenerator-->>MCPServer: { feature, userStories } MCPServer->>MarkdownGenerator: generateMarkdownFilesFromResult(result, outputPath) MarkdownGenerator->>FS: Crée feature.md, user-stories/*.md MarkdownGenerator-->>Validator: validate(.md) Validator-->>MCPServer: Résultat OK/Erreur MCPServer-->>Client: Résultat JSON + fichiers markdown ``` ## Validateur de Structure ```mermaid flowchart TD VS1[Scan du dossier .agile-planner-backlog/] --> VS2[Lecture des fichiers .md et backlog.json] VS2 --> VS3[Validation RULE 3] VS3 --> VS4[Résultat OK/Erreur] ``` ## Architecture des Tests MCP Version 1.7.1 a introduit une infrastructure de test optimisée pour améliorer la fiabilité des tests MCP et éviter les fuites de ressources. ```mermaid flowchart TD subgraph TestInfrastructure["Infrastructure de Tests MCP"] direction TB TestUtils["tests/utils/mcp-test-utils.js"] TestRunner["scripts/run-critical-tests.js"] TestEnv["Environnement de Test Isolé"] end subgraph TestFiles["Tests"] direction LR E2ETests["tests/integration/mcp.e2e.*.test.js"] CLITests["tests/integration/cli.*.test.js"] Rule3Test["test-mcp-rule3.js"] end TestRunner --> E2ETests TestRunner --> CLITests TestRunner --> Rule3Test E2ETests --> TestUtils CLITests --> TestUtils Rule3Test --> TestUtils TestUtils --> SpawnProcess["Lancement processus Child MCP"] TestUtils --> TestEnv TestUtils --> CleanResources["Nettoyage des ressources"] TestEnv --> IsolatedDir["Répertoire temporaire isolé"] SpawnProcess --> SendMCPRequest["Envoi requête MCP"] SpawnProcess --> ReceiveResult["Réception et parse résultat"] SpawnProcess --> TerminateProcess["Terminaison propre du processus"] TerminateProcess --> CleanResources CleanResources --> DeleteDir["Suppression des répertoires temporaires"] CleanResources --> KillProcess["Kill forcé si nécessaire"] style TestUtils fill:#f9f,stroke:#333,stroke-width:2px style TestEnv fill:#bbf,stroke:#333,stroke-width:2px style CleanResources fill:#bfb,stroke:#333,stroke-width:2px ``` ### Modules Clés de Test - **mcp-test-utils.js**: Utilitaires spécialisés pour l'exécution des tests MCP avec une gestion optimisée des processus et des ressources. - `runMcpCommand`: Exécute une commande MCP dans un processus enfant et renvoie une promesse qui se résout avec le résultat. - `setupMcpTestEnvironment`: Crée un environnement de test isolé avec nettoyage automatique. - `terminateProcess`: Assure la terminaison propre d'un processus, avec kill forcé en dernier recours. - **run-critical-tests.js**: Script exécutant les tests critiques avec différents modes de tolérance aux erreurs. - Mode normal: Exécute tous les tests avec rapports d'échecs. - Mode rapide (--quick): Ignore les tests alternatifs et produit toujours un exit code 0. - Mode strict (--strict): Exit code non-zéro pour tout échec. --- Dernière mise à jour : 2025-05-13