agile-planner-mcp-server/docs/architecture/architecture.md

Serveur MCP pour la génération d'artefacts agiles (backlogs, features, user stories) avec IA - compatible Windsurf, Claude et Cursor

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