À propos du projet

fumasignal-mcp est un serveur Model Context Protocol (MCP) tiers et non officiel dont l'objectif est de permettre aux assistants IA de rechercher et de lire des sites de documentation construits avec Fumadocs. Il pointe vers une URL Fumadocs déployée ou vers un répertoire de projet Fumadocs local, et expose un ensemble d'outils en lecture seule à tout client prenant en charge MCP. Le nom du projet fait référence au pseudo de l'auteur de Fumadocs, fuma-nama, et à l'idée de signaux de fumée transportant des messages entre un client IA et un outil externe. L'auteur indique explicitement qu'il n'est pas affilié au projet Fumadocs. Modes de fonctionnement Le serveur fonctionne selon deux modes. En mode distant, vous fournissez l'origine d'un site Fumadocs déployé (schéma plus hôte uniquement, le chemin de documentation étant configuré séparément), ce qui ne nécessite aucune configuration locale. En mode local, vous le pointez vers la racine d'un projet Fumadocs sur disque, ce qui convient au travail hors ligne ou à la vérification avant déploiement. Il est distribué sous forme de binaire npx unique, donc une invocation typique est npx -y fumasignal-mcp --url https://your-docs.com, et tous les accès sont décrits comme en lecture seule, sans jamais modifier la documentation. Outils exposés Sept outils sont fournis. search_docs effectue une recherche en texte intégral via l'API de recherche Orama du site et nécessite une requête ; elle accepte également un argument tag pour les sites multi-docs. list_pages énumère les pages de documentation connues et peut être filtrée par préfixe d'URL. get_page récupère le contenu Markdown complet d'une page. get_section récupère une section unique identifiée par une ancre de titre. get_toc liste les titres d'une page ainsi que leurs ancres. get_meta retourne les métadonnées de la page ou le frontmatter au format JSON. get_llms_txt récupère llms.txt, ou llms-full.txt lorsque l'option full est activée. Les références de page peuvent être fournies sous forme de chemin URL, d'URL absolue même hôte ou de slug sous le préfixe docs. Configuration du client Le README documente des extraits de configuration pour Claude Desktop, Claude Code, Cursor, VS Code avec GitHub Copilot Chat et Continue.dev, en utilisant le transport stdio et la même commande npx dans chaque cas. Plusieurs sites de documentation peuvent être servis en enregistrant plusieurs instances sous des clés différentes. Pour Continue.dev, un fichier JSON réutilisable et le format YAML natif sont présentés. Indicateurs CLI et variables d'environnement Les indicateurs CLI incluent --url pour l'origine du site, --local pour une racine de projet local, --search-path pour un chemin d'API de recherche non par défaut (par défaut /api/search, toujours résolu depuis la racine de l'origine), --docs-prefix pour le préfixe d'URL de documentation (par défaut /docs), --content-dir pour le répertoire de contenu local (par défaut content/docs), --auth-header pour les sites authentifiés, --cache-ttl pour la mise en cache des réponses distantes (par défaut 300000 ms), ainsi que --version et --help. Chaque indicateur dispose d'une variable d'environnement FUMASIGNAL_* correspondante, les indicateurs explicites ayant la priorité, et il existe une variable FUMASIGNAL_LOG_LEVEL supplémentaire sans équivalent en indicateur. Le README recommande de transmettre les secrets via la variable d'environnement plutôt que par la ligne de commande afin qu'ils ne persistent pas dans l'historique du shell ou les listes de processus. Fonctionnement de la récupération En mode distant, search appelle l'API Orama du site et gère à la fois les formes de réponse flat-array et hits/document ; le listing de pages récupère sitemap.xml et filtre par préfixe de documentation ; la récupération de pages tente d'abord les variantes .md, .mdx et /raw de l'URL, puis se rabat sur l'analyse HTML rendu et la conversion de l'élément article ou main en Markdown avec Turndown ; llms.txt est récupéré directement. Les réponses distantes sont mises en cache en mémoire avec un TTL par défaut de cinq minutes. En mode local, le serveur parcourt les fichiers Markdown et MDX sous le répertoire de contenu, analyse le frontmatter avec gray-matter, mappe les fichiers index à la racine docs et calcule les scores de recherche en utilisant une correspondance de tokens pondérée par les titres. Compatibilité et tests Le projet nécessite Node.js 20 ou version ultérieure, indique qu'il a été testé contre l'API de recherche Orama par défaut et la disposition standard de sitemap, et fonctionne avec n'importe quel client MCP STDIO, citant Claude Desktop, Claude Code, Cursor, les options VS Code, Zed et Cline entre autres. Il rapporte plus de 280 tests unitaires avec des fixtures couvrant les chemins de recherche, sitemap et HTML. Dépannage et développement Le README couvre les problèmes courants : un sitemap manquant n'affecte que list_pages, une erreur 404 sur search indique généralement un chemin de recherche non par défaut ou une URL incluant un chemin, l'analyse HTML peut produire du bruit sur les sites sans points de terminaison Markdown, et un script MCP Inspector est fourni pour vérifier que les outils s'enregistrent correctement. Les instructions de développement couvrent le clonage, l'installation, la vérification des types avec tsc, le linting avec eslint, les tests avec vitest, la construction avec tsup et un script de vérification combiné. Les contributions sont les bienvenues, avec une demande d'ouvrir d'abord un problème pour les changements non triviaux. Le projet est publié sous la licence MIT.