fumasignal-mcp

fumasignal-mcp es un servidor de Model Context Protocol (MCP) de terceros y no oficial cuyo propósito es permitir que los asistentes de IA busquen y lean sitios de documentación construidos con Fumadocs. Se apunta ya sea a una URL desplegada de Fumadocs o a un directorio de proyecto local de Fumadocs, y expone un conjunto de herramientas de solo lectura a cualquier cliente compatible con MCP. El nombre del proyecto es un juego de palabras con el identificador del autor de Fumadocs fuma-nama y con la idea de que las señales de humo transportan mensajes entre un cliente de IA y una herramienta externa. El autor afirma explícitamente que no está afiliado al proyecto Fumadocs. Modos de funcionamiento El servidor se ejecuta en dos modos. En modo remoto, proporcionas el origen de un sitio desplegado de Fumadocs (solo esquema más host, con la ruta de documentación configurada por separado), lo que no requiere configuración local. En modo local, lo apuntas a una raíz de proyecto Fumadocs en disco, lo cual es adecuado para trabajo sin conexión o comprobación previa al despliegue. Se distribuye como un binario npx único, por lo que una invocación típica es npx -y fumasignal-mcp --url https://your-docs.com, y todo acceso se describe como de solo lectura, nunca modificando la documentación. Herramientas expuestas Se proporcionan siete herramientas. search_docs realiza búsqueda de texto completo a través de la API de búsqueda de Orama del sitio y requiere una consulta; también acepta un argumento tag para sitios con múltiples documentos. list_pages enumera las páginas de documentación conocidas y puede filtrarse por prefijo de URL. get_page obtiene el contenido Markdown completo de una página. get_section recupera una sección única identificada por un ancla de encabezado. get_toc lista los encabezados de una página junto con sus anclas. get_meta devuelve datos de frontmatter o metadatos de página como JSON. get_llms_txt obtiene llms.txt, o llms-full.txt cuando se establece la opción full. Las referencias a páginas pueden darse como una ruta de URL, una URL absoluta del mismo host, o un slug bajo el prefijo docs. Configuración del cliente El README documenta fragmentos de configuración para Claude Desktop, Claude Code, Cursor, VS Code con GitHub Copilot Chat y Continue.dev, utilizando transporte stdio y el mismo comando npx en cada caso. Se pueden servir múltiples sitios de documentación registrando varias instancias bajo diferentes claves. Para Continue.dev, se muestran tanto un archivo JSON reutilizable como el formato YAML nativo. Banderas de configuración y variables de entorno Las banderas de CLI incluyen --url para el origen del sitio, --local para una raíz de proyecto local, --search-path para una ruta de API de búsqueda no predeterminada (predeterminado /api/search, siempre se resuelve desde la raíz del origen), --docs-prefix para el prefijo de URL de documentación (predeterminado /docs), --content-dir para el directorio local de contenido (predeterminado content/docs), --auth-header para sitios autenticados, --cache-ttl para almacenamiento en caché de respuestas remotas (predeterminado 300000 ms), además de --version y --help. Cada bandera tiene una variable de entorno FUMASIGNAL_* correspondiente, con las banderas explícitas tomando precedence, y existe una variable adicional FUMASIGNAL_LOG_LEVEL que no tiene equivalente de bandera. El README recomienda pasar secretos mediante la variable de entorno en lugar de la línea de comandos para que no persistan en el historial del shell o en los listados de procesos. Cómo funciona la recuperación En modo remoto, las búsquedas llaman a la API de Orama del sitio y manejan tanto formas de respuesta de array plano como de hits/document; listar páginas obtiene sitemap.xml y filtra por el prefijo docs; la recuperación de páginas primero intenta variantes .md, .mdx y /raw de la URL y, en caso contrario, recurre al scraping de HTML renderizado y convierte el elemento article o main a Markdown con Turndown; llms.txt se obtiene directamente. Las respuestas remotas se almacenan en caché en memoria con un TTL predeterminado de cinco minutos. En modo local, el servidor recorre archivos Markdown y MDX bajo el directorio content, analiza frontmatter con gray-matter, asigna archivos índice a la raíz docs y puntúa resultados de búsqueda mediante coincidencia de tokens ponderada por encabezados. Compatibilidad y pruebas El proyecto requiere Node.js 20 o posterior, afirma haber sido probado contra la API de búsqueda Orama predeterminada y la disposición estándar de sitemap, y dice que funciona con cualquier cliente MCP STDIO, nombrando entre otros Claude Desktop, Claude Code, Cursor, opciones de VS Code, Zed y Cline. Informa de más de 280 pruebas unitarias con fixtures que cubren las rutas de búsqueda, sitemap y HTML. Solución de problemas y desarrollo El README cubre problemas comunes: un sitemap ausente solo afecta a list_pages, un 404 en búsqueda suele indicar una ruta de búsqueda no predeterminada o una URL que incluye una ruta, el scraping de HTML puede producir ruido en sitios sin endpoints Markdown, y se proporciona un script MCP Inspector para verificar que las herramientas se registren correctamente. Las instrucciones de desarrollo cubren clonar, instalar, verificar tipos con tsc, linting con eslint, pruebas con vitest, construcción con tsup y un script de verificación combinado. Se aceptan contribuciones, con la solicitud de abrir un issue primero para cambios no triviales. El proyecto se publica bajo la licencia MIT.