MCP Research Friend Server

officiel

Outils de recherche, incluant un espace de stockage de documents basé sur Sqlite

GitHub

Documentation

Research Friend

Un assistant convivial pour les outils d'IA qui ont besoin de chercher des informations sur le web et de gérer une réserve locale de recherche.

Research Friend est un serveur MCP qui donne à vos outils d'IA la capacité de récupérer des pages web et de rechercher sur Internet. Il utilise un véritable navigateur web en arrière-plan, ce qui lui permet de fonctionner même avec les sites web modernes qui dépendent fortement de JavaScript. Il inclut également une « réserve » locale pour stocker des documents, extraire du texte et effectuer des recherches dans votre bibliothèque.

Pour profiter de toutes ses fonctionnalités, vous aurez besoin d'un client MCP qui prend en charge les invites (courant) et l'échantillonnage (moins courant). Nous développons Research Friend en parallèle de Chabeau, qui prend en charge les deux.

Que peut-il faire ?

  • Récupérer des pages web avec un vrai navigateur (y compris les sites utilisant beaucoup de JavaScript)
  • Récupérer des PDF et extraire leur contenu textuel
  • Rechercher sur le web via DuckDuckGo ou Google
  • Gérer une réserve locale de documents pour la recherche, le listage et l'extraction

Pour commencer

Vous aurez besoin de Node.js version 20 ou plus récente installée sur votre ordinateur.

1. Installer les dépendances

Ouvrez un terminal dans ce dossier et exécutez :

npm install

2. Installer la prise en charge du navigateur

Research Friend utilise Playwright pour contrôler un navigateur web. Après avoir installé les dépendances, vous devrez installer le navigateur :

npx playwright install chromium

Ceci télécharge une copie de Chromium que Playwright utilisera. Elle est distincte de tous les navigateurs que vous avez déjà installés.

3. Démarrer le serveur

node src/index.js

Le serveur communique via stdio (entrée/sortie standard), ce qui est la manière dont les clients MCP s'y connectent.

Ajouter à votre client MCP

La manière d'ajouter Research Friend dépend du client MCP que vous utilisez. Voici un exemple général de ce à quoi la configuration pourrait ressembler :

[[mcp_servers]]
id = "research-friend"
command = "node"
args = ["/path/to/mcp-research-friend/src"]
transport = "stdio"

Remplacez /path/to/mcp-research-friend par le chemin réel vers ce dossier sur votre ordinateur.

Outils

Outils web

friendly_web_fetch

Récupère une page web et retourne son contenu. Par défaut, retourne du markdown avec les liens préservés — idéal pour les LLM. Utilise Readability pour extraire le contenu principal (en supprimant la navigation, les publicités, etc.). Pour les PDF, la pagination ou la recherche dans le contenu, utilisez plutôt friendly_web_extract.

Paramètres :

  • url (requis) - L'adresse web à récupérer
  • outputFormat - Format de sortie : markdown (par défaut), text, ou html
  • waitMs - Temps supplémentaire à attendre après le chargement de la page, au cas où le contenu apparaîtrait lentement
  • timeoutMs - Combien de temps attendre avant d'abandonner (par défaut : 15 secondes)
  • maxChars - Quantité maximale de contenu à retourner (par défaut : 40 000 caractères)
  • includeHtml - Mettre à true pour également retourner le HTML brut avec le contenu
  • headless - Mettre à false pour voir la fenêtre du navigateur (utile pour le débogage)

Retourne :

  • url - L'URL qui a été demandée
  • finalUrl - L'URL après toute redirection
  • title - Le titre de la page
  • content - Le contenu extrait (dans le format demandé)
  • html - HTML brut (seulement si includeHtml est vrai)
  • meta - Métadonnées de la page (description, auteur, heure de publication, etc.)
  • fetchedAt - Horodatage ISO du moment où la page a été récupérée
  • truncated - Si le contenu a été tronqué pour correspondre à maxChars

friendly_search

Recherche sur le web et retourne une liste de résultats.

Paramètres :

  • query (requis) - Ce qu'il faut rechercher
  • engine - Quel moteur de recherche utiliser (duckduckgo ou google)
  • maxResults - Combien de résultats retourner (par défaut : 10, maximum : 50)
  • timeoutMs - Combien de temps attendre avant d'abandonner (par défaut : 15 secondes)
  • headless - Mettre à false pour voir la fenêtre du navigateur

Retourne :

  • query - La requête de recherche qui a été utilisée
  • engine - Quel moteur de recherche a été utilisé
  • results - Tableau de résultats, chacun avec title, url, et snippet
  • searchedAt - Horodatage ISO du moment où la recherche a été effectuée
  • fallback_result_html - HTML brut de la page (inclus seulement si aucun résultat n'a été trouvé)
  • debug_info - Informations de diagnostic sur la tentative de recherche

Gestion des CAPTCHA : Si un CAPTCHA est détecté lors de l'exécution en mode headless, l'outil réessaie automatiquement avec une fenêtre de navigateur visible. Cela vous donne une chance de résoudre le CAPTCHA manuellement. Le champ debug_info.retried indique si cette solution de repli a été utilisée.

friendly_web_extract

Extrait le contenu d'une URL. Détecte automatiquement si l'URL pointe vers un PDF ou une page web et gère chacun de manière appropriée.

Paramètres :

  • url (requis) - L'URL à récupérer (PDF ou page web)
  • maxChars - Quantité maximale de texte à retourner (par défaut : 40 000 caractères)
  • offset - Position du caractère à partir de laquelle commencer (par défaut : 0). Utilisez ceci pour paginer à travers un contenu volumineux.
  • search - Rechercher une phrase et retourner les correspondances avec le contexte environnant au lieu du contenu complet
  • contextChars - Caractères de contexte autour de chaque correspondance de recherche (par défaut : 200)
  • waitMs - Temps supplémentaire à attendre après le chargement de la page pour le contenu dynamique (pages web uniquement)
  • timeoutMs - Combien de temps attendre avant d'abandonner (par défaut : 15 secondes, pages web uniquement)
  • headless - Mettre à false pour voir la fenêtre du navigateur (pages web uniquement)

Retourne (mode normal) :

  • url - L'URL qui a été demandée
  • contentType - Soit pdf ou html
  • title - Le titre de la page/document
  • author - L'auteur du PDF (PDF uniquement, si disponible)
  • creationDate - Quand le PDF a été créé (PDF uniquement, si disponible)
  • pageCount - Nombre de pages (PDF uniquement)
  • totalChars - Nombre total de caractères (à utiliser avec offset pour paginer)
  • offset - Le décalage qui a été utilisé
  • content - Le contenu textuel extrait
  • fetchedAt - Horodatage ISO
  • truncated - S'il reste plus de contenu après ce segment

Retourne (mode recherche) :

  • url, contentType, title, totalChars, fetchedAt - Identique à ci-dessus
  • search - La phrase de recherche qui a été utilisée
  • matchCount - Nombre de correspondances trouvées
  • matches - Tableau de correspondances, chacune avec position, context, prefix, et suffix

friendly_web_ask

Récupère une URL (PDF ou page web) et demande à un LLM de répondre à des questions à son sujet. Détecte automatiquement le type de contenu. Le document est traité dans un contexte séparé, ce qui permet de garder votre conversation principale compacte.

Paramètres :

  • url (requis) - L'URL à récupérer (PDF ou page web)
  • ask (requis) - Question ou instruction pour le LLM (résumer, extraire des informations, répondre à des questions, etc.)
  • askMaxInputTokens - Nombre maximal de jetons d'entrée par appel LLM (par défaut : 150 000)
  • askMaxOutputTokens - Nombre maximal de jetons de sortie par appel LLM (par défaut : 4 096)
  • askTimeout - Délai d'attente en millisecondes (par défaut : 300 000 = 5 minutes)
  • askSplitAndSynthesize - Pour les documents volumineux : diviser en segments, traiter chacun, puis synthétiser les résultats (par défaut : false). Attention : consomme beaucoup de jetons.
  • waitMs - Temps supplémentaire à attendre après le chargement de la page pour le contenu dynamique (pages web uniquement)
  • timeoutMs - Combien de temps attendre avant d'abandonner (par défaut : 15 secondes, pages web uniquement)
  • headless - Mettre à false pour voir la fenêtre du navigateur (pages web uniquement)

Retourne :

  • url - L'URL qui a été demandée
  • contentType - Soit pdf ou html
  • title - Le titre de la page/document
  • totalChars - Nombre total de caractères dans le document
  • ask - L'instruction qui a été donnée
  • answer - La réponse du LLM
  • model - Le modèle qui a généré la réponse
  • chunksProcessed - Nombre de segments traités (1 pour les petits documents, plus lors de l'utilisation de askSplitAndSynthesize)
  • fetchedAt - Horodatage ISO

Le mode Ask utilise l'échantillonnage MCP pour qu'un LLM traite le document avec n'importe quelle instruction. Ceci est utile pour :

  • Les documents volumineux qui submergeraient le contexte
  • Réduire les coûts de jetons sur la conversation principale

Lorsque askSplitAndSynthesize est activé, les documents dépassant askMaxInputTokens sont automatiquement divisés en segments qui se chevauchent. Chaque segment est traité séparément, et les résultats sont synthétisés en une seule réponse cohérente. La réponse finale est fournie dans la même langue que votre demande, quelle que soit la langue du document.

Réserve de documents

La réserve est une bibliothèque locale de documents consultable. Elle prend en charge les PDF, les fichiers HTML et le texte brut (Markdown/TXT). Lorsque vous ajoutez un document, Research Friend stocke le fichier original, extrait le texte (pour les PDF/HTML) et enregistre les métadonnées dans une base de données locale. Les recherches utilisent ripgrep en arrière-plan pour une correspondance rapide et sensible aux phrases.

Emplacement de la réserve

La réserve se trouve sous ~/.research-friend/ :

  • inbox/ - Déposez les fichiers ici pour qu'ils soient traités
  • store/ - Stockage organisé des documents et texte extrait
  • stash.db - Base de données de métadonnées

Types de fichiers pris en charge

  • PDF : .pdf (texte extrait)
  • HTML : .html, .htm (texte extrait)
  • Markdown : .md, .markdown (stocké en texte brut)
  • Texte : .txt (stocké en texte brut)

Outils de la réserve

stash_open_inbox

Ouvrir le dossier de la boîte de réception de la réserve dans votre gestionnaire de fichiers pour un glisser-déposer plus facile.

Retourne :

  • opened - Si la demande d'ouverture du dossier a été envoyée
  • inboxPath - Chemin absolu vers la boîte de réception
  • command - Commande OS utilisée
  • args - Arguments de commande utilisés

stash_process_inbox

Traiter les fichiers dans inbox/, les classer par sujets, extraire le texte et stocker les résultats. Pour les documents longs, la classification utilise des sections échantillonnées (début/milieu/fin plus quelques segments aléatoires) pour améliorer la précision du sujet.

Retourne :

  • processed - Tableau des noms de fichiers traités avec succès
  • errors - Toute erreur rencontrée
  • documents - Tableau des enregistrements de documents créés

reindex_stash

Régénérer les résumés, réallouer les sujets et mettre à jour les métadonnées de la réserve pour les documents stockés. Si ids est omis ou vide, tous les documents sont réindexés.

Paramètres :

  • ids - ID des documents à réindexer (optionnel)

Retourne :

  • reindexed - ID des documents réindexés
  • errors - Toute erreur rencontrée
  • documents - Tableau des enregistrements de documents mis à jour

stash_list

Lister les documents dans la réserve.

Paramètres :

  • topic - Filtrer par sujet (optionnel)
  • limit - Nombre maximal de résultats (par défaut : 50)
  • offset - Décalage de pagination (par défaut : 0)

Retourne :

  • type - all ou topic
  • totalDocuments - Nombre total de documents (seulement lorsque type est all)
  • count - Résultats retournés après pagination
  • offset - Décalage de pagination utilisé
  • limit - Limite de pagination utilisée
  • topics - Résumé des sujets connus et du nombre de documents
  • documents - Liste des documents avec métadonnées (inclut isPrimary lors du listage d'un sujet)

stash_search

Rechercher des noms de fichiers et du contenu dans toute la réserve. Tous les termes de recherche doivent être présents (logique ET). Les correspondances de nom de fichier sont listées en premier. Utilisez des guillemets pour les phrases exactes.

Paramètres :

  • query (requis) - Termes de recherche. Utilisez des guillemets pour les phrases : "sparkling wine"
  • topic - Filtrer par sujet (optionnel)
  • ids - Filtrer par ID de document spécifiques (optionnel)
  • limit - Nombre maximal de documents à retourner (par défaut : 20)
  • offset - Décalage de pagination (par défaut : 0)
  • maxMatchesPerDoc - Nombre maximal de correspondances par document (par défaut : 50)
  • context - Lignes de contexte autour de chaque correspondance (par défaut : 1, max : 5). Contrôle à la fois la proximité à laquelle les termes doivent apparaître pour correspondre ET la quantité de texte environnant retourné. Retourne :
  • totalMatches - Total des documents correspondants avant pagination
  • count - Résultats retournés après pagination
  • results - Tableau de documents, chacun avec :
    • id, filename, fileType, summary, charCount, createdAt
    • matchType - filename, content, ou filename+content
    • matches - Tableau de { line, context } pour chaque emplacement de correspondance

Utilisez les valeurs line avec stash_extract pour accéder directement aux emplacements des correspondances.

stash_extract

Extrait le contenu d'un document stocké pour le lire. Utilisez les numéros de ligne des résultats de stash_search pour accéder directement aux correspondances.

Paramètres :

  • id (requis) - ID du document provenant de stash_list/stash_search
  • maxChars - Quantité maximale de texte à retourner (par défaut : 40 000 caractères)
  • offset - Position du caractère de départ (mutuellement exclusif avec line)
  • line - Numéro de ligne de départ (mutuellement exclusif avec offset)

Retourne :

  • id, filename, fileType, summary - Métadonnées du document
  • totalChars - Nombre total de caractères dans le document
  • offset - Décalage de caractère (inclus lors de l'utilisation de line pour référence)
  • line - Numéro de ligne (uniquement lorsque le paramètre line a été utilisé)
  • content - Le contenu textuel extrait
  • truncated - Indique s'il reste du contenu après ce segment

stash_ask

Permet à un LLM de répondre à des questions sur un document stocké. Le document est traité dans un contexte séparé, ce qui garde votre conversation principale compacte.

Paramètres :

  • id (requis) - ID du document provenant de stash_list/stash_search
  • ask (requis) - Question ou instruction pour le LLM
  • askMaxInputTokens - Nombre maximal de jetons d'entrée par appel LLM (par défaut : 150 000)
  • askMaxOutputTokens - Nombre maximal de jetons de sortie par appel LLM (par défaut : 4 096)
  • askTimeout - Délai d'expiration en millisecondes (par défaut : 300 000 = 5 minutes)
  • askSplitAndSynthesize - Pour les documents volumineux : diviser en segments, traiter chacun, puis synthétiser les résultats (par défaut : false)

Retourne :

  • id, filename, fileType, summary - Métadonnées du document
  • totalChars - Nombre total de caractères dans le document
  • ask - L'instruction qui a été donnée
  • answer - La réponse du LLM
  • model - Le modèle qui a généré la réponse
  • chunksProcessed - Nombre de segments traités

Flux typique

  1. Déposez les fichiers dans ~/.research-friend/inbox/
  2. Exécutez stash_process_inbox
  3. Utilisez stash_list pour parcourir les sujets
  4. Utilisez stash_search pour trouver les documents pertinents
  5. Utilisez stash_extract pour lire un document spécifique, ou stash_ask pour poser des questions à son sujet

Dépannage

« Navigateur fermé de manière inattendue » ou erreurs similaires

Essayez de réinstaller le navigateur :

npx playwright install chromium --force

Sur Linux, vous pourriez également avoir besoin de dépendances système :

npx playwright install-deps chromium

Le serveur ne démarre pas

Assurez-vous d'utiliser Node.js 20 ou une version plus récente :

node --version

Si votre version est plus ancienne, visitez nodejs.org pour en télécharger une plus récente.

Licence

MIT