Runtime — MCP nexus-kg V2

Note 2026-06-03 : la surface code est clarifiee sous le nom serveur nexus-code-kg en V3. Voir 26-Nexus-Code-KG-MCP-Runtime-V3.md pour les tools de regeneration controlee kg_regenerate et kg_compare_runs.

Objectif

Rendre le MCP nexus-kg directement exploitable par Codex comme couche d'orientation : trouver le bon graphe, vérifier sa fraîcheur par rapport au Git local, prioriser les findings utiles et construire un contexte minimal avant patch.

Le MCP reste read-only en V2. Le KG n'est jamais la source finale : Codex doit relire le code réel local avant toute modification.

Configuration

NEXUS_BASE_URL=http://127.0.0.1:18500
NEXUS_MCP_TOKEN=<token Nexus bearer>
NEXUS_MCP_TIMEOUT_SECONDS=20
NEXUS_MCP_RUNTIME_MODE=local_stdio
NEXUS_MCP_LOCAL_REPO_ROOTS=/home/ubuntu/apps

NEXUS_MCP_RUNTIME_MODE=local_stdio est le seul mode autorisant les tools avec local_path. En mode futur web ou remote_http, ces tools retournent un refus structuré.

Nouveaux tools V2

• kg_match_current_repo
• kg_compare_with_local_git
• kg_top_actionable_findings
• kg_patch_context

kg_file_context accepte aussi un mode compact :

{
  "compact": true,
  "include_relations": false,
  "include_symbols": true,
  "include_findings": true
}

Garde-fous filesystem

Un local_path est accepté seulement si :

1. le runtime est local_stdio;
2. le chemin est sous une racine autorisée par NEXUS_MCP_LOCAL_REPO_ROOTS;
3. le chemin appartient à un dépôt Git;
4. la racine Git reste sous les racines autorisées.

Sinon le MCP répond par exemple :

{
  "status": "refused",
  "reason": "local_path_not_allowed",
  "next_tools": ["kg_latest_graph", "kg_graph_summary"]
}

Matching repo

kg_match_current_repo normalise les remotes GitHub SSH/HTTPS, lit la branche, le HEAD et les graphes récents, puis score les candidats.

Le MCP ne choisit pas silencieusement si plusieurs candidats sont proches. Il retourne ambiguous et demande repository, branch ou graph_id.

Fraîcheur Git

kg_compare_with_local_git retourne un verdict :

• fresh
• stale_but_usable
• stale
• unsafe_for_patch_decision

Si le worktree local est dirty et que des fichiers modifiés croisent les findings KG, le verdict est unsafe_for_patch_decision.

Priorisation

kg_top_actionable_findings favorise :

1. findings high/critical en code productif;
2. sécurité et runtime;
3. imports internes qui réduisent la couverture KG;
4. Ruff actionnable;
5. Bandit low hors tests.

Par défaut, les asserts dans les tests ne remontent pas en premier.

Réponses V2

Les réponses enrichies contiennent :

• schema_version;
• warnings;
• confidence;
• next_tools;
• redaction_report.

Une redaction commune masque les valeurs ressemblant à tokens, JWT, clés API, secrets ou headers d'autorisation.

Flow conseillé

kg_status
-> kg_match_current_repo(local_path)
-> kg_compare_with_local_git(graph_id, local_path)
-> kg_graph_summary(graph_id)
-> kg_top_actionable_findings(graph_id)
-> kg_patch_context(graph_id, id)
-> lecture code réel local
-> patch + tests