neo4j-graph-ops v0.1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/b1a8f31de33414ba.

---
name: neo4j-graph-ops
description: >-
  Interroge et fait évoluer le graphe de connaissances Neo4j d'une stack locale (APOC/GDS) via le
  serveur MCP officiel neo4j/mcp : lit le schéma, formule des requêtes Cypher en LECTURE d'abord,
  propose l'écriture et ne l'exécute que sur GO, applique les patterns personne → projets → versions
  (projets, articles, personnes, organisations). À utiliser quand l'utilisateur veut « interroger
  le graphe », « quel est le schéma Neo4j », « écris-moi une requête Cypher », « relie ces fiches dans
  le graphe », « combien de projets pour cette personne », « chemins entre deux entités », « lance un
  algorithme GDS », ou pour brancher le MCP Neo4j d'un plugin. Ne pas utiliser pour une recherche
  sémantique mêlant vecteurs et graphe → graphrag-hybrid, ni pour résoudre un nom d'entité contre
  Wikidata (skill de réconciliation dédié), ni pour dédupliquer des fiches Markdown d'un vault.
license: MIT
allowed-tools: Read, Grep, Glob, Bash(python3:*), mcp__neo4j__get-schema, mcp__neo4j__read-cypher, mcp__neo4j__write-cypher, mcp__neo4j__list-gds-procedures
metadata:
  version: "0.1.0"
  author: GeekFamilyCorp
  status: public
  plugin: tk-knowledge
compatibility: Neo4j 5.x local (bolt://127.0.0.1:7687) avec APOC et GDS ; serveur MCP neo4j-mcp-server (Python 3.10+) ou binaire neo4j-mcp ; variables NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD fournies par l'environnement.
---

# 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 :

```cypher
// 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.