overmind-mcp 2.2.4 → 2.3.0

package/docs/docs/OVERMIND_WORKFLOW_GUIDE.md

@@ -0,0 +1,595 @@
+# Guide Workflow Client OverMind
+
+## 🎯 Architecture
+
+```
+VOTRE APPLICATION
+       ↓
+OVERMIND-BRIDGE (Wrapper)
+       ↓
+runAgent() (OverMind-MCP)
+       ↓
+AGENT LLM (Claude/Gemini/Kilo)
+```
+
+---
+
+## 📦 Étape 1: Créer le Bridge (overmind-bridge.ts)
+
+Le **bridge** est votre service wrapper qui simplifie l'interaction avec OverMind.
+
+### Code Complet
+
+```typescript
+/**
+ * OVERMIND-BRIDGE SERVICE
+ * Pont universel pour piloter Overmind programmatiquement
+ */
+
+import "./env.js"; // ⚠️ OBLIGATOIRE EN PREMIER (initialisation contexte)
+
+import { runAgent, getMemoryProvider } from "overmind-mcp";
+import { RunnerType } from "./types.js";
+
+export interface ExecutionResult {
+  success: boolean;
+  output?: string;
+  error: string;
+  duration: number;
+}
+
+export class OvermindBridge {
+  /**
+   * Exécute un agent IA avec une mission
+   * @param agentName Nom de l'agent configuré
+   * @param mission Prompt/instruction
+   * @param runner Type de moteur (claude/gemini/kilo/etc)
+   * @returns Résultat de l'exécution
+   */
+  async request(
+    agentName: string,
+    mission: string,
+    runner: RunnerType = "claude",
+    autoResume: boolean = true,
+    cwd?: string,
+  ): Promise<ExecutionResult> {
+    const start = Date.now();
+    try {
+      const result = await runAgent({
+        // @ts-expect-error - overmind-mcp uses 'qwen' internally
+        runner: runner === "qwencli" ? "qwen" : runner,
+        agentName,
+        prompt: mission,
+        autoResume,
+        cwd,
+      });
+
+      const duration = ((Date.now() - start) / 1000).toFixed(1);
+
+      if (result.isError) {
+        const errorText = result.content.find((c) => c.type === "text")?.text || "Unknown error";
+        return {
+          success: false,
+          error: errorText,
+          duration: parseFloat(duration),
+        };
+      }
+
+      const outputText = result.content.find((c) => c.type === "text")?.text || "";
+
+      return {
+        success: true,
+        output: outputText,
+        duration: parseFloat(duration),
+        error: "",
+      };
+    } catch (error: unknown) {
+      const msg = error instanceof Error ? error.message : String(error);
+      console.error(`[OvermindBridge] 💀 CRITICAL ERROR:`, msg);
+      return {
+        success: false,
+        error: msg,
+        duration: 0,
+      };
+    }
+  }
+
+  /**
+   * Enregistre une connaissance dans la mémoire Overmind
+   */
+  async memory_store(
+    text: string,
+    source: "user" | "agent" | "pattern" | "decision" = "agent",
+  ): Promise<string> {
+    try {
+      return await getMemoryProvider().storeKnowledge({ text, source });
+    } catch (err) {
+      console.error(`[OvermindBridge] 🧠 Memory Store Error:`, err);
+      return "";
+    }
+  }
+
+  /**
+   * Recherche dans la mémoire Overmind (RAG)
+   */
+  async memory_search(
+    query: string,
+    limit: number = 5,
+  ): Promise<Array<{ text: string; score: number }>> {
+    try {
+      return await getMemoryProvider().searchMemory({ query, limit });
+    } catch (err) {
+      console.error(`[OvermindBridge] 🔍 Memory Search Error:`, err);
+      return [];
+    }
+  }
+}
+
+// Instance singleton
+export const overmind = new OvermindBridge();
+```
+
+### Points Clés
+
+✅ `import "./env.js"` **OBLIGATOIRE EN PREMIER** (initialisation contexte)
+✅ Wrapper autour de `runAgent()` avec gestion d'erreurs
+✅ Méthodes helper: `memory_store()` et `memory_search()`
+✅ Instance singleton `overmind` pour usage facile
+
+---
+
+## 📋 Étape 2: Créer un Job/Workflow
+
+### Structure d'un Job
+
+```typescript
+import { overmind } from "../overmind-bridge.js";
+import type { JobConfig } from "../types.js";
+
+export const config: JobConfig = {
+  id: "001",
+  name: "Maintenance Agent Divers",
+  agent: "mainteneur_agent_divers",
+  mission: "OBJECTIF : Atteindre 0 défaut...",
+  runner: "claude",
+  frequency: JobFrequency.DAILY,
+  autoResume: false,
+  scheduleTime: { hour: 0, minute: 0 },
+};
+
+async function runStandalone() {
+  const res = await overmind.request(
+    config.agent,
+    config.mission,
+    config.runner,
+    config.autoResume,
+    "C:\\path\\to\\project", // cwd optionnel
+  );
+
+  if (res.success) {
+    console.log(`✅ Succès en ${res.duration}s`);
+    console.log(res.output);
+
+    // Mémoriser le résultat
+    await overmind.memory_store("Job 001 complété avec succès", "agent");
+  } else {
+    console.error(`❌ Erreur: ${res.error}`);
+  }
+}
+
+// Exécution standalone
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(__filename)) {
+  runStandalone().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+```
+
+---
+
+## 🚀 Étape 3: Patterns de Workflows
+
+### Pattern 1: Maintenance Zero Tolerance
+
+```typescript
+const zeroTolerancePrompt = `[ZERO TOLERANCE PROTOCOL v14.4] :
+1. TARGET : Tu es dans C:\\path\\to\\project.
+2. EXECUTE : npm run lint, npm run build, npm run test.
+3. ANALYZE : S'il y a le MOINDRE warning, CORRIGE-LES immédiatement.
+4. FINAL CHECK : Relance le cycle jusqu'à ZERO défaut.
+5. STATUS : Score final 100/100 exigé.`;
+
+const res = await overmind.request(
+  "mainteneur_agent_divers",
+  zeroTolerancePrompt,
+  "claude",
+  false,
+  "C:\\path\\to\\project"
+);
+```
+
+### Pattern 2: Workflow Multi-Étapes
+
+```typescript
+// Étape 1: Analyser
+const analysis = await overmind.request(
+  "analyste",
+  "Analyse ce code et identifie les problèmes..."
+);
+
+if (!analysis.success) {
+  throw new Error(analysis.error);
+}
+
+// Étape 2: Corriger
+const fix = await overmind.request(
+  "correcteur",
+  `Corrige les problèmes identifiés: ${analysis.output}`
+);
+
+// Étape 3: Vérifier
+const verify = await overmind.request(
+  "verificateur",
+  "Vérifie que tout est corrigé..."
+);
+```
+
+### Pattern 3: Workflow Multi-Agents Parallèle
+
+```typescript
+import { runAgents_parallel } from "overmind-mcp";
+
+// Exécuter 3 agents en parallèle
+const results = await runAgents_parallel({
+  agents: [
+    {
+      taskId: "lint",
+      runner: "claude",
+      agentName: "linter",
+      prompt: "Exécute npm run lint et corrige les warnings"
+    },
+    {
+      taskId: "build",
+      runner: "claude",
+      agentName: "builder",
+      prompt: "Exécute npm run build et corrige les erreurs"
+    },
+    {
+      taskId: "test",
+      runner: "claude",
+      agentName: "tester",
+      prompt: "Exécute npm run test et corrige les failures"
+    }
+  ],
+  waitAll: true // Attendre tous les agents
+});
+```
+
+### Pattern 4: Retry avec Fallback
+
+```typescript
+async function executeWithRetry(
+  agentName: string,
+  mission: string,
+  maxRetries: number = 3
+) {
+  for (let i = 0; i < maxRetries; i++) {
+    const res = await overmind.request(agentName, mission);
+
+    if (res.success) {
+      return res;
+    }
+
+    console.warn(`Tentative ${i + 1}/${maxRetries} échouée`);
+
+    if (i < maxRetries - 1) {
+      // Attendre avant retry
+      await new Promise(resolve => setTimeout(resolve, 2000));
+    }
+  }
+
+  throw new Error("Échec après " + maxRetries + " tentatives");
+}
+```
+
+### Pattern 5: Workflow avec Mémoire
+
+```typescript
+// 1. Rechercher dans la mémoire
+const previous = await overmind.memory_search("maintenance workflow");
+
+// 2. Créer le prompt avec contexte
+const contextPrompt = `
+CONTEXTE HISTORIQUE :
+${previous.map(r => r.text).join("\n")}
+
+MISSION ACTUELLE :
+Maintenance Zero Tolerance du projet...
+`;
+
+// 3. Exécuter
+const res = await overmind.request("mainteneur", contextPrompt);
+
+// 4. Mémoriser le résultat
+if (res.success) {
+  await overmind.memory_store(
+    `Maintenance complétée: ${res.output.substring(0, 100)}...`,
+    "agent"
+  );
+}
+```
+
+---
+
+## 🎨 Étape 4: Types et Configurations
+
+### types.ts
+
+```typescript
+export type RunnerType =
+  | "claude"
+  | "gemini"
+  | "kilo"
+  | "qwencli"
+  | "openclaw"
+  | "cline"
+  | "opencode"
+  | "hermes";
+
+export enum JobFrequency {
+  MANUAL = "MANUAL",
+  HOURLY = "HOURLY",
+  DAILY = "DAILY",
+  WEEKLY = "WEEKLY",
+  MONTHLY = "MONTHLY",
+}
+
+export interface JobConfig {
+  id: string;
+  name: string;
+  agent: string;
+  shortDescription: string;
+  mission: string;
+  runner: RunnerType;
+  frequency: JobFrequency;
+  autoResume: boolean;
+  scheduleTime?: { hour: number; minute: number };
+  secondScheduleTime?: { hour: number; minute: number };
+}
+```
+
+---
+
+## 🔧 Étape 5: Bonnes Pratiques
+
+### ✅ À Faire
+
+1. **Initialiser le contexte en premier**
+   ```typescript
+   import "./env.js"; // TOUJOURS EN PREMIER
+   ```
+
+2. **Gérer les erreurs**
+   ```typescript
+   try {
+     const res = await overmind.request(...);
+     if (!res.success) {
+       console.error(res.error);
+       return;
+     }
+   } catch (err) {
+     console.error(err);
+   }
+   ```
+
+3. **Spécifier le cwd**
+   ```typescript
+   const res = await overmind.request(
+     agent,
+     mission,
+     runner,
+     false,
+     "C:\\path\\to\\project" // cwd explicite
+   );
+   ```
+
+4. **Utiliser la mémoire**
+   ```typescript
+   await overmind.memory_store("Information importante", "user");
+   const results = await overmind.memory_search("requete");
+   ```
+
+5. **Logger les durées**
+   ```typescript
+   console.log(`Terminé en ${res.duration}s`);
+   ```
+
+### ❌ À Éviter
+
+1. **Oublier l'initialisation du contexte**
+   ```typescript
+   // ❌ FAUX
+   import { runAgent } from "overmind-mcp";
+
+   // ✅ CORRECT
+   import "./env.js";
+   import { runAgent } from "overmind-mcp";
+   ```
+
+2. **Ignorer les erreurs**
+   ```typescript
+   // ❌ FAUX
+   await overmind.request(agent, mission);
+
+   // ✅ CORRECT
+   const res = await overmind.request(agent, mission);
+   if (!res.success) {
+     // Gérer l'erreur
+   }
+   ```
+
+3. **Prompt trop vague**
+   ```typescript
+   // ❌ FAUX
+   await overmind.request(agent, "Corrige les erreurs");
+
+   // ✅ CORRECT
+   const prompt = `[ZERO TOLERANCE PROTOCOL] :
+   1. Exécute npm run lint
+   2. Corrige TOUTES les erreurs
+   3. Relance jusqu'à 0 défaut`;
+   ```
+
+---
+
+## 📚 Étape 6: Exemples Complets
+
+### Exemple 1: Job de Maintenance Complet
+
+```typescript
+import { overmind } from "../overmind-bridge.js";
+import type { JobConfig } from "../types.js";
+import { JobFrequency } from "../types.js";
+import path from "path";
+import { fileURLToPath } from "url";
+
+export const config: JobConfig = {
+  id: "001",
+  name: "Maintenance Zero Tolerance",
+  agent: "mainteneur",
+  shortDescription: "Lint/Build/Test complet",
+  mission: `OBJECTIF 0 DÉFAUT (v14.4) :
+    1. LINT : Atteindre 0 warning via 'npm run lint'
+    2. BUILD : Atteindre 0 erreur via 'npm run build'
+    3. TEST : 100% réussite via 'npm run test'
+    4. FIXING : Corriger activement tout écart`,
+  runner: "claude",
+  frequency: JobFrequency.DAILY,
+  autoResume: false,
+  scheduleTime: { hour: 0, minute: 0 },
+};
+
+async function runStandalone() {
+  console.log(`🚀 [MISSION: ${config.id}] ${config.name}`);
+  const startTime = Date.now();
+
+  try {
+    const prompt = `[ZERO TOLERANCE PROTOCOL v14.4] :
+    1. TARGET : Tu es dans C:\\path\\to\\project.
+    2. EXECUTE : npm run lint, npm run build, npm run test.
+    3. ANALYZE : S'il y a le MOINDRE warning, CORRIGE-LES.
+    4. FINAL CHECK : Relance jusqu'à ZERO défaut.
+    5. STATUS : Score final 100/100 exigé.
+
+    ${config.mission}`;
+
+    const res = await overmind.request(
+      config.agent,
+      prompt,
+      config.runner,
+      false,
+      "C:\\path\\to\\project"
+    );
+
+    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+    if (res.success) {
+      console.log(`✅ Terminé en ${duration}s`);
+      console.log(res.output);
+
+      await overmind.memory_store(
+        `Job ${config.id} complété avec succès (0 défaut)`,
+        "agent"
+      );
+    } else {
+      console.error(`❌ Erreur: ${res.error}`);
+    }
+  } catch (err) {
+    console.error("Erreur critique:", err);
+  }
+}
+
+// Exécution standalone
+const __filename = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(__filename)) {
+  runStandalone().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+```
+
+### Exemple 2: Workflow Multi-Projets
+
+```typescript
+import { overmind } from "../overmind-bridge.js";
+
+const PROJECTS = [
+  { name: "agent-divers", path: "C:\\SierraChart\\ACS_Source\\BTCacsil\\agent_multi" },
+  { name: "workflow", path: "C:\\Users\\Deamon\\Desktop\\Backup\\Serveur MCP\\Workflow" },
+];
+
+async function maintenanceAllProjects() {
+  const results = [];
+
+  for (const project of PROJECTS) {
+    console.log(`\n🔧 Maintenance de ${project.name}...`);
+
+    const res = await overmind.request(
+      "mainteneur",
+      `[MAINTENANCE PROJECT: ${project.name}]
+      1. cd ${project.path}
+      2. npm run lint
+      3. npm run build
+      4. npm run test
+      5. Corriger tous les défauts`,
+      "claude",
+      false,
+      project.path
+    );
+
+    results.push({
+      project: project.name,
+      success: res.success,
+      duration: res.duration,
+      output: res.output?.substring(0, 200) + "..."
+    });
+  }
+
+  // Rapport final
+  console.log("\n📊 RAPPORT GLOBAL:");
+  results.forEach(r => {
+    const icon = r.success ? "✅" : "❌";
+    console.log(`${icon} ${r.project}: ${r.duration}s`);
+  });
+
+  // Mémoriser
+  const successCount = results.filter(r => r.success).length;
+  await overmind.memory_store(
+    `Maintenance multi-projets: ${successCount}/${results.length} réussis`,
+    "agent"
+  );
+}
+
+maintenanceAllProjects().catch(console.error);
+```
+
+---
+
+## 🎯 Conclusion
+
+**Workflow Client OverMind = 3 Étapes**:
+
+1. **overmind-bridge.ts** - Wrapper service autour de `runAgent()`
+2. **jobs/JOB_XXX.ts** - Configurations et logique métier
+3. **runStandalone()** - Exécution avec gestion d'erreurs
+
+**Points Clés**:
+- ✅ `import "./env.js"` OBLIGATOIRE EN PREMIER
+- ✅ Gestion d'erreurs robuste
+- ✅ Mémoire vectorielle pour persistence
+- ✅ Multi-agents parallèle possibles
+- ✅ Retry et fallback automatiques
+
+**Architecture = Flexibilité Maximale**: Vous pouvez créer n'importe quel workflow en combinant ces patterns.

package/docs/docs/PROJECT_STRUCTURE.md

@@ -0,0 +1,101 @@
+# 📁 Structure du Projet OverMind MCP
+
+Organisation des dossiers et fichiers pour une meilleure navigation et maintenance.
+
+## 📂 Arborescence
+
+```
+Workflow/
+├── 📦 bin/                    # Scripts d'installation
+│   ├── install-overmind-unix.sh
+│   ├── install-overmind-windows.bat
+│   └── README.md
+├── 📋 changelog/             # Historique des versions
+│   ├── CHANGELOG.md
+│   ├── CHANGELOG.2.0.7.md
+│   ├── CHANGELOG_ENV_FIX.md
+│   └── README.md
+├── 🐳 docker/                # Configuration Docker
+│   ├── docker-compose.yml
+│   └── README.md
+├── 🗄️ db/                    # Scripts base de données
+│   ├── init-db.sql
+│   ├── init-overmind-db.sql
+│   └── README.md
+├── ⚙️ config/               # Configurations MCP
+│   ├── mcp-config.json
+│   └── README.md
+├── 📚 docs/                  # Documentation complète
+│   ├── api/                   # Documentation API
+│   ├── guides/                # Guides d'utilisation
+│   └── tools.md               # Référence des outils
+├── 🔧 scripts/              # Scripts de maintenance
+│   ├── setup.mjs
+│   ├── postgres-manager.mjs
+│   └── uninstall.mjs
+├── 💻 src/                   # Code source
+│   ├── bin/                  # Points d'entrée CLI
+│   ├── lib/                  # Bibliothèques partagées
+│   ├── services/             # Services métier
+│   ├── tools/                # Outils MCP
+│   └── server.ts             # Serveur MCP principal
+├── 🧪 tests/                 # Tests unitaires
+└── 📦 assets/               # Ressources (images, bannières)
+```
+
+## 🎯 Organisation par type de fichier
+
+### 📦 bin/ - Scripts d'installation
+Contient les scripts pour installer OverMind MCP sur différents systèmes.
+
+### 📋 changelog/ - Historique des versions
+Tous les changelogs organisés par version avec format standardisé.
+
+### 🐳 docker/ - Configuration Docker
+Stack Docker Compose avec tous les services nécessaires.
+
+### 🗄️ db/ - Scripts base de données
+Scripts SQL pour l'initialisation et la maintenance PostgreSQL.
+
+### ⚙️ config/ - Configurations MCP
+Exemples de configurations MCP pour différents scénarios d'utilisation.
+
+## 🔍 Navigation rapide
+
+### Pour les développeurs
+```bash
+# Installer
+bin/install-overmind-unix.sh
+
+# Démarrer Docker
+cd docker && docker-compose up -d
+
+# Initialiser la BD
+cat db/init-overmind-db.sql | docker exec -i overmind-postgres-pgvector psql -U postgres
+```
+
+### Pour les utilisateurs
+```bash
+# Voir les changelogs
+ls changelog/
+
+# Lire la doc d'un dossier
+cat config/README.md
+cat docker/README.md
+```
+
+## 📝 Conventions
+
+### Nouveaux fichiers
+- **Scripts** → `bin/`
+- **Changelogs** → `changelog/`
+- **Docker** → `docker/`
+- **SQL** → `db/`
+- **Config** → `config/`
+- **Documentation** → `docs/`
+
+### Avantages de cette organisation
+1. **Navigation claire** - Chaque type de fichier a son emplacement
+2. **Maintenance facilitée** - Scripts et config regroupés
+3. **Documentation contextuelle** - README dans chaque dossier
+4. **Professional** - Structure organisée selon les standards Node.js