Spec — MCP nexus-doc-kg | Auroramind Docs

Objectif

Exposer le KG documentaire Nexus aux applications externes et assistants IA compatibles MCP, sans le confondre avec le Meta KG de code nexus-code-kg.

nexus-doc-kg doit permettre de retrouver des documents, notes, captures, transcriptions, relations et contextes documentaires par utilisateur ou application source, avec droits Nexus et redaction des donnees sensibles.

Perimetre courant

Le MCP documentaire expose :

le KG documentaire Nexus existant ;
les dimensions caller_app, source_app, workspace et project ;
la recherche et l'expansion documentaire ;
des ressources et contextes documentaires bornes ;
les alertes de disponibilite du graphe.

Il ne cible pas :

les findings de code ;
les audits App KG ;
la fraicheur Git locale ;
la regeneration Code KG apres lot SR ;
les corrections Codex sur code reel.

Tools disponibles

Tool	Usage
`doc_kg_status`	Verifier disponibilite API, scopes, graphes documentaires et limites.
`doc_kg_list_source_apps`	Lister les sources documentaires accessibles.
`doc_kg_list_workspaces`	Lister les workspaces d'une `source_app`.
`doc_kg_list_projects`	Lister les projets d'un workspace.
`doc_kg_list_documents`	Lister les documents autorises dans un scope.
`doc_kg_list_resources`	Lister les ressources documentaires representant un scope.
`doc_kg_subgraph`	Lire un sous-graphe documentaire filtre.
`doc_kg_neighbors`	Lire les voisins autorises d'un noeud.
`doc_kg_node`	Lire un noeud documentaire autorise.
`doc_kg_relations`	Lire les relations autorisees autour d'un noeud.
`doc_kg_search`	Rechercher dans le RAG documentaire avec citations/preuves.
`doc_kg_context_pack`	Construire un context pack documentaire borne avec citations, snippets et relations KG.
`doc_kg_query`	Interroger le KG documentaire via l'API Nexus dans un scope borne.

Le serveur est expose sous le nom nexus-doc-kg, schema nexus_doc_kg_mcp.v1, avec readonly=true et mutating_tools=[].

Filtres obligatoires

Les tools doivent accepter, quand applicable :

{
  "caller_app": "codex|nexus-pocket|external-app",
  "source_app": "nexus_pocket_notes|echo|capture|manual",
  "workspace": "workspace_id",
  "project": "project_id",
  "limit": 20
}

Le MCP ne doit jamais elargir silencieusement un scope non autorise. workspace requiert source_app, et project requiert source_app + workspace.

Disponibilite du graphe

Si le KG documentaire est absent, non genere ou inaccessible, le MCP doit retourner :

{
  "status": "graph_unavailable",
  "reason": "not_generated|not_authorized|source_missing|stale",
  "recommended_action": "request_nexus_graph_generation_or_check_permissions"
}

Le MCP documentaire ne doit pas lancer de regeneration directe par defaut.

Securite

API Nexus uniquement, pas d'acces DB direct.
Auth scoped par utilisateur/application.
Aucun secret, token, header Authorization ou payload sensible brut retourne.
Respect strict des droits workspace/project.
Payloads bornes et rediges.
Citations et references documentaires plutot que textes longs non bornes.
Compatible clients OpenAI/Codex : outputSchema, structuredContent et annotations readOnlyHint=true.

Relation avec nexus-code-kg

nexus-code-kg et nexus-doc-kg doivent avoir :

des noms MCP distincts ;
des namespaces Codex distincts ;
des manifests de tools distincts ;
des scopes differents ;
des erreurs explicites si un tool est appele pour le mauvais graphe.

Statut

Implementation locale et endpoint public livres en test utilisateur :

serveur stdio local : scripts/nexus_doc_kg_mcp_server.py ;
serveur HTTP public : scripts/nexus_doc_kg_mcp_http_server.py ;
pack client : MCP Servers/MCP_KG_Docs/ ;
installation Codex locale : namespace nexus-doc-kg ;
endpoint public : https://mcpkgdocs.auroramind.fr/mcp.

Le token public reste stocke hors depot. Cette page ne contient aucun secret.

Spec — MCP nexus-doc-kg

On this page