Documentation Crawler & MCP Server

Documentación Crawler y servidor MCP

Este proyecto proporciona un conjunto de herramientas para rastrear sitios web, generar documentación Markdown y hacer que dicha documentación se pueda buscar a través de un servidor de Protocolo de contexto de modelo (MCP), diseñado para la integración con herramientas como Cursor.

Características

• Rastreador web ( crawler_cli ) :
  • Rastrea sitios web a partir de una URL determinada utilizando crawl4ai .
  • Profundidad de rastreo configurable, patrones de URL (incluir/excluir), tipos de contenido, etc.
  • Limpieza opcional de HTML antes de la conversión a Markdown (elimina enlaces de navegación, encabezados y pies de página).
  • Genera un único archivo Markdown consolidado a partir del contenido rastreado.
  • Guarda la salida en ./storage/ de forma predeterminada.
• Servidor MCP ( mcp_server ) :
  • Carga archivos Markdown desde el directorio ./storage/ .
  • Analiza Markdown en fragmentos semánticos basados en encabezados.
  • Genera incrustaciones vectoriales para cada fragmento utilizando sentence-transformers ( multi-qa-mpnet-base-dot-v1 ).
  • Almacenamiento en caché: utiliza un archivo de caché ( storage/document_chunks_cache.pkl ) para almacenar fragmentos procesados e incrustaciones.
    • Primera ejecución: el inicio inicial del servidor después de rastrear nuevos documentos puede llevar algún tiempo, ya que necesita analizar, fragmentar y generar incrustaciones para todo el contenido.
    • Ejecuciones posteriores: si el archivo de caché existe y los tiempos de modificación de los archivos de origen .md en ./storage/ no han cambiado, el servidor carga directamente desde el caché, lo que genera tiempos de inicio mucho más rápidos.
    • Invalidación de caché: la caché se invalida y se regenera automáticamente si se modifica, agrega o elimina algún archivo .md en ./storage/ desde la última creación de la caché.
  • Expone herramientas MCP a través de fastmcp para clientes como Cursor:
    • list_documents : enumera los documentos rastreados disponibles.
    • get_document_headings : recupera la estructura del encabezado de un documento.
    • search_documentation : realiza una búsqueda semántica en fragmentos de documentos utilizando similitud vectorial.
• Integración de Cursor : Diseñado para ejecutar el servidor MCP a través del transporte stdio para su uso dentro de Cursor.

Flujo de trabajo

1. Rastrear: utilice la herramienta crawler_cli para rastrear un sitio web y generar un archivo .md en ./storage/ .
2. Ejecutar servidor: configure y ejecute mcp_server (normalmente administrado por un cliente MCP como Cursor).
3. Cargar e incrustar: el servidor carga, fragmenta e incrusta automáticamente el contenido de los archivos .md en ./storage/ .
4. Consulta: utilice el cliente MCP (por ejemplo, Cursor Agent) para interactuar con las herramientas del servidor ( list_documents , search_documentation , etc.) para consultar el contenido rastreado.

Configuración

Este proyecto utiliza uv para la gestión y ejecución de dependencias.

1. Instalar uv : siga las instrucciones del sitio web de uv .
2. Clonar el repositorio:
   git clone https://github.com/alizdavoodi/MCPDocSearch.git cd MCPDocSearch
3. Instalar dependencias:
   uv sync
   Este comando crea un entorno virtual (normalmente .venv ) e instala todas las dependencias enumeradas en pyproject.toml .

Uso

1. Documentación de rastreo

Ejecute el rastreador utilizando el script crawl.py o directamente a través de uv run .

Ejemplo básico:

Esto rastreará https://docs.example.com con la configuración predeterminada y guardará la salida en ./storage/docs.example.com.md .

Ejemplo con opciones:

Ver todas las opciones:

Las opciones clave incluyen:

• --output / -o : especifica la ruta del archivo de salida.
• --max-depth / -d : establece la profundidad de rastreo (debe estar entre 1 y 5).
• --include-pattern / --exclude-pattern : Filtrar las URL para rastrear.
• --keyword / -k : Palabras clave para la puntuación de relevancia durante el rastreo.
• --remove-links / --keep-links : Controla la limpieza de HTML.
• --cache-mode : controla el almacenamiento en caché crawl4ai ( DEFAULT , BYPASS , FORCE_REFRESH ).
• --wait-for : Esperar un tiempo específico (segundos) o un selector CSS antes de capturar el contenido (p. ej., 5 o 'css:.content' ). Útil para páginas con carga retardada.
• --js-code : ejecuta JavaScript personalizado en la página antes de capturar el contenido.
• --page-load-timeout : establece el tiempo máximo (segundos) que se debe esperar para que se cargue una página.
• --wait-for-js-render / --no-wait-for-js-render : Habilita un script específico para gestionar mejor las aplicaciones de página única (SPA) con uso intensivo de JavaScript al desplazarse y hacer clic en los botones "Cargar más". Establece automáticamente un tiempo de espera predeterminado si no se especifica --wait-for .

Refinando los rastreos con patrones y profundidad

A veces, es posible que quieras rastrear solo una subsección específica de un sitio de documentación. Esto suele requerir un poco de prueba y error con --include-pattern y --max-depth .

• --include-pattern : Restringe el rastreador para que solo siga los enlaces cuyas URL coincidan con los patrones especificados. Use comodines ( * ) para mayor flexibilidad.
• --max-depth : Controla la cantidad de clics que el rastreador recorrerá desde la URL de inicio. Una profundidad de 1 significa que solo rastrea páginas enlazadas directamente desde la URL de inicio. Una profundidad de 2 significa que rastrea esas páginas y las páginas enlazadas desde ellas (si también coinciden con los patrones de inclusión), y así sucesivamente.

Ejemplo: Rastrear solo la sección API de administración de Pulsar

Supongamos que solo desea el contenido en https://pulsar.apache.org/docs/4.0.x/admin-api-* .

1. URL de inicio: Puede comenzar en la página de descripción general: https://pulsar.apache.org/docs/4.0.x/admin-api-overview/ .
2. Incluir patrón: solo desea enlaces que contengan admin-api : --include-pattern "*admin-api*" .
3. Profundidad máxima: Debes determinar cuántos niveles de profundidad tienen los enlaces de la API de administración desde la página inicial. Comienza con 2 y aumenta si es necesario.
4. Modo detallado: use -v para ver qué URL se están visitando o se omiten, lo que ayuda a depurar los patrones y la profundidad.

Revise el archivo de salida ( ./storage/pulsar.apache.org.md por defecto en este caso). Si faltan páginas, intente aumentar --max-depth a 3 Si se incluyen demasiadas páginas no relacionadas, especifique --include-pattern o agregue reglas --exclude-pattern .

2. Ejecución del servidor MCP

El servidor MCP está diseñado para ser ejecutado por un cliente MCP como Cursor mediante el transporte stdio . El comando para ejecutar el servidor es:

Sin embargo, es necesario ejecutarlo desde el directorio raíz del proyecto ( MCPDocSearch ) para que Python pueda encontrar el módulo mcp_server .

⚠️ Precaución: Tiempo de incrustación

El servidor MCP genera incrustaciones localmente la primera vez que se ejecuta o cuando cambian los archivos Markdown de origen en ./storage/ . Este proceso implica cargar un modelo de aprendizaje automático y procesar todos los fragmentos de texto.

• El tiempo varía: el tiempo necesario para la generación de la incrustación puede variar significativamente en función de:
  • Hardware: los sistemas con una GPU compatible (CUDA o Apple Silicon/MPS) serán mucho más rápidos que los sistemas con solo CPU.
  • Tamaño de los datos: la cantidad total de archivos Markdown y la longitud de su contenido afectan directamente el tiempo de procesamiento.
• Tenga paciencia: Para conjuntos de documentación grandes o en hardware lento, el inicio inicial (o el inicio después de los cambios) puede tardar varios minutos. Los inicios posteriores que usen la caché serán mucho más rápidos. ⏳

3. Configuración de Cursor/Claude para el escritorio

Para utilizar este servidor con Cursor, cree un archivo .cursor/mcp.json en la raíz de este proyecto ( MCPDocSearch/.cursor/mcp.json ) con el siguiente contenido:

Explicación:

• "doc-query-server" : un nombre para el servidor dentro de Cursor.
• "command": "uv" : especifica uv como el ejecutor del comando.
• "args" :
  • "--directory", "/path/to/your/MCPDocSearch" : Fundamentalmente , le indica uv que cambie su directorio de trabajo a la raíz de su proyecto antes de ejecutar el comando. Reemplace /path/to/your/MCPDocSearch con la ruta absoluta real en su sistema.
  • "run", "python", "-m", "mcp_server.main" : el comando uv se ejecutará dentro del directorio y entorno virtual correctos.

Después de guardar este archivo y reiniciar Cursor, "doc-query-server" debería estar disponible en la configuración de MCP de Cursor y ser utilizable por el Agente (por ejemplo, @doc-query-server search documentation for "how to install" ).

Para Claude for Desktop, puede utilizar esta documentación oficial para configurar el servidor MCP

Dependencias

Bibliotecas clave utilizadas:

• crawl4ai : funcionalidad básica de rastreo web.
• fastmcp : implementación del servidor MCP.
• sentence-transformers : Generando incrustaciones de texto.
• torch : Requerido por sentence-transformers .
• typer : Construyendo la CLI del rastreador.
• uv : Gestión de proyectos y medio ambiente.
• beautifulsoup4 (vía crawl4ai ): análisis de HTML.
• rich : Salida de terminal mejorada.

Arquitectura

El proyecto sigue este flujo básico:

1. crawler_cli : ejecuta esta herramienta, proporcionando una URL de inicio y opciones.
2. Rastreo ( crawl4ai ) : la herramienta utiliza crawl4ai para buscar páginas web, siguiendo enlaces según reglas configuradas (profundidad, patrones).
3. Limpieza ( crawler_cli/markdown.py ) : opcionalmente, el contenido HTML se limpia (eliminando la navegación, los enlaces) utilizando BeautifulSoup.
4. Generación de Markdown ( crawl4ai ) : el HTML limpio se convierte a Markdown.
5. Almacenamiento ( ./storage/ ) : el contenido Markdown generado se guarda en un archivo en el directorio ./storage/ .
6. Inicio mcp_server : cuando se inicia el servidor MCP (generalmente a través de la configuración de Cursor), ejecuta mcp_server/data_loader.py .
7. Carga y almacenamiento en caché : El cargador de datos busca un archivo de caché ( .pkl ). Si es válido, carga fragmentos e incrustaciones desde la caché. De lo contrario, lee archivos .md desde ./storage/ .
8. Fragmentación e incrustación : Los archivos Markdown se analizan en fragmentos según los encabezados. Se generan incrustaciones para cada fragmento mediante sentence-transformers y se almacenan en memoria (y en caché).
9. Herramientas MCP ( mcp_server/mcp_tools.py ) : El servidor expone herramientas ( list_documents , search_documentation , etc.) a través de fastmcp .
10. Consulta (Cursor) : un cliente MCP como Cursor puede llamar a estas herramientas. search_documentation utiliza las incrustaciones precalculadas para encontrar fragmentos relevantes en función de la similitud semántica con la consulta.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Contribuyendo

¡Agradecemos sus contribuciones! No dude en abrir un problema o enviar una solicitud de incorporación de cambios.

Notas de seguridad

• Caché Pickle: Este proyecto utiliza el módulo pickle de Python para almacenar en caché los datos procesados ( storage/document_chunks_cache.pkl ). Descompilar datos de fuentes no confiables puede ser inseguro. Asegúrese de que el directorio ./storage/ solo sea escribible por usuarios/procesos confiables.