Spec — MCP nexus-code-kg

Objectif

Exposer le Meta KG Applications, c'est-a-dire le Code KG, a Codex et aux agents IA compatibles MCP sans leur donner d'acces DB direct, de secret Nexus ou de filesystem brut.

Le MCP nexus-code-kg est un adaptateur externe au runtime Nexus. Il appelle l'API Nexus, applique les scopes MCP, retourne des paquets courts et preuves, puis laisse Codex relire le code reel avant toute correction.

Le KG documentaire Nexus releve d'une surface MCP separee ciblee nexus-doc-kg. Ne pas melanger les intentions code/SR et les intentions documentaires/metier. Voir aussi 27-Nexus-MCP-Operating-Notes.md pour l'exploitation courante et 28-Nexus-Doc-KG-MCP-Spec.md pour le contrat du MCP documentaire.

Clients cibles

• Codex local sur le serveur Aurora.
• Agent IA web compatible MCP ou tool-calling : ChatGPT, Claude ou equivalent.
• Client interne Nexus futur.

Le contrat des tools doit rester identique quel que soit le transport retenu.

Principes

1. API Nexus uniquement, pas d'acces DB direct.
2. Lecture seule par defaut.
3. Aucun mot de passe Nexus transmis a l'agent IA.
4. Aucun secret retourne.
5. Resolution des findings par preuve structuree, pas par hypothese sur un ID.
6. Relire le code reel avant patch.
7. Actions sensibles separees par scope et validation humaine.

Tools MCP

Regeneration controlee Code KG

kg_regenerate est reserve au Code KG et doit rester orchestre par la SR Method ou par une validation humaine explicite.

Regles minimales :

• le tool doit accepter un mode dry-run par defaut ;
• la mutation reelle exige dry_run=false et confirmed_by_sr=true ;
• les chemins locaux sont reserves au runtime local_stdio et a NEXUS_MCP_LOCAL_REPO_ROOTS ;
• en runtime remote_http, les agents externes utilisent repository + branch; le MCP resout le root API via son registre allowliste, sans exposer de chemin serveur au client ;
• si le worktree est dirty, la mutation reelle exige allow_dirty=true et doit retourner un warning ;
• le tool doit refuser un graphe ambigu ;
• le tool passe par l'API Nexus, pas par la base de donnees ;
• apres regeneration, kg_compare_runs doit comparer le graphe avant/apres si possible.

kg_regenerate ne doit pas etre expose au MCP documentaire nexus-doc-kg par defaut. Le KG documentaire doit plutot retourner un statut ou une alerte si le graphe est absent ou non genere.

Resolution des findings

Les risques IA et prompts exportes peuvent contenir des finding_id lisibles mais non fiables comme qualified_name KG. Le MCP doit donc resoudre les findings par tuple de preuve.

Tuple obligatoire :

(graph_id, source_tool, finding_type, path, line)

Fallback autorise si la ligne est absente :

(graph_id, source_tool, finding_type, path)

Si plusieurs candidats correspondent, le MCP doit retourner :

{
  "status": "ambiguous",
  "candidates": [],
  "required_disambiguation": ["line", "message", "dedupe_key"]
}

Il ne doit pas choisir silencieusement.

Schemas communs

Graph selector

{
  "repository": "syl2042/Nexus-Pocket",
  "branch": "main",
  "graph_id": "optional",
  "latest": true
}

Finding proof

{
  "graph_id": "uuid",
  "source_tool": "nexus_kg|ruff|bandit|osv|audit_ai",
  "finding_type": "bandit_b324_hashlib",
  "path": "services/echo/app/services/meeting_service.py",
  "line": 1094,
  "message": "Use of weak SHA1 hash for security.",
  "severity": "high"
}

Codex action packet

{
  "status": "ready",
  "finding": {},
  "file_context": {},
  "nearby_relations": [],
  "impact": {},
  "recommended_reads": [],
  "recommended_commands": [],
  "safety_notes": []
}

Règles d'usage par intention

Pour les clients qui preferent des tools separes, utiliser kg_regenerate_dry_run puis kg_regenerate_submit au lieu du tool compatible kg_regenerate.

Priorisation

1. High actionnable avec fichier et ligne.
2. Findings bloquants : parsing, imports internes non resolus, runtime probable.
3. Medium avec impact securite, runtime ou architecture.
4. Clusters homogenes Ruff/Bandit valides.
5. Low/info uniquement si demande explicite ou lot dedie.
6. Faux positifs : documenter, ne pas corriger a l'aveugle.

Fraîcheur locale

Les tools avec local_path sont réservés au runtime local stdio et doivent refuser proprement tout autre mode. Le serveur doit limiter les chemins à une allowlist locale, par exemple /home/ubuntu/apps.

Verdicts attendus pour kg_compare_with_local_git :

• fresh : commit graphe égal au HEAD local et worktree propre.
• stale_but_usable : écart limité ou worktree dirty sans croisement direct avec les findings.
• stale : commit différent ou comparaison impossible.
• unsafe_for_patch_decision : worktree dirty touchant des fichiers avec findings, ou situation ambiguë.

Codex ne doit jamais patcher sur la seule base du KG si le verdict n'est pas fresh.

Cycle cible

kg_latest_graph
-> kg_graph_summary
-> kg_list_audit_risks ou kg_list_anomalies
-> kg_get_audit_risk ou kg_get_anomaly
-> kg_file_context / kg_impact
-> lecture du code reel
-> correction
-> tests
-> kg_regenerate si valide
-> kg_compare_runs

Limites du lot courant

Cette spec ne cree pas de serveur MCP, endpoint API, UI, migration ou token. Elle definit le contrat qui guidera l'implementation ulterieure.