Runtime — MCP nexus-code-kg V3

Objectif

Completer le MCP Code KG avec une regeneration controlee apres correction SR, sans donner d'acces DB direct et sans scanner un chemin arbitraire.

Le serveur se presente comme nexus-code-kg. Les tools gardent le prefixe historique kg_* pour compatibilite.

Notes d'exploitation, refresh Codex et separation avec le futur MCP documentaire : voir 27-Nexus-MCP-Operating-Notes.md.

Tools V3

• kg_regenerate
• kg_regenerate_dry_run
• kg_regenerate_submit
• kg_compare_runs

kg_regenerate

Le tool prepare ou lance une regeneration du Meta KG de code a partir d'un repo local autorise en local_stdio, ou d'un repository distant allowliste en remote_http.

Parametres principaux :

{
  "graph_id": "uuid optionnel",
  "local_path": "/home/ubuntu/apps/Aurora_rag_public optionnel en local_stdio",
  "repository": "owner/repo ou local/name optionnel",
  "branch": "main optionnel",
  "source_app": "optionnel",
  "workspace": "optionnel",
  "project": "optionnel",
  "max_files": 4000,
  "dry_run": true,
  "confirmed_by_sr": false,
  "allow_dirty": false,
  "wait": false,
  "compare_after": false
}

Regles :

• dry_run=true par defaut appelle seulement POST /api/meta-kg/repositories/pre-scan.
• la regeneration reelle appelle POST /api/meta-kg/repositories/scan;
• la regeneration reelle exige dry_run=false et confirmed_by_sr=true;
• par defaut, la regeneration reelle est soumise en arriere-plan (wait=false) pour eviter qu'un scan long cree un graphe cote API tout en expirant cote client MCP;
• wait=true force un appel synchrone et doit rester reserve aux scans courts ou aux tests controles;
• compare_after=true lance kg_compare_runs automatiquement seulement si l'appel synchrone retourne un graph_after;
• si le worktree est dirty, la regeneration reelle exige aussi allow_dirty=true;
• local_path est refuse hors local_stdio ou hors NEXUS_MCP_LOCAL_REPO_ROOTS;
• en remote_http, les agents externes ne fournissent pas de chemin serveur : ils fournissent repository + branch, et le MCP resout le root API via NEXUS_MCP_REMOTE_REPOSITORIES;
• les repositories non declares dans le registre distant sont refuses;
• le chemin local utilise pour Git peut etre traduit avant appel API via NEXUS_MCP_API_SCAN_ROOTS, afin de convertir par exemple /home/ubuntu/apps/Aurora_rag_public en /repo-scan/Aurora_rag_public quand l'API Nexus tourne dans Docker;
• si aucun graph_id n'est fourni, le tool utilise kg_match_current_repo et refuse les cas ambigus.

Tools split OpenAI/Codex

Pour les clients qui traitent prudemment les tools mutateurs, la regeneration est aussi exposee en deux tools explicites :

kg_regenerate reste disponible pour compatibilite avec les clients MCP existants.

Mapping root MCP -> API

Le MCP valide le repo sur le filesystem local de Codex. L'API Nexus valide le root selon AURORA_META_KG_ALLOWED_ROOT, typiquement /repo-scan dans le conteneur API.

Configuration standard :

NEXUS_MCP_LOCAL_REPO_ROOTS=/home/ubuntu/apps
NEXUS_MCP_API_SCAN_ROOTS=/repo-scan
NEXUS_MCP_REMOTE_REPOSITORIES=syl2042/Nexus-Pocket=/repo-scan/Nexus-pocket

Avec cette configuration, kg_regenerate garde le chemin local pour les controles Git, mais envoie a l'API :

/repo-scan/<repo>

Si NEXUS_MCP_API_SCAN_ROOTS est absent dans l'installation standard, le MCP infere /repo-scan pour la racine locale par defaut /home/ubuntu/apps.

kg_compare_runs

Compare deux graphes Meta KG :

• score avant/apres ;
• total findings avant/apres ;
• resolved/new samples par dedupe_key ou id ;
• delta par finding_type ;
• delta par source_tool.

La comparaison repose sur les endpoints API existants :

• GET /api/meta-kg/audit
• GET /api/meta-kg/anomalies

Flow SR cible

tests du lot SR OK
-> kg_regenerate(dry_run=true)
-> validation SR / decision de cloture
-> kg_regenerate(dry_run=false, confirmed_by_sr=true, allow_dirty=<si requis>, wait=false)
-> kg_latest_graph(repository, branch)
-> kg_compare_runs(before_graph_id, after_graph_id)
-> noter graph_before, graph_after et deltas dans la memoire SR

Pour un agent web ou ChatGPT, le flow ne doit pas demander local_path :

kg_latest_graph(repository, branch)
-> kg_graph_summary(graph_id)
-> kg_regenerate_dry_run(repository, branch, max_files)
-> validation humaine/SR
-> kg_regenerate_submit(repository, branch, confirmed_by_sr=true, max_files)
-> kg_latest_graph(repository, branch)
-> kg_compare_runs(before_graph_id, after_graph_id)

Limites

• La SR Method decide quand appeler le tool.
• Le MCP n'ecrit pas dans SR_LOTS.yaml ou CURRENT_STATE.md.
• Le MCP documentaire cible nexus-doc-kg reste separe et ne doit pas exposer de regeneration directe par defaut.
• Une regeneration peut produire un nouveau graphe identique en contenu si le repository n'a pas change; kg_compare_runs reste la preuve attendue.