Présentation des outils MCP de Linkly AI

Vue d’ensemble des outils

Linkly AI expose neuf outils aux assistants IA via MCP (Model Context Protocol). Le cœur en est un flux de travail progressif d’accès aux documents :

search → grep or outline → read

Autour de lui gravitent trois outils de découverte — list_libraries (lister les bibliothèques de connaissances), explore (vue d’ensemble des collections de documents), find_paths (localiser des chemins de dossier par mot-clé pour alimenter le path_glob de search) — auxquels s’ajoutent list (énumérer un conteneur : les fichiers d’un dossier, une bibliothèque ou vos notes) et l’unique outil de notes : note_save (créer / modifier une note).

search

Rechercher des documents et trouver les résultats pertinents

outline

Consulter le sommaire du document pour comprendre sa structure

grep

Trouver des motifs de texte spécifiques par correspondance regex

read

Lire le contenu du document pour obtenir des informations détaillées

list_libraries

Lister les bibliothèques de connaissances et leurs nombres de documents

explore

Vue d’ensemble des thèmes et de la structure de la collection de documents

find_paths

Localiser des chemins de dossier par mot-clé pour alimenter le path_glob de search

list

Lister les entrées d’un conteneur — un dossier, une bibliothèque ou vos notes

note_save

Créer ou modifier une note, le seul outil d’écriture

À l’exception de note_save, tous ces outils sont en lecture seule : ils se contentent de lire vos documents, sans jamais rien y modifier. note_save n’écrit que dans le dossier des notes et il n’existe aucun outil de suppression : supprimer une note reste une action que vous seul pouvez faire depuis l’application.

Recherche (search)

Recherche dans vos documents locaux indexés et retourne la liste des résultats les plus pertinents.

Paramètres

Paramètre	Type	Obligatoire	Par défaut	Description
`query`	string	Oui	—	Mots-clés ou expression de recherche
`limit`	number	Non	20	Nombre maximum de résultats (1-50)
`doc_types`	string[]	Non	Tous	Filtrer par type de document. Valeurs possibles : `pdf`, `docx`, `pptx`, `epub`, `md`, `txt`, `html`, `image`, `audio`, `video`
`library`	string	Non	—	Restreindre à une bibliothèque spécifique. Local : un nom simple ou `local://<id>` ; cloud : `cloud://<owner>/<slug>` (`--remote` uniquement). Utilisez `list_libraries` pour voir les bibliothèques disponibles
`path_glob`	string	Non	—	Filtrer par chemin de fichier. Le motif est recherché comme sous-chaîne du chemin — il peut apparaître n’importe où, sans `` en début ou fin. `` correspond à tout caractère (y compris `/`), `?` à un seul caractère. Toujours sensible à la casse. Un chemin de répertoire complet (`/Users/me/notes/`) limite la recherche à ce répertoire. Lorsque le chemin réel est inconnu, appeler `find_paths` d’abord
`scope`	string	Non	`folder`	Périmètre de recherche. `folder` (par défaut) interroge tout le contenu indexé selon la sémantique de `library` / `path_glob` ci-dessus ; `notes` ne cherche que dans les notes locales et ignore `path_glob` ainsi qu’une `library` locale ; l’associer à une bibliothèque `cloud://` est rejeté, les notes n’ayant aucun équivalent côté cloud. Toute autre valeur est rejetée
`tags`	string[]	Non	—	Filtrer les notes par tag, avec une sémantique ET (tous les tags listés doivent être présents). Les tags sont normalisés (`#` initial retiré, ASCII mis en minuscules). Pour un OU, appelez une fois par tag puis fusionnez. S’utilise généralement avec `scope="notes"`
`modified_after`	string	Non	—	Borne inférieure incluse sur la date de modification. ISO 8601 UTC : date simple `2024-01-01` (interprétée comme `00:00:00Z`) ou RFC 3339 complet `2024-01-01T00:00:00Z`
`modified_before`	string	Non	—	Borne supérieure incluse sur la date de modification. Même format que `modified_after`
`time_sort`	string	Non	`default`	Réordonnement temporel : `default` (préserve l’ordre de pertinence) / `newest` (le plus récent en premier) / `oldest` (le plus ancien en premier). Le réordonnancement n’est appliqué qu’après la sélection et la déduplication
`output_format`	string	Non	`markdown`	Définir sur `json` pour une sortie JSON structurée

Si le modèle vectoriel est encore en cours de téléchargement, la recherche bascule automatiquement en mode mots-clés uniquement, sans impact sur l’utilisation.

À propos du filtrage et du tri par date :

Lorsque l’utilisateur fournit une fenêtre temporelle explicite (« le mois dernier », « en 2024 », « ces trois derniers mois »), utilisez modified_after / modified_before.
Lorsque l’utilisateur dit seulement « récent », « le plus récent », « le plus ancien » sans plage fixe, utilisez time_sort=newest ou oldest.
Les deux peuvent se combiner : « le plus ancien en 2024 » donne modified_after=2024-01-01 + modified_before=2024-12-31 + time_sort=oldest.
Pour une date relative (« le mois dernier »), lisez d’abord l’heure UTC actuelle depuis le champ [meta] now=... à la fin de toute réponse d’outil, puis calculez la date — voir Métadonnées de réponse ci-dessous.

Champs retournés

Chaque résultat de recherche contient les informations suivantes :

Champ	Description
`doc_id`	Identifiant unique du document pour les appels outline/read ultérieurs
`title`	Titre du document
`path`	Chemin du fichier
`relevance`	Score de pertinence (0-1)
`word_count`	Nombre de mots du document
`total_lines`	Nombre total de lignes du document
`has_outline`	Indique si un sommaire est disponible
`modified_at`	Date de dernière modification
`keywords`	Liste des mots-clés extraits
`snippet`	Extrait du contenu correspondant

Exemples d’utilisation

# Via CLI
linkly search "project management best practices" --limit 10

# Filtrer par type de document
linkly search "quarterly report" --type pdf,docx --json

# Rechercher dans une bibliothèque spécifique
linkly search "deep learning" --library my-research --limit 10

# Filtrer par chemin de fichier
linkly search "report" --path-glob "*2024*"

# Limiter par fenêtre temporelle (rapports trimestriels Q3 2024)
linkly search "quarterly report" --modified-after 2024-07-01 --modified-before 2024-09-30

# Trier par date ("le plus récent", "le plus ancien" — sans plage fixe)
linkly search "weekly retro" --time-sort newest --limit 5

Sommaire (outline)

Obtient le sommaire structuré et les métadonnées d’un ou plusieurs documents, permettant de comprendre rapidement la structure du document et de localiser les sections ciblées.

Paramètres

Paramètre	Type	Obligatoire	Par défaut	Description
`doc_ids`	string[]	Oui	—	Liste d’ID de documents (issus des résultats de recherche)
`expand`	string[]	Non	Auto	ID des noeuds à développer (ex. `["2", "3.1"]`) ; omis pour afficher tous les niveaux
`output_format`	string	Non	`markdown`	Définir sur `json` pour une sortie JSON structurée

Quand utiliser le sommaire

Scénario	Recommandation
Document > 50 lignes avec sommaire	Consulter d’abord le sommaire, puis lire les sections ciblées
Document court (< 50 lignes)	Ignorer le sommaire, lire directement le texte complet avec `read`
Document avec `has_outline: false`	Utiliser `grep` pour trouver des motifs ou `read` page par page

La fonctionnalité de sommaire est optimale pour les PDF avec signets, les documents Markdown, DOCX, PowerPoint (PPTX) et EPUB. Elle est particulièrement efficace pour la lecture de documents volumineux et de livres. Le support du sommaire pour le texte brut et les PDF sans signets sera ajouté dans les itérations futures.

Exemples d’utilisation

# Consulter le sommaire d'un document
linkly outline abc123

# Consulter plusieurs documents à la fois
linkly outline id1 id2 id3

# Sortie au format JSON
linkly outline abc123 --json

Grep

Localise des lignes spécifiques au sein d’un seul document à l’aide d’un motif regex. Idéal pour les documents avec has_outline=false où le sommaire n’est pas disponible. Utilisez-le après search pour localiser les positions exactes de noms, dates, termes, identifiants ou tout motif, puis utilisez read avec offset pour voir le contexte complet. Fonctionne avec tous les types de documents (PDF, Markdown, DOCX, PPTX, EPUB, TXT, HTML). Pour rechercher dans plusieurs documents, appelez grep une fois par document.

Paramètres

Paramètre	Type	Obligatoire	Par défaut	Description
`pattern`	string	Oui	—	Motif d’expression régulière à rechercher
`doc_id`	string	Oui	—	ID du document dans lequel rechercher (issu des résultats de recherche)
`context`	number	Non	3	Lignes de contexte avant et après chaque correspondance
`before`	number	Non	—	Lignes de contexte avant chaque correspondance (remplace `context`)
`after`	number	Non	—	Lignes de contexte après chaque correspondance (remplace `context`)
`case_insensitive`	boolean	Non	false	Correspondance insensible à la casse
`output_mode`	string	Non	`content`	`content` (lignes correspondantes avec contexte) ou `count` (nombre uniquement, pour prévisualiser)
`limit`	number	Non	20	Nombre maximum de lignes correspondantes à retourner (max 100)
`offset`	number	Non	0	Nombre de correspondances à sauter pour la pagination
`fuzzy_whitespace`	boolean	Non	Auto	Correspondance tolérante au bruit d’espacement, pour venir à bout des textes extraits de PDF truffés d’espaces superflus et de coupures de ligne. Omis, il est déterminé automatiquement (activé pour les PDF, désactivé pour les autres formats) ; `true` / `false` permettent de forcer
`output_format`	string	Non	`markdown`	Définir sur `json` pour une sortie JSON structurée

Quand utiliser Grep vs Sommaire

Scénario	Recommandation
Besoin de trouver un terme, nom ou date spécifique	Utiliser `grep` avec le motif
Besoin de comprendre la structure globale du document	Utiliser `outline`
Le document n’a pas de sommaire (`has_outline: false`)	Utiliser `grep` pour localiser le contenu
Recherche de motifs (emails, identifiants, nombres, etc.)	Utiliser `grep` avec regex

Exemples d’utilisation

# Trouver des termes spécifiques dans un document
linkly grep "quarterly revenue" 456

# Recherche insensible à la casse avec contexte
linkly grep "error|warning" 1044 -C 3 -i

# Prévisualiser le nombre de correspondances avant lecture
linkly grep "TODO" 591 --mode count

Lecture (read)

Lit le contenu d’un document avec positionnement par numéro de ligne et pagination, adapté à la lecture de sections spécifiques de documents longs. L’outil Read a un comportement cohérent avec celui du SDK Claude AI, garantissant des résultats optimaux avec divers modèles Agentic AI.

Paramètres

Paramètre	Type	Obligatoire	Par défaut	Description
`doc_id`	string	Oui	—	ID du document (issu des résultats de recherche)
`offset`	number	Non	1	Numéro de ligne de départ (à partir de 1)
`limit`	number	Non	200	Nombre de lignes à lire (maximum 500)
`image_text`	string	Non	`abstract`	Quantité d’informations à joindre pour les images référencées dans le texte, voir Lire des documents illustrés ci-dessous
`output_format`	string	Non	`markdown`	Définir sur `json` pour une sortie JSON structurée

Lire des documents illustrés

Dans bien des documents — les notes Markdown et la documentation technique tout particulièrement — l’information décisive se trouve dans les illustrations. read résout les références d’images apparaissant dans la plage de lignes que vous êtes en train de lire vers les documents image correspondants déjà indexés, et les joint à la fin du résultat. image_text détermine ce qui est joint :

Valeur	Contenu joint
`none`	La seule correspondance : numéro de ligne, fichier, `doc_id`
`abstract` (par défaut)	S’y ajoutent un extrait d’une ligne et le nombre de caractères de chaque image
`full`	S’y ajoute le texte OCR complet, en ligne

full est soumis à un budget : 2 000 caractères au maximum par image, 20 000 caractères au total pour l’appel. Les images dépassant ce budget retombent automatiquement sur abstract, accompagnées de la marche à suivre pour les lire individuellement.

Repérez d’abord l’image utile avec le mode abstract par défaut, puis appelez read sur son seul doc_id : c’est nettement plus économe que de démarrer en full.

Format du contenu

L’outil Read retourne le contenu avec des numéros de ligne pour faciliter le référencement et le positionnement :

  1	# Project Requirements Document
  2
  3	## 1. Project Background
  4
  5	This project aims to build an efficient knowledge management system...
  6	Target users are enterprise R&D teams and individual knowledge workers.

Stratégie de pagination

Pour les documents longs, il est recommandé de lire par blocs :

# Première page : lignes 1-200
linkly read <DOC_ID> --offset 1 --limit 200

# Deuxième page : lignes 201-400
linkly read <DOC_ID> --offset 201 --limit 200

# Troisième page : lignes 401-600
linkly read <DOC_ID> --offset 401 --limit 200

L’utilisation combinée avec le sommaire est encore plus efficace : localisez d’abord la plage de lignes de la section ciblée via le sommaire, puis utilisez read pour lire précisément cet intervalle.

Exemples d’utilisation

# Lire le début du document
linkly read abc123

# Lire une plage spécifique
linkly read abc123 --offset 120 --limit 80

# Format JSON (adapté au traitement programmatique)
linkly read abc123 --json

Lister les bibliothèques (list_libraries)

Liste toutes les bibliothèques de connaissances configurées par l’utilisateur, avec leurs descriptions et leurs nombres de documents.

Paramètres

Aucun paramètre requis.

Cas d’utilisation

Lorsque l’utilisateur demande « quelles bibliothèques ai-je ? »
Avant d’utiliser le paramètre library dans search, pour vérifier le nom d’une bibliothèque

linkly list-libraries

Explorer (explore)

Obtient une vue d’ensemble de tous les documents indexés ou d’une bibliothèque spécifique. Retourne la distribution des types de documents, la structure des répertoires (avec le nombre de fichiers et la médiane du nombre de mots) et les mots-clés principaux (avec attribution de la source).

Paramètres

Paramètre	Type	Obligatoire	Par défaut	Description
`library`	string	Non	—	Restreindre à une bibliothèque spécifique. Local : un nom simple ou `local://<id>` ; cloud : `cloud://<owner>/<slug>` (`--remote` uniquement). Omettez pour explorer tous les documents locaux

Cas d’utilisation

L’utilisateur souhaite savoir ce que contient sa base de connaissances ou sa collection de documents
L’utilisateur n’a pas de sujet de recherche spécifique et souhaite découvrir les thèmes et directions disponibles
L’assistant IA a besoin de comprendre l’échelle et la distribution thématique pour formuler des stratégies de recherche efficaces

Après l’exploration, utilisez les mots-clés et les noms de répertoires de la sortie comme pistes pour les requêtes search ultérieures.

# Explorer tous les documents
linkly explore

# Explorer une bibliothèque spécifique
linkly explore --library my-research

Localisation de chemins (find_paths)

Effectue une correspondance approximative des mots-clés sur le champ chemin de fichier des documents indexés, agrège les correspondances au niveau du dossier et retourne les meilleurs candidats. Cet outil est positionné comme un complément de search : lorsque l’utilisateur nomme un conteneur (« dans mes notes Notion », « dans mon dossier de papiers Dropbox ») sans en connaître le chemin sur le disque, appelez d’abord find_paths pour découvrir le chemin réel, puis transmettez-le comme path_glob à search. Le nom réel du dossier sur le disque diffère souvent du nom utilisé par l’utilisateur (par exemple, un export peut résider sous Notion-Export-c58e430f... plutôt que simplement Notion), donc deviner directement un path_glob est fragile.

Paramètres

Paramètre	Type	Obligatoire	Par défaut	Description
`patterns`	string[]	Oui	—	Tableau de mots-clés ; chacun est encapsulé en interne sous forme de SQL `LIKE %keyword%` contre le chemin. Plusieurs mots-clés sont combinés par OR, donc passez plusieurs variantes en un seul appel (paires de traduction, casse, identifiants réels d’application/SDK), ex. `["Notion", "notion", "notion-export"]`. Insensible à la casse pour ASCII ; CJK correspond littéralement.
`library`	string	Non	—	Restreindre à une bibliothèque spécifique. Local : un nom simple ou `local://<id>` ; cloud : `cloud://<owner>/<slug>` (`--remote` uniquement). Utilisez `list_libraries` pour voir les bibliothèques disponibles
`limit`	number	Non	10	Nombre maximum de dossiers candidats (max 50)
`output_format`	string	Non	`markdown`	Définir sur `json` pour une sortie JSON structurée

Champs retournés (mode JSON)

Champ	Description
`total_files`	Nombre total de fichiers agrégés dans les candidats retournés (avant troncature par `limit`)
`truncated`	Indique si `limit` a coupé la liste de répertoires (`true` signifie qu’il existe d’autres candidats)
`directories`	Dossiers candidats, triés par `file_count` décroissant. Chaque entrée contient `path` (le chemin absolu complet), `path_glob` (le `path` transformé en motif `path_glob` prêt à l’emploi : les métacaractères glob `* ? [` présents dans le nom du dossier sont échappés afin qu’il corresponde littéralement à ce dossier — égal à `path` lorsque le nom ne contient aucun métacaractère ; copiez-le tel quel dans un `search` ultérieur pour cibler tout le dossier) et `file_count` (nombre de fichiers correspondants)

Comportement d’agrégation

Les fichiers dont les motifs ne correspondent qu’au segment du nom de fichier (sans correspondance dans un segment de répertoire) sont silencieusement écartés — c’est un outil de « recherche de dossiers », pas de « recherche de fichiers ». Si une requête ne renvoie aucun dossier candidat alors que des fichiers correspondants existent, repassez à un appel direct à search.
Chaque correspondance est regroupée par la position la moins profonde d’un motif dans le chemin, tronquée au prochain /. Ainsi local:///Users/me/Documents/Notion-Export-abc/workspace/page.md correspondant à Notion est agrégé sous .../Documents/Notion-Export-abc, peu importe la profondeur du fichier.

Quand l’utiliser

L’utilisateur nomme un conteneur avec un mot flou ou multilingue (« dans mes notes Notion », « dans mon dossier de papiers Dropbox », « dans ma sauvegarde de travail ») et vous ne connaissez pas le chemin réel
Avant search, pour déterminer la valeur de path_glob

Quand ne pas l’utiliser

Requêtes purement basées sur le contenu / le sujet (« trouve mes CV », « trouve les articles IA ») — appelez search directement ; sa recherche hybride couvre déjà titre, nom de fichier, contenu et chemin
Filtrage par type de fichier uniquement (« tous les PDF ») — appelez search avec path_glob="*.pdf" directement
Requêtes vagues sans intention de conteneur (« trouve les choses récentes ») — appelez search

Exemple d’utilisation

# Utilisateur : "trouve mes reçus d'achat dans mes notes Notion"
# Étape 1 : localiser le chemin réel
linkly find-paths --patterns Notion,notion --limit 5
# Supposons que cela retourne .../Documents/Notion-Export-abc/workspace (1240 fichiers)

# Étape 2 : rechercher dans ce conteneur
linkly search "shopping receipt" --path-glob "*Notion-Export*"

Lister (list)

Liste les entrées d’un conteneur, sans aucune correspondance plein texte — pour retrouver du contenu par mot-clé ou par le sens, utilisez search. Trois conteneurs sont pris en charge : folder (les fichiers indexés sous un répertoire du disque), library (les fichiers d’une bibliothèque) et notes (les fiches de notes locales). Répartition des rôles : explore = vue d’ensemble → find_paths = trouver un répertoire → list = lister les fichiers d’un conteneur connu → outline / read = lire le contenu. Le listage est un balayage récursif à plat de tout le sous-arbre — aucune arborescence n’est renvoyée ; pour descendre, suivez les chemins absolus des entrées ou passez par find_paths.

Paramètres

Paramètre	Type	Obligatoire	Par défaut	Description
`scope`	string	Oui	—	Le conteneur à lister. `folder` : les fichiers indexés sous un répertoire du disque (omettez `path` pour balayer toutes les racines surveillées) ; `library` : les fichiers d’une bibliothèque (exige `library`) ; `notes` : les fiches de notes locales. Toute autre valeur est rejetée. Attention : `search.scope` possède aussi une valeur écrite `folder`, qui signifie « tout le contenu indexé » — c’est un autre concept, les valeurs ne sont pas interchangeables
`library`	string	Avec `scope="library"`	—	La bibliothèque à lister. Locale : un nom ou `local://<id>` (voir `list_libraries`) ; cloud : `cloud://<owner>/<slug>` (uniquement avec `--remote`)
`path`	string	Non	—	Le répertoire à lister — une adresse, pas un motif : pas de jokers ; si vous ne connaissez qu’un nom approximatif, appelez d’abord `find_paths` et recopiez son champ `path` (pas `path_glob`, dont l’échappement ferait échouer la correspondance en silence). Local (`folder` / `library` locale) : chemin absolu — un chemin inexistant sur le disque, ou hors de vos dossiers surveillés, est rejeté avec une erreur. Si la bibliothèque possède un filtre par étiquette pour les notes ou les extraits, les chemins situés dans ce répertoire `Notes/` ou `Clips/` sont également acceptés — ils ne listent que les documents correspondant au filtre. Bibliothèque cloud : préfixe de répertoire relatif (la forme que renvoie le `find_paths` cloud) ; un chemin absolu y est rejeté
`doc_types`	string[]	Non	Tous	Filtrer par type de document (`folder` / `library` uniquement) : `pdf`, `docx`, `pptx`, `epub`, `md`, `txt`, `html`, `image`, `audio`, `video`
`tags`	string[]	Non	—	Filtrer par tag, avec une sémantique ET (`notes` uniquement — les autres scopes le rejettent). Le `#` initial est retiré, l’ASCII mis en minuscules, comme pour `search.tags`
`modified_after`	string	Non	—	Borne inférieure incluse sur la date de modification (`folder` / `library` uniquement). ISO 8601 UTC : date simple `2024-01-01` ou RFC 3339 complet
`modified_before`	string	Non	—	Borne supérieure incluse. Même format
`sort`	string	Non	`recent`	`recent` (les plus récents d’abord — ancré sur la date de création pour `notes`, de modification pour `folder` / `library` : une page tronquée montre donc la tranche la plus récente) / `oldest` (même ancre, les plus anciens d’abord) / `name` (nom de fichier de A à Z). Chaque tri possède une règle de départage déterministe sur le chemin, la pagination est donc stable
`snippet`	boolean	Non	Selon scope	`notes` : `true` (environ 200 caractères de début de texte) ; `folder` / `library` : `false` (activé, l’extrait provient du résumé indexé — aucune lecture disque). Tant qu’il est activé, `limit` est plafonné à 50
`limit`	number	Non	50	Nombre maximum d’entrées, plafonné à 200 ; le plafond descend à 50 tant que `snippet` est activé
`offset`	number	Non	0	Nombre d’entrées à sauter dans l’ordre de tri (pagination) ; fiez-vous à `has_more` pour décider de demander la page suivante
`output_format`	string	Non	Selon scope	`notes` : `json` (chaque entrée est un jeton CAS pour `note_save`, qui ne tient pas dans un format ligne compact) ; `folder` / `library` : `markdown`. Les deux valeurs peuvent être demandées explicitement

Champs retournés

Les entrées folder / library comportent : doc_id, title, le path absolu, doc_type, word_count, total_lines, has_outline, modified_at (millisecondes Unix ; le mtime du système de fichiers), keywords, snippet (null sauf si les extraits sont activés) et skip_reason — un skip_reason non nul signifie que le contenu est illisible : ne lui appliquez ni read ni grep. Servez-vous de total_lines + has_outline pour arbitrer entre outline et read. Pour les scopes locaux, total compte l’ensemble filtré complet ; une bibliothèque cloud peut renvoyer total: null quand le décompte complet est inconnu — dans tous les cas, paginez avec offset + has_more. Les entrées notes comportent : doc_id (transmissible à read / grep / outline), note_id et la version du moment (ces deux-là servent de jeton de verrou optimiste lors d’une modification via note_save), title, le chemin absolu, created_at / modified_at (millisecondes Unix), tags, les informations de source, ainsi que le snippet joint par défaut. La réponse comporte en outre un champ available_tags : les 50 tags les plus fréquents parmi l’ensemble des notes, directement réutilisables pour filtrer l’appel suivant via tags.

Pointeur README : uniquement lorsque vous listez avec un path explicite (scope folder ou library locale) et qu’un fichier de type README se trouve directement dans ce répertoire (pas dans un sous-répertoire), la réponse porte un pointeur readme de premier niveau. Les bibliothèques cloud n’en renvoient jamais. S’il est présent et que vous devez comprendre à quoi sert le dossier, lisez d’abord ce document.

Le système de fichiers d’abord (notes) : une note tout juste écrite apparaît immédiatement dans la liste, mais son doc_id vaut alors null et indexed vaut false (le nombre de mots et de lignes restent vides également) ; tout cela se complète une fois l’indexation passée. « Une note tout juste écrite figure dans la liste mais reste introuvable à la recherche » est donc un comportement normal, elle n’est pas perdue.title peut lui aussi valoir null : les notes dont le nom de fichier est généré automatiquement n’ont pas de titre exploitable ; il faut alors s’appuyer sur l’extrait, les tags et la date.

Bibliothèques cloud

folder ne comprend que les chemins de disque locaux. Pour lister une bibliothèque cloud, utilisez scope="library" avec library="cloud://<owner>/<slug>" (disponible avec --remote) et passez dans path un préfixe de répertoire relatif — exactement la forme que renvoie le find_paths cloud. Le préfixe s’applique à l’union de toutes les sources de la bibliothèque ; un préfixe inexistant est indiscernable d’un répertoire vide — sur la première page (offset=0), les deux renvoient total: 0, avec une indication si un path a été fourni. Le listage cloud diffère du local sur quelques points : sort="name" n’est pas pris en charge, skip_reason vaut toujours null, les extraits sont tronqués à environ 120 caractères et, au-delà de la première page, total peut valoir null — paginez avec has_more.

Exemples d’utilisation

# Les fichiers les plus récents de toutes les racines surveillées
linkly list --scope folder --limit 10

# Les PDF d'un répertoire, modifiés cette année
linkly list --scope folder --path /Users/me/Papers --type pdf --modified-after 2026-01-01

# Les fichiers d'une bibliothèque
linkly list --scope library --library my-research

# Les notes filtrées par tag (sortie par défaut : JSON avec jetons CAS)
linkly list --scope notes --tags project

Enregistrer une note (note_save)

Crée ou modifie une fiche de note Markdown locale. C’est le seul outil qui écrit, et il n’écrit que dans le dossier des notes ; les métadonnées YAML sont intégralement générées côté serveur, l’appelant n’a pas à s’en préoccuper.

Paramètres

Paramètre	Type	Obligatoire	Description
`mode`	string	Oui	`create` ou `edit`
`content`	string	Oui	Le corps en Markdown, sans en-tête YAML. Lors d’une modification, il s’agit du texte intégral révisé
`note_id`	string	Oui en mode `edit`	L’UUID de la note, obtenu via `list`
`base_version`	string	Oui en mode `edit`	La `version` lue, pour le contrôle par verrou optimiste
`tags`	string[]	Non	Tags à ajouter (le serveur complète le corps avec les `#tag` manquants). Ne permet pas de supprimer : pour retirer un tag, effacez son `#tag` du `content`. Nécessite Desktop 0.11.0+ ; sur les versions antérieures, ce paramètre est obligatoire à la modification et remplace l’ensemble
`app_name`	string	Non	Nom d’affichage de l’application qui héberge la conversation (p. ex. `ChatGPT`, `Cursor`), affiché comme badge de source de la note. C’est le nom de l’application, pas celui du modèle — si vous ne connaissez que le nom du modèle, omettez le paramètre. Sur une connexion OAuth via la passerelle cloud, le serveur le renseigne automatiquement. 64 caractères maximum

Deux règles à connaître impérativement

Le format du corps obéit à une liste blanche, on n'y écrit pas n'importe quoi

Cette voie n’accepte que la part de Markdown que la barre d’outils de l’interface sait produire : paragraphes et sauts de ligne, gras, barré, listes ordonnées ou à puces, texte brut.Les titres, l’italique, les citations, le code, les liens, les tableaux, les listes de tâches, les images et le HTML brut sont rejetés, avec un NOTE_INVALID_INPUT en retour. Ce que vous écrivez vous-même dans l’interface n’est pas soumis à cette restriction.Les #tag présents dans le corps (hors code) sont les tags de la note : le corps est l’unique source de vérité, exactement comme lorsque vous écrivez dans l’éditeur de l’application. Pour retirer un tag, effacez son #tag ; le paramètre tags ne sait qu’ajouter. Les notes écrites par les versions antérieures, dont les tags ne figurent que dans le YAML, se réparent d’elles-mêmes : à la première modification par l’IA, les #tag manquants sont ajoutés au corps.

La modification impose une boucle de verrou optimiste (CAS)

La bonne séquence est la suivante :

list (scope="notes") pour obtenir note_id et version
read(doc_id) pour lire le corps intégral actuel
note_save avec mode="edit", note_id, base_version (la version qui vient d’être lue) et le corps complet révisé — gardez les #tag que vous voulez conserver, effacez ceux dont vous voulez vous débarrasser

Si base_version est périmé (la note a été modifiée entre-temps), un NOTE_VERSION_CONFLICT est retourné, accompagné du numéro de version réel — il faut alors relire, fusionner et réessayer, surtout pas écraser aveuglément.Chaque réponse en succès retourne le content effectif de la note (le serveur y a peut-être ajouté des #tag) ainsi que sa nouvelle version — toute modification ultérieure doit partir du content retourné, jamais de celui que vous avez envoyé. Une note pas encore indexée a un doc_id à null : c’est précisément ainsi que l’on modifie une note que l’on vient de créer. Ne réécrivez jamais une note entière sur la seule foi de son extrait.

Il n’existe aucun outil de suppression. Une note ne se supprime que depuis l’interface de l’application, par l’utilisateur.

Métadonnées de réponse

Chaque réponse réussie d’outil contient l’heure UTC actuelle, ce qui permet aux appelants de calculer des dates relatives (« le mois dernier », « cette année », « ces 30 derniers jours ») sans dépendre de la date de coupure d’entraînement du modèle.

Sortie Markdown : un bloc de pied de page à la fin de la réponse, formaté comme :
--- [meta] now=2026-05-08T14:43:14Z

Sortie JSON : un objet _meta au niveau supérieur :

{ ..., "_meta": { "now": "2026-05-08T14:43:14Z" } }

Les réponses d’erreur (isError: true) n’incluent pas ces métadonnées — le corps d’erreur transmet déjà la cause, et ajouter un horodatage diluerait le signal. Lorsque l’utilisateur utilise une date relative, lisez now depuis la réponse d’outil la plus récente, calculez la date ISO 8601 correspondante, puis transmettez-la à modified_after / modified_before de search.

Exemples de flux de travail

Flux de travail complet : via CLI

L’exemple suivant illustre comment effectuer une recherche documentaire complète via le CLI :

# Étape 1 : Rechercher les documents pertinents
linkly search "microservice architecture design" --limit 5

# Étape 2 : Consulter le sommaire du document cible (en supposant doc_id = abc123)
linkly outline abc123

# Étape 3 : Lire la section intéressante (en supposant que la cible est aux lignes 80-150)
linkly read abc123 --offset 80 --limit 70

Flux de travail complet : via MCP

Lorsque l’assistant IA appelle les outils via le protocole MCP, le format des requêtes est le suivant :

// Étape 1 : Recherche
{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "microservice architecture design",
      "limit": 5
    }
  }
}

// Étape 2 : Consulter le sommaire
{
  "method": "tools/call",
  "params": {
    "name": "outline",
    "arguments": {
      "doc_ids": ["abc123"]
    }
  }
}

// Étape 3 : Lire le contenu
{
  "method": "tools/call",
  "params": {
    "name": "read",
    "arguments": {
      "doc_id": "abc123",
      "offset": 80,
      "limit": 70
    }
  }
}

Questions fréquentes

Quels formats de documents sont pris en charge ?

Linkly AI prend actuellement en charge les formats suivants :

Format	Extensions	Support du sommaire
Markdown	`.md`, `.mdx`	Yes
Word	`.docx`	Yes
PowerPoint	`.pptx`	Yes
EPUB	`.epub`	Yes
PDF	`.pdf`	Partial
Texte brut	`.txt`	No
HTML	`.html`	Partial
Image (OCR)	`.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp`	No
Audio (transcription)	`.mp3`, `.wav`, `.m4a`, `.flac`, `.aac`, `.ogg`	No
Vidéo (transcription)	`.mp4`, `.mov`, `.mkv`, `.webm`	No

La transcription vocale de l’audio et de la vidéo est désactivée par défaut : ces fichiers sont bien enregistrés dans l’index et se retrouvent par leur nom, mais pour chercher « ce qui s’y dit », il faut d’abord activer Transcription audio et Transcription vidéo dans Paramètres → Index. Voir Paramètres d’indexation.

Que faire si le sommaire n'est pas disponible ?

Si le document n’a pas de sommaire disponible (has_outline: false), vous pouvez :

Utiliser directement l’outil read pour parcourir le contenu du document page par page
Lire d’abord le début du document (200 lignes par défaut) pour avoir un aperçu du contenu, puis décider si vous souhaitez poursuivre la lecture

Comment traiter les documents longs ?

Flux recommandé :

Consulter d’abord la structure du document via outline (si un sommaire est disponible)
En fonction de la plage de lignes indiquée dans le sommaire, utiliser les paramètres offset et limit de read pour lire précisément les sections ciblées
Lire au maximum 500 lignes à la fois, en ajustant offset pour paginer

Quel est le port par défaut du service MCP ?

Le port par défaut est 60606. Si ce port est occupé, l’application essaie automatiquement d’autres ports. Vous pouvez vérifier le port réellement utilisé dans les paramètres de Linkly AI Desktop.

Que faire si les résultats de recherche sont imprécis ?

Vous pouvez essayer :

Utiliser des mots-clés plus précis
Utiliser des descriptions en langage naturel (en exploitant la correspondance sémantique vectorielle)
Combiner mots-clés et synonymes, par exemple "authentication auth login sign-in"
Utiliser --type pour filtrer des types de documents spécifiques et affiner le champ de recherche

​Vue d’ensemble des outils

search

outline

grep

read

list_libraries

explore

find_paths

list

note_save

​Recherche (search)

​Paramètres

​Champs retournés

​Exemples d’utilisation

​Sommaire (outline)

​Paramètres

​Quand utiliser le sommaire

​Exemples d’utilisation

​Grep

​Paramètres

​Quand utiliser Grep vs Sommaire

​Exemples d’utilisation

​Lecture (read)

​Paramètres

​Lire des documents illustrés

​Format du contenu

​Stratégie de pagination

​Exemples d’utilisation

​Lister les bibliothèques (list_libraries)

​Paramètres

​Cas d’utilisation

​Explorer (explore)

​Paramètres

​Cas d’utilisation

​Localisation de chemins (find_paths)

​Paramètres

​Champs retournés (mode JSON)

​Comportement d’agrégation

​Quand l’utiliser

​Quand ne pas l’utiliser

​Exemple d’utilisation

​Lister (list)

​Paramètres

​Champs retournés

​Bibliothèques cloud

​Exemples d’utilisation

​Enregistrer une note (note_save)

​Paramètres

​Deux règles à connaître impérativement

​Métadonnées de réponse

​Exemples de flux de travail

​Flux de travail complet : via CLI

​Flux de travail complet : via MCP

​Questions fréquentes

Vue d’ensemble des outils

Recherche (search)

Paramètres

Champs retournés

Exemples d’utilisation

Sommaire (outline)

Paramètres

Quand utiliser le sommaire

Exemples d’utilisation

Grep

Paramètres

Quand utiliser Grep vs Sommaire

Exemples d’utilisation

Lecture (read)

Paramètres

Lire des documents illustrés

Format du contenu

Stratégie de pagination

Exemples d’utilisation

Lister les bibliothèques (list_libraries)

Paramètres

Cas d’utilisation

Explorer (explore)

Paramètres

Cas d’utilisation

Localisation de chemins (find_paths)

Paramètres

Champs retournés (mode JSON)

Comportement d’agrégation

Quand l’utiliser

Quand ne pas l’utiliser

Exemple d’utilisation

Lister (list)

Paramètres

Champs retournés

Bibliothèques cloud

Exemples d’utilisation

Enregistrer une note (note_save)

Paramètres

Deux règles à connaître impérativement

Métadonnées de réponse

Exemples de flux de travail

Flux de travail complet : via CLI

Flux de travail complet : via MCP

Questions fréquentes