neo4j-graph-ops — Le graphe, en lecture d'abord

Le graphe est la mémoire relationnelle de la stack : entités (personnes, projets, articles, organisations, versions) et leurs liens. Une requête mal écrite en lecture coûte du temps ; une écriture mal écrite coûte des données. D'où l'ordre : schéma → lecture → proposition d'écriture → GO → écriture.

1. Brancher le serveur MCP (une fois par plugin)

Le serveur officiel neo4j/mcp expose quatre tools : get-schema, read-cypher, write-cypher, list-gds-procedures. Il se configure dans le .mcp.json du plugin (fourni à la racine de tk-knowledge) et lit ses paramètres uniquement dans l'environnement :

Variable	Rôle	Valeur
NEO4J_URI	adresse bolt	bolt://127.0.0.1:7687 en local
NEO4J_USERNAME / NEO4J_PASSWORD	identifiants	jamais en clair dans un fichier versionné
NEO4J_DATABASE	base cible	neo4j par défaut
NEO4J_READ_ONLY	true désactive write-cypher	true par défaut ; passer à false seulement pour une session d'écriture décidée

Installation : pip install neo4j-mcp-server (module python -m neo4j_mcp_server, transport stdio). Le dépôt contient aussi un binaire Go neo4j-mcp (cmd/neo4j-mcp) ; méthode d'installation du binaire à vérifier selon la plateforme. Détails et exemples : references/mcp-neo4j.md.

Le mot de passe vit dans le gestionnaire d'identifiants du système ou une variable de session : on ne le lit pas, on ne l'affiche pas, on ne le colle pas dans un .mcp.json.

2. Séquence de travail

1. Schéma d'abord — get-schema avant toute requête. Les labels et types de relations réels priment sur ce qu'on croit savoir ; un graphe alimenté par plusieurs collecteurs dérive.
2. Lecture — read-cypher avec LIMIT explicite (≤ 100 par défaut) et paramètres nommés ($titre, $id) plutôt que des valeurs concaténées dans la chaîne.
3. Compter avant de toucher — pour toute modification envisagée, exécuter d'abord le MATCH correspondant avec RETURN count(*). Le chiffre est annoncé à l'utilisateur.
4. Proposer l'écriture — présenter la requête write-cypher complète, le nombre de nœuds ou relations touchés, et la requête inverse (comment revenir en arrière). Attendre le GO.
5. Écrire — MERGE plutôt que CREATE (idempotence), propriétés de provenance sur chaque élément écrit : source, collecte_le (ISO 8601), confiance.
6. Vérifier — relire ce qui vient d'être écrit ; rendre compte avec les compteurs.

Un DELETE ou DETACH DELETE n'est jamais proposé en première intention : on marque (archive_le, remplace_par) — principe NO-DROP. Si la suppression est vraiment demandée, elle passe par un export préalable des éléments concernés (references/cypher-patterns.md, §Archivage).

3. Patterns du domaine

Le modèle type est Personne → Projet → Version, avec articles et organisations en périphérie :

// Projets d'une personne, avec leurs versions
MATCH (p:Personne {nom: $nom})-[:AUTEUR_DE]->(o:Projet)
OPTIONAL MATCH (o)-[:PUBLIE_EN]->(a:Version)
RETURN o.nom, o.type, collect(a.type) AS versions
ORDER BY o.debut
LIMIT 100

Les noms de labels ci-dessus sont génériques : les vrais viennent de get-schema. Le fichier references/cypher-patterns.md rassemble les requêtes récurrentes : projets d'une personne, co-auteurs, chaîne projet → versions → organisation, orphelins, doublons probables par titre normalisé, provenance d'un nœud, archivage.

4. GDS et APOC

list-gds-procedures donne ce qui est réellement installé. Les algorithmes GDS (PageRank, Louvain, similarité de nœuds) demandent une projection de graphe en mémoire : la créer avec un nom daté, la supprimer en fin de session (gds.graph.drop) — c'est une projection, pas une donnée. Sur un poste partagé avec Ollama, une projection de tout le graphe peut saturer la RAM : projeter le sous-graphe utile (labels et relations listés), jamais * par réflexe.

5. Quand le graphe ne suffit pas

• Question « sémantique » (« des projets qui ressemblent à … ») → graphrag-hybrid.
• Nom d'entité à résoudre contre une référence externe → skill de réconciliation d'entités.
• Le schéma montre des labels inattendus → les signaler, ne pas les « corriger » en silence.

Format de réponse

1. Ce que dit le schéma (labels/relations utilisés).
2. La requête exécutée et son résultat (tableau court).
3. Si écriture proposée : requête, impact chiffré, requête inverse, « GO ? ».

Changelog

• 2026-09-07 — 0.1.0 : version initiale. MCP officiel neo4j/mcp (4 tools, NEO4J_READ_ONLY), séquence schéma → lecture → GO → écriture, patterns personne → projets → versions, garde-fous GDS.