Fetch as Markdown MCP Server

Obtiene páginas web y las convierte a markdown limpio, centrándose en la extracción del contenido principal.

GitHub
4

Documentación

Servidor MCP Fetch as Markdown

Un servidor de Protocolo de Contexto de Modelo (MCP) que obtiene páginas web y las convierte a un formato markdown limpio y legible, centrándose en la extracción del contenido principal mientras minimiza la sobrecarga de contexto.

Descripción general

Este servidor MCP actúa como un puente entre los asistentes de IA y la web, diseñado específicamente para:

  • Extraer contenido limpio: Se centra en el contenido principal del artículo, eliminando navegación, anuncios y barras laterales
  • Minimizar contexto: Elimina elementos innecesarios para reducir el uso de tokens mientras preserva la estructura del contenido
  • Extracción respetuosa: Implementa límites de velocidad adecuados, cabeceras de agente de usuario y manejo de tiempos de espera
  • Resiliencia ante errores: Maneja de manera elegante varios errores web y casos límite

Características

🌐 Obtención de páginas web

  • Obtiene cualquier página web de acceso público
  • Manejo automático de redirecciones con reporte de la URL final
  • Tiempos de espera configurables y manejo adecuado de errores
  • Límite de velocidad respetuoso (intervalos de 1 segundo entre solicitudes)

🧹 Limpieza de contenido

  • Elimina navegación, anuncios, barras laterales y otros elementos no esenciales
  • Se centra en las áreas de contenido principal mediante la detección semántica de HTML
  • Elimina atributos HTML innecesarios para reducir el uso de tokens
  • Preserva la estructura y legibilidad del contenido

📝 Conversión a Markdown

  • Convierte HTML a markdown limpio y legible
  • Inclusión configurable de enlaces e imágenes
  • Jerarquía de encabezados y formato adecuados
  • Post-procesamiento para eliminar espacios en blanco excesivos

Instalación y configuración

Requisitos previos

  • Python 3.12 o superior
  • uv gestor de paquetes

Inicio rápido

Ejecutar directamente con uvx:

uvx git+https://github.com/bhubbb/mcp-fetch-as-markdown

O instalar localmente:

  1. Clonar o descargar este proyecto

  2. Instalar dependencias:

    cd mcp-fetch-as-markdown
uv sync

  3. Ejecutar el servidor:

    uv run python main.py

Integración con asistentes de IA

Este servidor MCP está diseñado para funcionar con asistentes de IA que admitan el Protocolo de Contexto de Modelo. Configure su asistente de IA para conectarse a este servidor a través de stdio.

Ejemplo de configuración para Claude Desktop:

{
  "mcpServers": {
    "fetch-as-markdown": {
      "command": "uvx",
      "args": ["git+https://github.com/bhubbb/mcp-fetch-as-markdown"]
    }
  }
}

O si se utiliza una instalación local:

{
  "mcpServers": {
    "fetch-as-markdown": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp-fetch-as-markdown/main.py"]
    }
  }
}

Herramientas disponibles

fetch

Obtiene una página web y la convierte a formato markdown limpio.

Parámetros:

  • url (obligatorio): URL de la página web a obtener y convertir
  • include_links (opcional): Si se deben conservar los enlaces en la salida markdown (por defecto: true)
  • include_images (opcional): Si se deben incluir referencias a imágenes (por defecto: false)
  • timeout (opcional): Tiempo de espera de la solicitud en segundos (5-30, por defecto: 10)

Devuelve:

  • Metadatos de la obtención (URL original, URL final, título, longitud del contenido, código de estado, tipo de contenido)
  • Contenido markdown limpio con formato adecuado

Ejemplo:

{
  "name": "fetch",
  "arguments": {
    "url": "https://example.com/article",
    "include_links": true,
    "include_images": false,
    "timeout": 15
  }
}

Cómo funciona

Estrategia de extracción de contenido

  1. Obtener página: Realiza una solicitud HTTP con cabeceras adecuadas y manejo de tiempo de espera
  2. Analizar HTML: Utiliza BeautifulSoup para analizar el contenido HTML
  3. Eliminar elementos no deseados: Elimina scripts, estilos, navegación, anuncios, barras laterales y pies de página
  4. Encontrar contenido principal: Busca elementos semánticos como <main>, <article>, o clases de contenido comunes
  5. Limpiar atributos: Elimina atributos HTML innecesarios para reducir el tamaño
  6. Convertir a Markdown: Utiliza conversión markdown configurable con formato adecuado
  7. Post-procesar: Elimina espacios en blanco excesivos y líneas en blanco

Extracción web respetuosa

  • Límite de velocidad: Intervalo mínimo de 1 segundo entre solicitudes
  • Agente de usuario: Identificación adecuada como herramienta "MCP-Fetch-As-Markdown"
  • Manejo de tiempo de espera: Tiempos de espera configurables para evitar solicitudes colgadas
  • Manejo de errores: Manejo elegante de problemas de red, errores HTTP y contenido malformado
  • Soporte de redirecciones: Sigue redirecciones e informa las URL finales

Formato de salida estructurado

Todas las respuestas incluyen:

  • Bloque de metadatos: URL original, URL final, título de la página, estadísticas de contenido, estado HTTP
  • Bloque de contenido: Conversión markdown limpia del contenido principal de la página

Esta estructura hace que las respuestas sean tanto legibles para humanos como analizables por máquinas, minimizando el uso de tokens.

Manejo de errores

  • URL no válidas: Validación clara y mensajes de error
  • Problemas de red: Manejo de tiempo de espera, errores de conexión y fallos de DNS
  • Errores HTTP: Manejo adecuado de códigos de estado HTTP 404, 500 y otros
  • Contenido malformado: Manejo elegante de HTML roto y problemas de codificación

Casos de uso

Para investigación y análisis

  • Convertir artículos y publicaciones de blog a markdown limpio para análisis
  • Extraer contenido principal de noticias y documentos de investigación
  • Recopilar información minimizando el contexto irrelevante

Para procesamiento de contenido

  • Preparar contenido web para procesamiento adicional con IA
  • Extraer texto limpio de páginas web para resúmenes
  • Convertir contenido HTML a markdown para documentación

Para asistentes de IA

  • Obtener y procesar contenido web con sobrecarga mínima de tokens
  • Extraer información relevante filtrando el ruido
  • Proporcionar contenido limpio y estructurado para el razonamiento de IA

Ejemplos

Obtención básica de páginas

Pida a su asistente de IA: "Obtén el contenido de esta URL de artículo como markdown"

El servidor:

  1. Obtendrá la página web con cabeceras adecuadas y límite de velocidad
  2. Extraerá el área de contenido principal, eliminando navegación y anuncios
  3. Convertirá a formato markdown limpio
  4. Devolverá metadatos y contenido estructurados

Con conservación de enlaces

Pida a su asistente de IA: "Obtén esta página pero conserva todos los enlaces intactos"

El servidor:

  1. Obtendrá y procesará la página normalmente
  2. Conservará todos los hipervínculos en formato markdown [text](url)
  3. Mantendrá la estructura de enlaces mientras limpia otros elementos

Ejemplo de manejo de errores

Pida a su asistente de IA: "Intenta obtener contenido de esta URL rota"

El servidor:

  1. Validará el formato de la URL
  2. Intentará la solicitud con tiempo de espera adecuado
  3. Devolverá un mensaje de error estructurado si la solicitud falla
  4. Proporcionará información útil sobre lo que salió mal

Desarrollo

Estructura del proyecto

mcp-fetch-as-markdown/
├── main.py          # Main MCP server implementation
├── pyproject.toml   # Project dependencies and metadata
├── AGENT.md         # Development rules and guidelines
├── example.py       # Usage examples and demonstrations
└── .venv/           # Virtual environment (created by uv)

Dependencias clave

  • mcp: Marco de trabajo del Protocolo de Contexto de Modelo
  • requests: Manejo de solicitudes HTTP
  • beautifulsoup4: Análisis de HTML y extracción de contenido
  • markdownify: Conversión de HTML a markdown

Personalización

El servidor se puede personalizar fácilmente modificando main.py:

  • Selectores de contenido: Modifique los selectores CSS utilizados para encontrar el contenido principal
  • Límite de velocidad: Ajuste el intervalo mínimo entre solicitudes
  • Configuración de tiempo de espera: Cambie los valores de tiempo de espera predeterminados y máximos
  • Filtrado de contenido: Agregue reglas personalizadas de procesamiento o filtrado de contenido
  • Opciones de Markdown: Personalice la configuración de conversión markdown

Prueba del servidor

Pruebe el servidor directamente:

uvx git+https://github.com/bhubbb/mcp-fetch-as-markdown

O con instalación local:

cd mcp-fetch-as-markdown
uv run python main.py

Para pruebas interactivas, utilice el script de ejemplo:

uv run python example.py

Solución de problemas

Problemas comunes

  1. Errores de importación: Asegúrese de que todas las dependencias estén instaladas con uv sync
  2. Tiempos de espera de conexión: Algunos sitios web pueden ser lentos; intente aumentar el parámetro de tiempo de espera
  3. Límite de velocidad: El servidor aplica intervalos de 1 segundo entre solicitudes
  4. Solicitudes bloqueadas: Algunos sitios web pueden bloquear solicitudes automatizadas; este es un comportamiento esperado

Depuración

Habilite el registro de depuración modificando el nivel de registro en main.py:

logging.basicConfig(level=logging.DEBUG)

Compatibilidad de sitios web

  • Sitios web modernos: Funciona mejor con estructura HTML estándar
  • Sitios con mucho JavaScript: No puede ejecutar JavaScript; obtiene solo el HTML inicial
  • Contenido protegido: Respeta robots.txt y las restricciones de acceso del sitio web
  • Límites de velocidad: Implementa prácticas de extracción respetuosas

Uso ético

Esta herramienta está diseñada para investigación legítima, análisis y procesamiento de contenido. Por favor:

  • Respete los Términos de Servicio: Siempre verifique y cumpla con los términos de servicio del sitio web
  • Evite la sobrecarga: El límite de velocidad integrado ayuda, pero tenga en cuenta la frecuencia de las solicitudes
  • Atribución: Dé el crédito adecuado a las fuentes originales al utilizar contenido extraído
  • Cumplimiento legal: Asegúrese de que su caso de uso cumpla con las leyes y regulaciones aplicables

Contribuciones

Esta es una implementación simple de un solo archivo diseñada para claridad y facilidad de modificación. Siéntase libre de:

  • Agregar soporte para estrategias adicionales de extracción de contenido
  • Implementar filtrado personalizado para tipos específicos de sitios web
  • Agregar caché para un mejor rendimiento
  • Extender con opciones adicionales de formato markdown

Licencia

Este proyecto utiliza la misma licencia que sus dependencias. El contenido obtenido de sitios web sigue sujeto a los términos de servicio y derechos de autor del sitio web original.