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

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

# Architecture du serveur MCP Agile Planner

**Date de dernière modification:** 12/05/2025  
**Version:** 1.7.1

## Vue d'ensemble

Agile Planner implémente le protocole MCP (Model Context Protocol) qui permet aux assistants IA comme Claude, Cursor et Windsurf IDE d'interagir avec des outils externes. Cette documentation détaille l'architecture et le fonctionnement du serveur MCP.

## Architecture générale

```mermaid
graph TB
    subgraph "Client LLM"
        C[Claude.ai] 
        W[Windsurf IDE]
        CU[Cursor]
    end
    
    subgraph "Agile Planner MCP Server"
        direction TB
        E[MCP Entry Point] --> Router[MCP Router]
        Router --> Tools[Tools Registry]
        
        subgraph "Core Tools"
            Tools --> BacklogGenerator[Backlog Generator]
            Tools --> MarkdownGenerator[Markdown Generator]
            Tools --> StatusChecker[Status Checker]
        end
        
        BacklogGenerator --> OPENAI[OpenAI API]
        BacklogGenerator --> GROQ[Groq API]
        
        MarkdownGenerator --> FileSystem[File System]
    end
    
    C -- "JSON-RPC 2.0" --> E
    W -- "JSON-RPC 2.0" --> E
    CU -- "JSON-RPC 2.0" --> E
```

## Fonctionnement du serveur MCP

Le serveur MCP Agile Planner utilise le protocole JSON-RPC 2.0 pour communiquer avec les clients LLM. Le flux général est le suivant:

### 1. Initialisation

```mermaid
sequenceDiagram
    participant Client as Client LLM
    participant Server as MCP Server
    
    Client->>Server: initialize {version}
    Server->>Server: Vérifier version MCP
    Server-->>Client: {server_info, tools_list}
    Note right of Server: Retourne les informations sur le serveur et les outils disponibles
```

### 2. Appel d'outil

```mermaid
sequenceDiagram
    participant Client as Client LLM
    participant Server as MCP Server
    participant Tools as Tools Registry
    participant Generator as Backlog Generator
    participant LLMAPI as LLM API (OpenAI/Groq)
    
    Client->>Server: tools/call {name, arguments}
    Server->>Tools: Recherche de l'outil
    Tools->>Generator: Appel avec arguments
    Generator->>LLMAPI: Requête de génération
    LLMAPI-->>Generator: Réponse
    Generator-->>Tools: Résultat de la génération
    Tools-->>Server: Résultat traité
    Server-->>Client: {result}
```

## Composants principaux

### MCP Router (`server/lib/mcp-router.js`)

Le routeur MCP est responsable de:
- Recevoir et valider les requêtes JSON-RPC 2.0
- Dispatcher les requêtes vers les handlers appropriés
- Formater les réponses selon la spécification MCP

```javascript
// Exemple simplifié du fonctionnement du routeur MCP
function processRequest(jsonRequest) {
  if (jsonRequest.method === 'initialize') {
    return handleInitialize(jsonRequest);
  } else if (jsonRequest.method === 'tools/list') {
    return handleToolsList(jsonRequest);
  } else if (jsonRequest.method === 'tools/call') {
    return handleToolsCall(jsonRequest);
  } else {
    return createErrorResponse(jsonRequest.id, 'Method not found');
  }
}
```

### Registre d'outils

Les outils disponibles dans Agile Planner MCP incluent:

| Nom | Description | Arguments | Retour |
|-----|-------------|-----------|--------|
| `generateBacklog` | Génère un backlog complet | `projectName`, `projectDescription`, `outputPath` | Structure JSON du backlog |
| `generateFeature` | Génère une feature isolée | `featureTitle`, `featureDescription`, `outputPath` | Structure JSON de la feature |
| `getStatus` | Vérifie le statut du serveur | - | État actuel du serveur |

### Générateur de backlog

Le générateur de backlog est responsable de:
- Construire les prompts pour le LLM (OpenAI/Groq)
- Envoyer les requêtes à l'API appropriée
- Traiter et valider les réponses
- Générer les fichiers markdown correspondants

## Architecture de génération markdown

```mermaid
graph TD
    BacklogJSON[Backlog JSON] --> MarkdownGenerator
    MarkdownGenerator --> EpicFormatter
    MarkdownGenerator --> FeatureFormatter
    MarkdownGenerator --> StoryFormatter
    
    EpicFormatter --> |"epic.md"| FileSystem
    FeatureFormatter --> |"feature.md"| FileSystem
    StoryFormatter --> |"[story-slug].md"| FileSystem
    
    subgraph "Structure de fichiers générée"
        FileSystem --> |".agile-planner-backlog/"| RootDir
        RootDir --> |"epics/"| EpicsDir
        RootDir --> |"orphan-stories/"| OrphanDir
        EpicsDir --> |"[epic-slug]/"| EpicDir
        EpicDir --> |"features/"| FeaturesDir
        FeaturesDir --> |"[feature-slug]/"| FeatureDir
        FeatureDir --> |"user-stories/"| StoriesDir
    end
```

## Modes de fonctionnement

Agile Planner peut fonctionner dans trois modes distincts:

1. **Mode MCP** - Communication via stdio pour intégration avec les LLM
2. **Mode CLI** - Interface en ligne de commande pour utilisation directe
3. **Mode API** - Serveur HTTP pour intégrations personnalisées

Tous les modes partagent le même cœur fonctionnel pour assurer la cohérence.

## Tests et validation

Le système de tests inclut:

- Tests unitaires pour chaque composant
- Tests d'intégration pour le flux complet
- Tests end-to-end spécifiques au protocole MCP

```mermaid
graph LR
    UnitTests --> Composants
    IntegrationTests --> Flows
    E2ETests --> MCPProtocol
    
    subgraph "Tests unitaires"
        Composants --> RouterTest
        Composants --> GeneratorTest
        Composants --> FormatterTest
    end
    
    subgraph "Tests d'intégration"
        Flows --> BacklogFlow
        Flows --> MCPFlow
        Flows --> MarkdownFlow
    end
    
    subgraph "Tests E2E"
        MCPProtocol --> CLITest
        MCPProtocol --> StdioTest
    end
```

## Sécurité et gestion des erreurs

Le serveur MCP inclut plusieurs mécanismes de sécurité:

- Validation des entrées utilisateur
- Gestion des timeouts pour les requêtes LLM
- Logs détaillés pour le débogage
- Mécanismes de reprise sur erreur

## Références

- [Spécification MCP](https://github.com/anthropics/anthropic-cookbook/tree/main/mcp)
- [Documentation JSON-RPC 2.0](https://www.jsonrpc.org/specification)
- [Formats de backlog](./backlog-format.md)