Présentation des outils MCP de Linkly AI

Vue d’ensemble des outils

Linkly AI expose sept outils aux assistants IA via MCP (Model Context Protocol), formant un flux de travail progressif d’accès aux documents :

search → grep or outline → read

Trois outils utilitaires supplémentaires sont disponibles : list_libraries (lister les bibliothèques de connaissances), explore (vue d’ensemble des collections de documents) et find_paths (localiser des chemins de dossier par mot-clé pour alimenter le path_glob de search).

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

Ces sept outils fonctionnent ensemble pour permettre aux assistants IA d’obtenir efficacement des informations contextuelles depuis vos documents locaux.

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, ex. `["pdf", "md", "docx", "pptx", "epub"]`
`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
`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
`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)
`output_format`	string	Non	`markdown`	Définir sur `json` pour une sortie JSON structurée

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*"

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
EPUB	`.epub`	Yes
PDF	`.pdf`	Partial
Texte brut	`.txt`	No
HTML	`.html`, `.htm`	Partial
Image (OCR)	`.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp`	No

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

​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

​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

​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

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

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