> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Présentation des outils MCP de Linkly AI
> Présentation des outils que Linkly AI met à disposition des assistants IA
## 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`).
Rechercher des documents et trouver les résultats pertinents
Consulter le sommaire du document pour comprendre sa structure
Trouver des motifs de texte spécifiques par correspondance regex
Lire le contenu du document pour obtenir des informations détaillées
Lister les bibliothèques de connaissances et leurs nombres de documents
Vue d'ensemble des thèmes et de la structure de la collection de documents
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://` ; cloud : `cloud:///` (`--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](#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
```bash theme={null}
# 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
```bash theme={null}
# 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
```bash theme={null}
# 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 :
```bash theme={null}
# Première page : lignes 1-200
linkly read --offset 1 --limit 200
# Deuxième page : lignes 201-400
linkly read --offset 201 --limit 200
# Troisième page : lignes 401-600
linkly read --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
```bash theme={null}
# 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
```bash theme={null}
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://` ; cloud : `cloud:///` (`--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.
```bash theme={null}
# 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://` ; cloud : `cloud:///` (`--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
```bash theme={null}
# 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 :
```json theme={null}
{ ..., "_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 :
```bash theme={null}
# É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 :
```json theme={null}
// É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
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 |
Si le document n'a pas de sommaire disponible (`has_outline: false`), vous pouvez :
1. Utiliser directement l'outil `read` pour parcourir le contenu du document page par page
2. 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
Flux recommandé :
1. Consulter d'abord la structure du document via `outline` (si un sommaire est disponible)
2. 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
3. Lire au maximum 500 lignes à la fois, en ajustant `offset` pour paginer
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.
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