Outils d'intention
La passerelle MCP ne remet pas à l'agent un CRUD générique, mais 21 outils orientés intention — chacun exprime une intention (« créer une note », « rappeler un contexte », « renommer un projet ») plutôt qu'une opération sur une table. Cet ensemble trace des limites par construction : l'agent ne choisit ni l'espace ni la classe de la note — c'est l'outil lui-même qui l'impose, et la portée du jeton détermine quels outils sont visibles tout court.
Les noms et descriptions que l'agent voit dans tools/list sont statiques — le contenu des notes n'y est jamais mélangé (protection contre le tool-poisoning).
Portée du jeton — le plafond de visibilité
Un jeton read ne voit que les outils de lecture ; les outils d'écriture n'apparaissent pas du tout dans tools/list. De plus, chaque appel vérifie l'accès à l'espace concerné. Les tableaux ci-dessous représentent donc le maximum ; l'ensemble réel dépend de votre jeton.
Bootstrap
Outils de démarrage de session : qui suis-je, ce qui m'est accessible, ce qui a changé.
| Outil | Fonction |
|---|---|
start_session | À appeler en premier dans une nouvelle session. En une seule requête : le profil de l'utilisateur (toujours chargé), les projets accessibles et — si vous précisez project — un index compact du projet (nombre de notes + dossiers de premier niveau), le delta des changements depuis votre dernière visite, ainsi que knownValues (un dictionnaire des catégories/tags utilisés). Idempotent ; son appel n'est pas obligatoire — vous obtenez simplement moins de contexte. |
whoami | Qui je suis (id du principal), mon plafond (read/write), mes appartenances aux projets et les capabilities du moteur (vector/trash/revisions) — pour ne pas tâtonner à l'aveugle. |
get_my_projects | Une liste à plat des projets accessibles avec leurs handles prêts à l'emploi — pour l'argument project. Un handle a généralement la forme space/slug, mais pour le projet racine d'un espace il se réduit à un seul segment : reprenez-le tel quel depuis la réponse plutôt que de le déduire d'une règle. Le domaine personnel ne figure pas dans la liste (il est implicite dans le jeton). |
start_session → (besoin d'un projet ?) get_my_projects → parcourir la structure avec list_notes/recent_activity → search/recall avant d'écrire → create_note/remember_*/edit_note/link.
Cet ordre est une recommandation, pas un mécanisme : c'est le modèle qui décide quel outil appeler. Pour qu'il soit respecté sans rappel de votre part, inscrivez-le dans les instructions permanentes de l'agent — Règles de l'agent.
Discover — navigation
| Outil | Fonction |
|---|---|
list_notes | Le ls de la base de connaissances : les notes directes et sous-dossiers d'un dossier (déterministe, paginé). project sélectionne l'espace, path désigne le dossier (à reprendre tel quel depuis la réponse), tag filtre. Liste les notes visibles, pas la mémoire de l'agent. |
recent_activity | Les notes modifiées le plus récemment (« ce qui a été touché dernièrement, à relire »). Chaque entrée : qui (humain/agent), comment, où, quand. Ce n'est pas le delta de start_session. |
Read — lecture et rappel
| Outil | Fonction |
|---|---|
search | Recherche hybride (sémantique + lexicale via RRF) ; quand la recherche vectorielle est indisponible, elle se rabat sur la recherche plein texte (FTS) — sans erreur. Elle couvre aussi la mémoire propre de l'agent — « chercher avant d'écrire » y élimine également les doublons. Renvoie des extraits classés avec un score et un path, pas des notes entières. |
get_note | La note complète par ref (note-id ou wiki-ref) : contenu, frontmatter, path, class, versionToken (pour des écritures sûres) et provenance. En mode detailed — aussi outline (les titres) et links (les arêtes du graphe). |
recall | Assembler un bloc de contexte autour d'un sujet, dans un budget de tokens : les notes pertinentes plus leurs voisines dans le graphe. Plus riche que search, il puise dans la connaissance et dans la mémoire privée. budgetTokens en plafonne la taille. |
Plus de détails sur la différence entre search et recall — Mémoire de l'agent.
Write — écriture et intention
| Outil | Fonction |
|---|---|
create_note | Créer une nouvelle note partagée (KB) dans un projet, classe user-doc. body (Markdown) définit le titre de la note à partir d'un # H1 en tête ; path? est le dossier de destination ; type?/tags? sont des paramètres de surcharge optionnels ; links? ajoute d'emblée des arêtes typées. L'agent ne choisit ni la classe ni l'espace. |
remember_about_user | Enregistrer un fait durable sur l'utilisateur (préférences, contexte) dans sa mémoire privée. Ajoute une observation sous une category. |
remember_about_project | Enregistrer un fait sur un projet dans la mémoire privée de l'agent (classe agent-memory, symétrique de remember_about_user). Ce n'est pas de la connaissance partagée — pour cela, utilisez create_note. |
edit_note | Modifier une note de façon incrémentale par mots, pas par positions : append/prepend, replace (le corps entier), replaceSection (par titre de section), findReplace (un extrait unique ; content vide = supprimer). Requiert un versionToken (CAS). |
delete_note | Déplacer une note vers la corbeille — la seule action destructrice de l'agent, réversible par conception. Seul un humain restaure ou vide la corbeille. |
link | Un lien typé from→cible. La cible est to (note-id) ou toTitle (une référence anticipée par le titre d'une note pas encore créée). Les deux notes dans le même espace. |
edit_note requiert un versionToken issu d'un get_note récent. Une modification concurrente renvoie une erreur versionConflict — l'outil n'écrase pas silencieusement les changements d'autrui ; l'agent relit et réessaie.
Reorganize
La grammaire des outils de réorganisation est verb_entity. Une note se désigne par son id, un dossier par path, un projet par son handle.
| Outil | Fonction |
|---|---|
move_note | Déplacer une note vers un autre dossier, en conservant son nom. L'id et l'URL restent stables, les liens entrants ne se cassent pas. |
rename_note | Changer le titre d'une note. Link-safe : l'ancien titre passe dans l'historique des alias, les [[links]] entrants continuent de se résoudre. |
move_folder | Déplacer un dossier entier avec son contenu sous un autre parent. Les id de toutes les notes qu'il contient restent stables. |
rename_folder | Renommer un dossier sur place. Si le dossier est un projet, son handle ne change pas (pour le handle — rename_project). |
rename_project | Changer le handle et/ou le nom lisible d'un projet. Link-safe : l'ancien handle passe dans un alias. |
Scale — migration à grande échelle
| Outil | Fonction |
|---|---|
create_notes | Créer plusieurs notes KB dans un même projet par appel. Best-effort, non transactionnel : results[] marque chacune ok/error — ne réessayer que celles en échec. |
link_many | Créer plusieurs liens typés par appel. Best-effort, idempotent. |
Ensuite
- Mémoire de l'agent — remember et recall en détail.
- Jeux de contexte et épingles — ce qui entre dans
start_session. - Sécurité et visibilité — comment l'ensemble brise la « lethal trifecta ».