Docs MCP Server : indexer la documentation que votre assistant lit vraiment
Grounded Docs MCP Server: Open-Source Alternative to Context7, Nia, and Ref.Tools
En bref
- De quoi s’agit-il ?
- Le projet arabold/docs-mcp-server construit un index documentaire local, versionné et interrogeable par un client MCP. Voici le mécanisme, les commandes réelles, et les cas où il n'est pas le bon outil.
- À qui s’adresse-t-il ?
- À adopter si vous voulez un index documentaire privé, alimenté par vos propres sources et interrogeable en CLI ou via MCP, avec Node.js 22 ou plus. À éviter si votre documentation change plusieurs fois par jour ou si vous refusez la charge d'un service local à maintenir.
- Puis-je l’utiliser commercialement ?
- Oui. MIT est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 17 jours.
- En quel langage est-il écrit ?
- Principalement TypeScript, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le problème : un assistant qui cite une version qui n'existe plus
Un assistant de code répond à partir de ce qu'il a vu à l'entraînement. Si vous utilisez React 19 et qu'il a surtout vu React 18, ses exemples compilent parfois et se comportent mal le reste du temps. Le README du projet pose le diagnostic en une phrase : fournir à l'assistant un index documentaire personnel et toujours à jour, pour qu'il interroge la version exacte utilisée dans le projet. La cible est donc l'ingénieur qui travaille sur une bibliothèque à rythme de publication rapide, ou sur un framework dont la documentation en ligne est la seule source de vérité. Le projet se présente comme l'alternative open source à Context7, Nia et Ref.Tools, ce qui situe la catégorie : des services qui exposent de la documentation à un agent via le protocole MCP. La différence annoncée tient en deux points, la récupération depuis les sources officielles à la demande, et l'exécution entièrement locale. Le README insiste sur le fait que le code ne quitte pas votre réseau. C'est un argument de déploiement, pas de performance, et il faut le lire comme tel.
Ce que le serveur ingère réellement
La liste des formats est le point le plus concret du dépôt. Le README annonce le support des PDF, Word (.docx/.doc), Excel, PowerPoint, OpenDocument, RTF, EPUB, FictionBook et Jupyter Notebooks. S'y ajoutent les archives ZIP, TAR et TAR compressé, dont le contenu est extrait et traité fichier par fichier. Côté web, HTML et XHTML. Côté balisage, Markdown, MDX, reStructuredText, AsciiDoc, Org Mode, Textile et R Markdown. Le projet revendique plus de 90 langages de programmation pris en charge, avec une page de référence dédiée (docs/concepts/supported-formats.md) qui détaille les types MIME. Les formats de données et de configuration sont couverts aussi : JSON, YAML, TOML, CSV, XML, SQL, GraphQL, Protocol Buffers, Dockerfile, Makefile, Terraform/HCL, INI, dotenv, Bazel. Cette largeur a un effet secondaire qu'il faut nommer : indexer un dépôt entier revient à indexer ses fichiers de configuration et ses notebooks, pas seulement sa documentation. Le bruit dans l'index dépend donc de ce que vous pointez, pas de l'outil. Un monorepo avec beaucoup de YAML généré produira un index plus bruyant qu'un site de documentation statique.
Le flux : scraping, découverte llms.txt, recherche
Le mécanisme visible dans le README se décompose en deux temps. D'abord l'indexation : une commande scrape prend un identifiant et une URL, récupère les pages, les convertit et les stocke. Ensuite l'interrogation : une commande search envoie une requête en langage naturel contre cet index. Le détail intéressant concerne le scraping web. Avant le crawl normal, l'outil sonde la présence d'un fichier llms.txt au niveau du sous-chemin de documentation et à la racine du site. Quand il le trouve, les liens curatés de ce fichier deviennent des graines de crawl supplémentaires, et les pages découvertes ainsi privilégient les variantes .md des URL, par exemple /guide/index.html.md ou /page.html.md, avant de retomber sur la page d'origine. Les requêtes web envoient par défaut l'en-tête Accept: text/markdown, text/html;q=0.9, */*;q=0.8. Autrement dit, le projet tente la négociation de contenu plutôt que de parser du HTML quand le serveur sait produire du Markdown. Pour les sites à routage par hash, une option dédiée existe : en mode scrapeMode=fetch, le scraper bascule automatiquement sur Playwright, car un fetch simple ne peut pas évaluer une route cliente. C'est un choix cohérent, et coûteux en ressources quand il se déclenche.
Mise en route : CLI d'abord, serveur ensuite
Le README recommande la CLI pour les agents et les scripts. Node.js 22 ou plus est requis. Trois commandes suffisent à couvrir le cycle complet. Pour indexer : npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react. Pour interroger : npx @arabold/docs-mcp-server@latest search react "useEffect cleanup" --output yaml. Pour récupérer une page seule en Markdown : npx @arabold/docs-mcp-server@latest fetch-url https://react.dev/reference/react/useEffect. Le comportement de sortie est documenté précisément : les commandes structurées émettent du JSON propre sur stdout en exécution non interactive, --output accepte json, yaml ou toon, les commandes en texte brut comme fetch-url gardent leur charge utile sur stdout, et les diagnostics passent par un logger partagé qui reste hors de stdout. --quiet supprime les diagnostics non erreur, --verbose active le débogage. Pour les sites à routage par hash, il faut ajouter --preserve-hashes, avec l'exemple fourni : scrape my-spa https://docs.example.com/#/guide --preserve-hashes. Le README précise que l'option ne doit servir que pour les SPA à hash, car les sites normaux utilisent les fragments pour les ancres internes. Côté serveur MCP, la commande est npx @arabold/docs-mcp-server@latest, l'interface web écoute sur http://localhost:6280, et la configuration client déclare une entrée de type sse pointant vers http://localhost:6280/sse. Une variante Docker est donnée avec les volumes docs-mcp-data et docs-mcp-config et les options --protocol http --host 0.0.0.0 --port 6280.
La recherche sémantique est optionnelle, et c'est un vrai arbitrage
Le README écrit que l'usage d'un modèle d'embedding est optionnel mais améliore nettement la qualité de recherche en activant la recherche vectorielle sémantique. L'activation la plus simple consiste à lancer le serveur avec OPENAI_API_KEY défini dans l'environnement. D'autres fournisseurs sont documentés dans docs/guides/embedding-models.md, notamment Ollama, Gemini et Azure. Deux conséquences pratiques. Sans embedding, la recherche repose sur autre chose que la similarité vectorielle, et le projet ne détaille pas dans le README ce que cela donne sur des requêtes paraphrasées. Avec embedding, vous ajoutez une dépendance externe : soit une clé API et des appels sortants vers un service tiers, soit un modèle local via Ollama et la charge correspondante. Le discours de confidentialité du projet mérite d'être lu avec cette nuance. Le serveur tourne localement et votre code ne sort pas, mais si vous configurez un fournisseur d'embeddings distant, le contenu indexé est envoyé à ce fournisseur pour être vectorisé. Un déploiement vraiment isolé suppose Ollama ou un modèle local équivalent. Le dépôt contient par ailleurs une page docs/guides/benchmarking.md qui décrit une mesure de la qualité de recherche avec métriques IR et scores jugés par LLM. Le README en donne les prérequis et la méthode, pas des résultats. Aucun chiffre de qualité n'est donc vérifiable ici.
Ce que l'outil ne fait pas
Le projet ne surveille pas vos sources. Le README décrit des scrapes et des rafraîchissements déclenchés, pas un agent qui détecte une nouvelle version de React et réindexe pendant la nuit. Si vous dépendez d'une bibliothèque qui publie plusieurs fois par jour, l'index se périme entre deux rafraîchissements, et l'assistant citera une documentation qui n'est plus la bonne. C'est exactement le problème que l'outil prétend résoudre, déplacé d'un cran. La fraîcheur devient votre responsabilité opérationnelle. Le rafraîchissement a une subtilité documentée : il réutilise par défaut le réglage preserveHashes stocké, et les points d'entrée CLI et web peuvent le surcharger explicitement. Une erreur de réglage à l'indexation se propage donc aux rafraîchissements suivants. Autre limite, le routage par hash déclenche Playwright, ce qui suppose un navigateur installé et des scrapes plus lents. Enfin, le README ne dit rien sur la taille maximale d'un index, sur la concurrence des scrapes ou sur la politique de rétention. Pour un site de documentation de quelques centaines de pages, ces questions ne se posent pas. Pour un dépôt GitHub volumineux, elles se poseront avant tout choix définitif.
Face à Context7 et aux services hébergés
Context7, Nia et Ref.Tools sont nommés par le projet lui-même comme les alternatives auxquelles il se compare. L'écart porte sur le modèle de déploiement, pas sur la fonction. Un service hébergé maintient sa propre collection de documentation, ce qui vous évite d'indexer quoi que ce soit, mais vous ne choisissez ni les sources, ni la version indexée, ni le moment de la mise à jour. Docs MCP Server inverse la répartition : vous fournissez les URL, les dépôts et les dossiers locaux, vous payez le coût du scraping et du stockage, et vous obtenez en échange la maîtrise de ce qui est indexé. Cette maîtrise couvre aussi les documents que personne n'héberge, comme un dossier local de spécifications ou une archive ZIP de PDF internes. Aucun service tiers ne fera cela pour vous. Le prix à payer est la maintenance d'un service local. Le dépôt publie des versions rapprochées, v3.0.0, v3.0.1 et v3.1.0 en quelques semaines, ce qui suggère un rythme de développement actif et, corollairement, des mises à jour fréquentes à suivre. Le paquet s'installe via npx, donc sans arbre de dépendances à gérer vous-même, mais la version épinglée dans vos scripts reste votre problème.
Licence, coût de maintenance et compatibilité
Le dépôt est publié sous licence MIT, ce qui autorise l'usage commercial, la modification et la redistribution, avec conservation du texte de licence. Les implications concrètes concernent surtout les composants que vous branchez autour : un modèle d'embedding OpenAI ou Gemini est régi par ses propres conditions, et un modèle local via Ollama par la licence de ce modèle. Rien dans le README ne traite de ces combinaisons, et ce n'est pas un avis juridique. Côté compatibilité, le projet annonce fonctionner avec tout client MCP, et cite Claude, Cline, Copilot, Gemini CLI, VS Code via Cline ou Roo, ainsi que Windsurf d'après les topics du dépôt. Le dossier skills/ contient des Agent Skills qui apprennent à un assistant à utiliser la CLI pour la recherche documentaire, la gestion d'index et la récupération d'URL. Le coût de mise à jour se limite donc à la version du paquet et, si vous utilisez Docker, à l'image ghcr.io/arabold/docs-mcp-server:latest. Épingler un tag plutôt que latest évite qu'une montée de version change le comportement de scraping sans que vous l'ayez décidé.
Conclusion éditoriale
À adopter si vous voulez un index documentaire privé, alimenté par vos propres sources et interrogeable en CLI ou via MCP, avec Node.js 22 ou plus. À éviter si votre documentation change plusieurs fois par jour ou si vous refusez la charge d'un service local à maintenir. Avant tout déploiement, lancez un scrape sur un seul paquet, vérifiez la qualité des résultats sans embedding, puis ajoutez OPENAI_API_KEY ou Ollama et relancez la même requête pour mesurer l'écart.
Notes de la communauté