Spec — Installation MCP Nexus KG

Objectif

Prevoir une installation portable des MCP Nexus KG pour Codex local et agents IA web, sans imposer un runtime unique dans la conception.

Deux surfaces doivent rester distinctes :

• nexus-api : API/RAG Nexus en OAuth utilisateur, orienté assistants externes et accès aux données Nexus autorisées.
• nexus-code-kg : Meta KG de code, orienté Codex/SR, findings, audit, regeneration controlee et comparaison avant/apres.
• nexus-doc-kg : KG documentaire/metier Nexus, orienté recherche, récupération de contexte documentaire et reponses utilisateur, sans regeneration directe par defaut.

Endpoints publics actuels

Les endpoints publics utilisent un bearer token ou une authentification future equivalente. Les tokens restent stockes hors depot.

Modes supportes

Mode local Codex

Usage :

Codex local -> MCP nexus-code-kg local -> API Nexus

Configuration cible :

{
  "name": "nexus-code-kg",
  "base_url": "https://nexus.auroramind.fr",
  "auth": {
    "type": "bearer",
    "env": "NEXUS_MCP_TOKEN"
  },
  "default_scopes": ["kg:read", "kg:audit:read", "kg:export:read"],
  "sensitive_tools": ["kg_regenerate"]
}

Le token reste dans l'environnement local ou dans un store de secrets, jamais dans le repository.

Namespace Codex et nom serveur

Codex nomme le namespace MCP depuis la cle mcp_servers.<name> de ~/.codex/config.toml, pas depuis le champ server retourne par kg_status.

Exemple :

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

donne un namespace MCP cible mcp__nexus_code_kg__....

Si la cle reste [mcp_servers.nexus-kg], Codex affichera encore mcp__nexus_kg__... meme si le serveur runtime retourne server=nexus-code-kg.

Controle local attendu :

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

La sortie doit indiquer server=nexus-code-kg, version=0.3.0 et les tools kg_regenerate / kg_compare_runs.

Si une session Codex relancee voit encore version=0.2.0, verifier les anciens processus nexus_kg_mcp_server.py, les stopper proprement, puis relancer Codex ou son app-server. Ne pas modifier le repository applicatif pour cette operation.

Mode agent IA web

Usage :

ChatGPT / Claude / agent IA
-> connecteur MCP
-> autorisation Nexus
-> API Nexus

Deux variantes sont prevues :

1. OAuth/OIDC ou consentement Nexus cible.
2. Token MCP manuel comme fallback.

Le connecteur doit annoncer ses scopes, son client et ses limites avant autorisation.

Capabilities manifest

Le MCP doit exposer ou documenter un manifeste de capacites :

{
  "name": "nexus-code-kg",
  "version": "0.3",
  "tools": [
    {
      "name": "kg_status",
      "scope": "kg:read",
      "readonly": true
    },
    {
      "name": "kg_regenerate",
      "scope": "kg:regenerate:request",
      "readonly": false,
      "sensitive": true
    }
  ],
  "auth_modes": ["local_token", "manual_token", "oauth_consent"],
  "default_readonly": true
}

Variables d'environnement cibles

NEXUS_BASE_URL
NEXUS_MCP_TOKEN
NEXUS_MCP_SERVICE_TOKEN_SHA256
NEXUS_MCP_SERVICE_TOKEN_SHA256_LIST
NEXUS_MCP_SCOPE
NEXUS_MCP_MODE
NEXUS_MCP_TIMEOUT_SECONDS
NEXUS_MCP_READONLY
NEXUS_MCP_LOCAL_REPO_ROOTS
NEXUS_MCP_API_SCAN_ROOTS
NEXUS_MCP_REMOTE_REPOSITORIES

Pour le runtime Code KG local standard, le mapping de scan attendu est :

NEXUS_MCP_LOCAL_REPO_ROOTS=/home/ubuntu/apps
NEXUS_MCP_API_SCAN_ROOTS=/repo-scan

Il permet au MCP de verifier Git sur le chemin hote tout en envoyant a l'API Nexus le chemin monte dans le conteneur.

NEXUS_MCP_TOKEN est le secret brut lu par le wrapper Codex local. Il ne doit pas etre un JWT utilisateur Nexus. L'API Nexus ne stocke que son hash SHA-256 via NEXUS_MCP_SERVICE_TOKEN_SHA256; NEXUS_MCP_SERVICE_TOKEN_SHA256_LIST permet une rotation temporaire avec plusieurs hashes separes par des virgules.

Regles de packaging

• Meme contrat de tools pour tous les clients.
• Adapter seulement le transport et l'auth.
• Ne pas embarquer de secret dans le package.
• Ne pas donner acces au filesystem du serveur a un agent web.
• Garder les payloads bornes et rediges.
• Retourner des erreurs explicites si scope ou consentement absent.

Procedure cible Codex local

1. Installer ou declarer le MCP nexus-code-kg.
2. Configurer NEXUS_BASE_URL.
3. Configurer un token scoped.
4. Verifier ~/.codex/bin/nexus-kg-mcp --check.
5. Relancer Codex si le namespace ou la version MCP active ne sont pas a jour.
6. Utiliser la skill projet Meta KG pour choisir les tools.

Procedure cible agent web

1. Ajouter le connecteur Nexus KG concerne.
2. Se connecter via Nexus ou renseigner un token MCP manuel.
3. Verifier les scopes demandes.
4. Autoriser lecture des graphes/audits.
5. Interdire actions sensibles par defaut.
6. Utiliser les tools en lecture avant toute correction.

Pour nexus-api, utiliser OAuth et non un bearer token manuel quand le client le permet. Le connecteur redirige vers Nexus, recupere un JWT utilisateur et le transmet ensuite aux endpoints Nexus. Les droits restent ceux de l'utilisateur.

Limites

• OAuth multi-utilisateur reste a cadrer; le bearer token manuel est le mode operationnel actuel pour les tests ChatGPT-style.
• nexus-doc-kg est lecture seule et ne doit pas lancer de regeneration.
• nexus-code-kg peut regenerer uniquement dans les scopes allowlistes et avec confirmation explicite. Elle prepare l'installation pour le lot runtime futur.