Skip to content

mcp-server-architecture.md

Latest commit

 

History

History
200 lines (153 loc) · 6.05 KB

mcp-server-architecture.md

File metadata and controls

200 lines (153 loc) · 6.05 KB
Raw

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

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
Loading

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

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
Loading

2. Appel d'outil

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

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

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
Loading

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

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