Operating Notes — Nexus MCP Code KG et Doc KG

Objectif

Documenter l'etat courant des MCP Nexus KG apres les evolutions Code KG V2/V3 et la livraison du MCP documentaire nexus-doc-kg.

Etat courant Code KG

Le MCP Code KG cible se nomme nexus-code-kg.

Le runtime local actuel est porte par :

scripts/nexus_kg_mcp_server.py

Le wrapper local peut conserver un nom historique, par exemple :

~/.codex/bin/nexus-kg-mcp

Le point important est la sortie du check :

~/.codex/bin/nexus-kg-mcp --check

Sortie attendue :

server=nexus-code-kg
version=0.3.0
schema_version=nexus_code_kg_mcp.v3
tools V3 : kg_regenerate, kg_regenerate_dry_run, kg_regenerate_submit, kg_compare_runs

Endpoint public actuel :

https://mcpkgcode.auroramind.fr/mcp

Namespace Codex

Le namespace visible dans Codex depend de ~/.codex/config.toml.

Si la configuration contient :

[mcp_servers.nexus-kg]
command = "/home/ubuntu/.codex/bin/nexus-kg-mcp"

Codex affiche mcp__nexus_kg__....

Pour un namespace coherent avec le serveur Code KG, utiliser :

[mcp_servers.nexus-code-kg]
command = "/home/ubuntu/.codex/bin/nexus-kg-mcp"

Apres modification de la configuration globale Codex, relancer Codex et stopper les anciens processus MCP encore charges si la session voit toujours version=0.2.0.

Cette operation est une mise a jour d'integration Codex, pas une reinstallation du serveur MCP.

Tools Code KG V3

`kg_regenerate`

Tool sensible reserve au Meta KG de code.

Regles :

dry-run par defaut ;
scan reel uniquement avec dry_run=false et confirmed_by_sr=true ;
scan reel soumis en arriere-plan par defaut (wait=false) pour les repos longs; utiliser ensuite kg_latest_graph puis kg_compare_runs ;
worktree dirty autorise seulement avec allow_dirty=true ;
chemins locaux limites a NEXUS_MCP_LOCAL_REPO_ROOTS ;
mapping root hote -> root API via NEXUS_MCP_API_SCAN_ROOTS, avec defaut standard /home/ubuntu/apps -> /repo-scan ;
refus si le graphe courant est ambigu ;
API Nexus uniquement, pas de DB direct.
en remote_http, ne pas fournir local_path; utiliser repository + branch, puis laisser le MCP resoudre le root API allowliste.

Si kg_regenerate retourne cote API Root de scan non autorisé, verifier que le root envoye dans scan_request est bien le chemin vu par le conteneur API (/repo-scan/<repo>), et non le chemin hote (/home/ubuntu/apps/<repo>).

`kg_compare_runs`

Compare deux graphes Code KG avant/apres :

score ;
total findings ;
samples resolved/new ;
deltas par finding_type ;
deltas par source_tool.

Capacites et readonly

kg_status ne doit pas etre lu comme un MCP strictement read-only. Le contrat courant expose :

default_readonly=true ;
readonly=false ;
mutating_tools=["kg_regenerate"] ;
mutations_require_confirmation=true.

Cela signifie que les tools sont de lecture par defaut, sauf kg_regenerate, qui reste une mutation sensible encadree.

Separation Code KG / Doc KG

nexus-code-kg sert Codex et la SR Method :

matching repo ;
fraicheur Git locale ;
audit/findings ;
contexte fichier ;
contexte patch ;
regeneration controlee apres lot SR ;
comparaison avant/apres.

nexus-doc-kg doit servir les usages documentaires/metier :

recherche dans le KG documentaire Nexus ;
resolution par caller_app, source_app, workspace, project ;
contexte documentaire court et cite ;
assistant utilisateur ou application externe ;
alertes si le graphe documentaire est absent ou non disponible.

Le MCP documentaire ne doit pas exposer de regeneration directe par defaut. Si le graphe n'existe pas ou n'a jamais ete genere, le tool doit retourner une alerte explicite et une action recommandee cote Nexus, plutot que lancer une mutation automatiquement.

Etat courant Doc KG

Le MCP documentaire se nomme nexus-doc-kg.

Contrat attendu :

server=nexus-doc-kg ;
schema_version=nexus_doc_kg_mcp.v1 ;
readonly=true ;
mutating_tools=[] ;
filtres : caller_app, source_app, workspace, project.

Endpoint public actuel :

https://mcpkgdocs.auroramind.fr/mcp

Smoke minimal :

doc_kg_status(ping_api=true)
doc_kg_list_source_apps
doc_kg_list_workspaces(source_app="...")
doc_kg_list_projects(source_app="...", workspace="...")
doc_kg_list_resources(source_app="...", workspace="...", project="...", limit=5)
doc_kg_search(query="...", source_app="...", workspace="...", project="...")
doc_kg_context_pack(query="...", source_app="...", workspace="...", project="...")

Smoke attendu apres refresh Codex

Verifier le wrapper :

~/.codex/bin/nexus-kg-mcp --check

Relancer Codex.
Verifier le namespace MCP visible.
Appeler kg_status.
Confirmer que kg_regenerate et kg_compare_runs sont disponibles.
Ne lancer kg_regenerate reel qu'avec validation SR/humaine explicite.

Smoke attendu Doc KG

Verifier le statut doc_kg_status.
Confirmer readonly=true et mutating_tools=[].
Lister une source_app connue.
Lister ses workspaces puis projets.
Lire quelques ressources ou un sous-graphe dans un scope autorise.
Ne jamais demander une regeneration documentaire via ce MCP.

Operating Notes — Nexus MCP Code KG et Doc KG

On this page