# Argus MCP — Cycle Cognitif & Référence des Outils

## Table des matières

- [Vue d'ensemble](#vue-densemble)
- [Architecture du cycle cognitif](#architecture-du-cycle-cognitif)
- [Les 15 outils MCP](#les-15-outils-mcp)
  - [Outils de lecture](#outils-de-lecture)
  - [Outils d'écriture épisodique](#outils-décriture-épisodique)
  - [Outils d'écriture sémantique](#outils-décriture-sémantique)
  - [Outils du cycle cognitif](#outils-du-cycle-cognitif)
- [Ressources MCP](#ressources-mcp)
- [Configuration du cycle](#configuration-du-cycle)
- [Exemple de première utilisation](#exemple-de-première-utilisation)
- [Politiques de sécurité](#politiques-de-sécurité)

---

## Vue d'ensemble

Le MCP Argus expose **15 outils** et **2 ressources** via le protocole MCP (stdio).

> 📖 **Documentation complète** : voir [`REFERENCE.md`](REFERENCE.md) pour la référence
> exhaustive de tous les outils, agents, ressources et profils de contexte.

Le **cycle cognitif** est le mécanisme central de maintenance de la mémoire : il
transforme l'expérience brute (épisodes) en connaissance structurée (patterns,
heuristiques), applique un oubli contrôlé sur les connaissances inutilisées, et
diagnostique la santé globale de la mémoire.

Le cycle suit trois phases **dans un ordre strict** :

```
 Consolidation ──▶ Decay ──▶ Reflection
```

| Phase | Rôle | Mode |
|-------|------|------|
| **Consolidation** | Transforme les épisodes récents en renforcements sémantiques | scan / apply |
| **Decay** | Applique un oubli graduel aux connaissances non utilisées | scan / apply |
| **Reflection** | Diagnostique la mémoire via 12 contrôles de santé | lecture seule |

---

## Architecture du cycle cognitif

### Phase 1 — Consolidation

Parcourt la mémoire épisodique (analyses, incidents, décisions, exécutions) et :

- Identifie les patterns et heuristiques référencés dans les épisodes
- Extrait de nouveaux candidats patterns
- Découvre des associations composant → défaut
- Renforce la confiance des connaissances sémantiques confirmées par l'expérience

Boosts de confiance appliqués :

| Signal | Boost |
|--------|-------|
| Correspondance avec un incident | +0.03 |
| Référencé dans une analyse | +0.02 |
| Heuristique appliquée | +0.01 |

### Phase 2 — Decay (Oubli contrôlé)

Calcule et applique un déclin de confiance sur les patterns et heuristiques
inactifs, avec plusieurs mécanismes de protection :

- **Période de grâce** : aucun decay si utilisé dans les 60 derniers jours
- **Catégories protégées** : `security` et `critical` ne déclinent jamais
- **Incidents critiques** : les patterns liés à des P0/P1 sont protégés
- **Taux réduit** : les patterns avec occurrences > 0 déclinent à 0.02/mois (au lieu de 0.05)
- **Seuil de suppression** : confiance < 0.20 → marqué pour retrait

Taux de decay par catégorie (par mois) :

| Catégorie | Taux | Catégorie | Taux |
|-----------|------|-----------|------|
| performance | 0.03 | regression | 0.06 |
| data_integrity | 0.03 | ui | 0.07 |
| error_handling | 0.04 | seo | 0.06 |
| api | 0.04 | functional | 0.05 |
| accessibility | 0.03 | requirements | 0.05 |
| concurrency | 0.03 | async | 0.04 |
| null_safety | 0.04 | *(défaut)* | 0.05 |

### Phase 3 — Reflection

Exécute **12 contrôles de santé** regroupés en 5 catégories :

| Catégorie | Contrôles |
|-----------|-----------|
| **Cohérence** (3) | Sync compteurs index ↔ fichiers, validité des références croisées |
| **Complétude** (4) | Couverture des types d'épisodes, population relationnelle, validation des champs |
| **Fraîcheur** (3) | Consolidation récente, backlog ≤ 5 épisodes, items à faible confiance (< 0.40) |
| **Équilibre** (2) | Diversité catégorielle (≥ 3), ratio connaissance/expérience |
| **Connectivité** (1) | Détection de cycles dans les associations composant → défaut |

---

## Les 15 outils MCP

> Seuls les 11 outils du cycle cognitif et de la mémoire sont détaillés ici.
> Pour les 4 outils supplémentaires (test scaffold, test cases, audit sécurité,
> audit performance), voir [`REFERENCE.md`](REFERENCE.md).

### Outils de lecture

#### `query_memory` — Interroger la mémoire

Recherche libre dans toutes les sections de la mémoire Argus.

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `section` | string | ✅ | `patterns` · `heuristics` · `analyses` · `decisions` · `incidents` · `executions` · `projects` · `profiles` · `associations` · `stats` · `index` |
| `query` | string | — | Recherche textuelle (nom, description, catégorie) |
| `category` | string | — | Filtre par catégorie (ex: `security`, `api`) |
| `min_confidence` | float | — | Seuil de confiance minimum (0.0–1.0) |
| `limit` | int | — | Résultats max (1–1000, défaut: 100) |
| `offset` | int | — | Offset de pagination |

#### `get_risk_analysis` — Analyser les risques d'un code

Analyse du code source ou un diff unifié contre les 46 patterns de défauts.
Détection multi-signal : indicateurs textuels, patterns de code, signaux techniques.

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `code_or_diff` | string | ✅ | Code source ou diff unifié (max 500 Ko) |
| `context_profile` | string | — | Profil applicatif : `CTX-GENERIC` · `CTX-FINTECH` · `CTX-ECOMMERCE` · `CTX-HEALTH` · `CTX-SAAS` · `CTX-IOT` |
| `file_path` | string | — | Chemin du fichier analysé (pour contexte) |

Retourne : niveau de risque (`critical` / `high` / `medium` / `low`), score max,
patterns détectés avec stratégies.

#### `get_testing_strategy` — Recommander une stratégie de test

Recommande les types de tests et heuristiques applicables selon le changement.

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `change_description` | string | ✅ | Description du changement |
| `change_type` | string | — | `feature` · `bugfix` · `refactoring` · `performance` · `security` · `dependency_update` · `config` |
| `context_profile` | string | — | Profil applicatif (défaut: `CTX-GENERIC`) |
| `components_affected` | list[str] | — | Composants impactés (ex: `["auth", "payment"]`) |

#### `get_memory_health` — Diagnostic de santé mémoire

Lance les 12 contrôles de la réflexion et retourne un rapport complet :
statistiques globales, résultats par catégorie, recommandations.

*Aucun paramètre requis.*

---

### Outils d'écriture épisodique

#### `record_analysis` — Enregistrer une analyse

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `title` | string | ✅ | Titre de l'analyse |
| `findings` | list[dict] | ✅ | Résultats (max 50). Chaque finding : `title`, `risk_level`, `category`, `description`, `recommendation`, et optionnellement `related_patterns`, `related_heuristics`, `confidence` |
| `project` | string | — | Identifiant projet (défaut: `external`) |
| `trigger` | string | — | `manual_request` · `PR_merge` · `incident_response` |
| `scope_type` | string | — | `file` · `PR` · `directory` · `full_project` |
| `scope_reference` | string | — | Référence du scope (chemin, n° PR…) |
| `verdict` | string | — | `approved` · `approved_with_caveats` · `rejected` |

Retourne : `ANL-YYYYMMDD-NNN`

#### `record_decision` — Enregistrer une décision

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `title` | string | ✅ | Titre |
| `context` | string | ✅ | Contexte menant à la décision |
| `decision` | string | ✅ | Décision prise |
| `rationale` | string | ✅ | Justification |
| `project` | string | — | Identifiant projet |
| `alternatives` | list[str] | — | Alternatives considérées |
| `risks` | list[str] | — | Risques identifiés |
| `tags` | list[str] | — | Tags libres |

Retourne : `DEC-YYYYMMDD-NNN`

#### `record_incident` — Enregistrer un incident

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `title` | string | ✅ | Titre |
| `severity` | string | ✅ | `P0` · `P1` · `P2` · `P3` · `P4` |
| `description` | string | ✅ | Description détaillée |
| `project` | string | — | Identifiant projet |
| `root_cause` | string | — | Cause racine identifiée |
| `matched_patterns` | list[str] | — | IDs de patterns Argus (ex: `["PAT-SEC-001"]`) |
| `resolution` | string | — | Résolution appliquée ou planifiée |
| `tags` | list[str] | — | Tags libres |

Retourne : `INC-YYYYMMDD-NNN`

#### `record_execution` — Enregistrer une exécution de tests

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `suite` | string | ✅ | Nom de la suite (ex: `unit-tests`, `e2e-checkout`) |
| `total` | int | ✅ | Tests exécutés |
| `passed` | int | ✅ | Tests réussis |
| `failed` | int | ✅ | Tests échoués |
| `project` | string | — | Identifiant projet |
| `skipped` | int | — | Tests sautés |
| `duration_seconds` | float | — | Durée totale |
| `failures` | list[dict] | — | Détails : `test_name`, `error`, `matched_patterns` |
| `tags` | list[str] | — | Tags libres |

Retourne : `EXC-YYYYMMDD-NNN`

---

### Outils d'écriture sémantique

#### `record_pattern` — Enregistrer un pattern de défaut

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `name` | string | ✅ | Nom du pattern |
| `category` | string | ✅ | `null_safety` · `concurrency` · `async` · `security` · `performance` · `regression` · `api` · `data_integrity` · `error_handling` · `requirements` · `functional` · `accessibility` · `seo` · `ui` |
| `severity_typical` | string | ✅ | `critical` · `high` · `medium` · `low` |
| `description` | string | ✅ | Description du pattern |
| `confidence` | float | — | 0.0–1.0 (défaut: 0.7) |
| `indicators` | list[str] | — | Indicateurs textuels |
| `code_patterns` | list[str] | — | Exemples de code |
| `prevention_strategy` | list[str] | — | Stratégies de prévention |
| `related_owasp` | string | — | Référence OWASP (ex: `A03:2021`) |
| `related_cwe` | string | — | Référence CWE (ex: `CWE-89`) |

Retourne : `PAT-{CAT}-NNN`

#### `record_heuristic` — Enregistrer une heuristique de test

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `name` | string | ✅ | Nom de l'heuristique |
| `category` | string | ✅ | `selection` · `prioritization` · `coverage` · `automation` · `flaky_detection` · `api_testing` · `security_testing` · `accessibility_testing` · `istqb_black_box` · `istqb_white_box` · `istqb_experience` · `istqb_levels` · `istqb_risk` |
| `action` | string | ✅ | Action recommandée |
| `condition` | string | — | Condition d'applicabilité |
| `confidence` | float | — | 0.0–1.0 (défaut: 0.7) |
| `priority` | string | — | `always` · `high_priority` · `when_applicable` · `optional` |
| `rationale` | string | — | Justification |
| `related_patterns` | list[str] | — | IDs de patterns liés |

Retourne : `HEU-{CAT}-NNN`

---

### Outils du cycle cognitif

#### `run_cognitive_cycle` — Lancer le cycle cognitif

Orchestre les trois phases ou exécute une phase individuelle.

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `phase` | string | — | `all` · `consolidation` · `decay` · `reflection` (défaut: `all`) |
| `apply` | bool | — | `true` = applique les changements, `false` = scan uniquement (défaut: `false`) |

Retourne un rapport structuré avec :
- Timestamp et mode (scan/apply)
- Rapport de chaque phase (durée, statut, métriques)
- Statut global : `HEALTHY` · `ACTIONS_NEEDED` · `ISSUES_FOUND` · `ERROR`

---

## Ressources MCP

| URI | Description |
|-----|-------------|
| `argus://persona` | Persona complète (framework CRAFT/TOON) |
| `argus://memory/stats` | Statistiques globales de la mémoire (JSON) |

---

## Configuration du cycle

Les constantes sont définies dans `mcp_server/engines/config.py` :

| Constante | Valeur | Description |
|-----------|--------|-------------|
| `DECAY_RATE` | 0.05/mois | Taux de decay de base |
| `DECAY_RATE_REINFORCED` | 0.02/mois | Taux pour items renforcés (occurrences > 0) |
| `DECAY_THRESHOLD` | 0.20 | Sous ce seuil → candidat au retrait |
| `DECAY_GRACE_DAYS` | 60 | Période de grâce (pas de decay) |
| `PROTECTED_CATEGORIES` | security, critical | Catégories qui ne déclinent jamais |
| `LOW_CONFIDENCE` | 0.40 | Seuil d'alerte « confiance faible » |
| `CONSOLIDATION_LAG_THRESHOLD` | 5 | Max épisodes non consolidés avant alerte |
| `CRITICAL_THRESHOLD` | 15.0 | Score de risque « critical » |
| `HIGH_THRESHOLD` | 8.0 | Score de risque « high » |

---

## Exemple de première utilisation

Ce scénario illustre un workflow complet : diagnostiquer la mémoire, analyser du
code, enregistrer les résultats, puis lancer le cycle cognitif.

### Étape 1 — Vérifier la santé de la mémoire

```
Outil : get_memory_health
```

Réponse attendue : un rapport avec les statistiques (46 patterns, 62
heuristiques, 0 épisodes) et les 12 contrôles de santé. Au premier lancement,
plusieurs contrôles seront en alerte (aucun épisode, pas de consolidation
récente, mémoire relationnelle vide).

### Étape 2 — Analyser un code source

```
Outil : get_risk_analysis
Paramètres :
  code_or_diff: |
    def login(request):
        username = request.POST["username"]
        password = request.POST["password"]
        query = f"SELECT * FROM users WHERE name='{username}' AND pass='{password}'"
        user = db.execute(query).fetchone()
        return JsonResponse({"token": generate_token(user)})
  context_profile: "CTX-SAAS"
  file_path: "auth/views.py"
```

Réponse attendue : niveau `critical`, patterns détectés incluant l'injection SQL
(PAT-SEC-001) et potentiellement l'absence de rate limiting / hash de mot de
passe.

### Étape 3 — Obtenir une stratégie de test

```
Outil : get_testing_strategy
Paramètres :
  change_description: "Refactoring du module d'authentification pour utiliser un ORM"
  change_type: "security"
  context_profile: "CTX-SAAS"
  components_affected: ["auth", "database", "api"]
```

Réponse attendue : recommandation de tests de sécurité (injection, XSS), tests
d'intégration BDD, tests de régression sur les endpoints existants, avec les
heuristiques ISTQB applicables.

### Étape 4 — Enregistrer l'analyse dans la mémoire

```
Outil : record_analysis
Paramètres :
  title: "Audit sécurité module auth"
  project: "mon-projet-saas"
  trigger: "manual_request"
  scope_type: "file"
  scope_reference: "auth/views.py"
  verdict: "rejected"
  findings:
    - title: "Injection SQL via f-string"
      risk_level: "critical"
      category: "security"
      description: "Construction de requête SQL par interpolation directe des entrées utilisateur"
      recommendation: "Utiliser des requêtes paramétrées ou un ORM"
      related_patterns: ["PAT-SEC-001"]
      confidence: 0.95
```

Réponse : `ANL-20260329-001` créé dans `memory/episodic/analyses/`.

### Étape 5 — Enregistrer un incident lié

```
Outil : record_incident
Paramètres :
  title: "Injection SQL détectée en production"
  severity: "P1"
  description: "Le endpoint /api/login est vulnérable à l'injection SQL via le champ username"
  project: "mon-projet-saas"
  root_cause: "Utilisation de f-string pour construire les requêtes SQL"
  matched_patterns: ["PAT-SEC-001"]
  resolution: "Migration vers l'ORM Django en cours"
```

Réponse : `INC-20260329-001` créé.

### Étape 6 — Lancer le cycle cognitif (scan)

```
Outil : run_cognitive_cycle
Paramètres :
  phase: "all"
  apply: false
```

Réponse attendue : rapport en mode scan montrant :
- **Consolidation** : 2 épisodes non consolidés détectés, renforcement
  identifié pour PAT-SEC-001 (+0.03 incident + 0.02 analyse)
- **Decay** : aucun decay à appliquer (tout est frais)
- **Reflection** : amélioration par rapport à l'étape 1 (épisodes présents)

### Étape 7 — Appliquer le cycle

```
Outil : run_cognitive_cycle
Paramètres :
  phase: "all"
  apply: true
```

Le cycle applique les renforcements : la confiance de PAT-SEC-001 augmente,
les épisodes sont marqués comme consolidés, l'index est mis à jour.

---

## Politiques de sécurité

| ID | Politique | Description |
|----|-----------|-------------|
| SEC-001 | Anti-ReDoS | Timeout sur les regex, patterns pré-compilés |
| SEC-002 | Anti-OOM | Limites de taille sur les entrées (500 Ko code, 1000 résultats) |
| SEC-003 | Rate limiting analyses | 100 analyses par jour |
| SEC-004 | Findings cap | Max 50 findings par analyse |
| SEC-005 | Rate limiting sémantique | 200 enregistrements patterns/heuristiques par jour |
| SEC-006 | Path traversal | Validation des chemins, restriction au data dir |
| SEC-007 | File locking | Verrouillage des écritures concurrentes |
| SEC-008 | Rate limiting épisodique | 100 enregistrements épisodiques par jour |
