Fetch as Markdown MCP Server

Busca páginas da web e as converte para markdown limpo, focando na extração do conteúdo principal.

GitHub
4
Experimente este MCPPatrocinado

Documentação

Servidor MCP Fetch as Markdown

Um servidor Model Context Protocol (MCP) que busca páginas da web e as converte em formato markdown limpo e legível, com foco na extração do conteúdo principal e minimização da sobrecarga de contexto.

Visão Geral

Este servidor MCP atua como uma ponte entre assistentes de IA e a web, projetado especificamente para:

  • Extrair Conteúdo Limpo: Foca no conteúdo principal do artigo, removendo navegação, anúncios e barras laterais
  • Minimizar Contexto: Remove elementos desnecessários para reduzir o uso de tokens, preservando a estrutura do conteúdo
  • Raspagem Respeitosa: Implementa limitação de taxa adequada, cabeçalhos de user-agent e tratamento de tempo limite
  • Resiliência a Erros: Lida graciosamente com vários erros relacionados à web e casos extremos

Recursos

🌐 Busca de Páginas Web

  • Busca qualquer página web publicamente acessível
  • Tratamento automático de redirecionamentos com relatório da URL final
  • Tempos limite configuráveis e tratamento adequado de erros
  • Limitação de taxa respeitosa (intervalos de 1 segundo entre solicitações)

🧹 Limpeza de Conteúdo

  • Remove navegação, anúncios, barras laterais e outros elementos não essenciais
  • Foca nas áreas de conteúdo principal usando detecção semântica de HTML
  • Remove atributos HTML desnecessários para reduzir o uso de tokens
  • Preserva a estrutura e legibilidade do conteúdo

📝 Conversão para Markdown

  • Converte HTML em markdown limpo e legível
  • Inclusão configurável de links e imagens
  • Hierarquia de cabeçalhos e formatação adequadas
  • Pós-processamento para remover espaços em branco excessivos

Instalação e Configuração

Pré-requisitos

  • Python 3.12 ou superior
  • Gerenciador de pacotes uv

Início Rápido

Execute diretamente com uvx:

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

Ou instale localmente:

  1. Clone ou baixe este projeto

  2. Instale as dependências:

    cd mcp-fetch-as-markdown
uv sync

  3. Execute o servidor:

    uv run python main.py

Integração com Assistentes de IA

Este servidor MCP foi projetado para funcionar com assistentes de IA que suportam o Model Context Protocol. Configure seu assistente de IA para conectar-se a este servidor via stdio.

Exemplo de configuração para Claude Desktop:

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

Ou se estiver usando uma instalação local:

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

Ferramentas Disponíveis

fetch

Busca uma página web e a converte em formato markdown limpo.

Parâmetros:

  • url (obrigatório): URL da página web a ser buscada e convertida
  • include_links (opcional): Se deve preservar links na saída markdown (padrão: true)
  • include_images (opcional): Se deve incluir referências de imagens (padrão: false)
  • timeout (opcional): Tempo limite da solicitação em segundos (5-30, padrão: 10)

Retorna:

  • Metadados da busca (URL original, URL final, título, tamanho do conteúdo, código de status, tipo de conteúdo)
  • Conteúdo markdown limpo com formatação adequada

Exemplo:

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

Como Funciona

Estratégia de Extração de Conteúdo

  1. Buscar Página: Faz solicitação HTTP com cabeçalhos adequados e tratamento de tempo limite
  2. Analisar HTML: Usa BeautifulSoup para analisar o conteúdo HTML
  3. Remover Elementos Indesejados: Remove scripts, estilos, navegação, anúncios, barras laterais, rodapés
  4. Encontrar Conteúdo Principal: Procura elementos semânticos como <main>, <article>, ou classes de conteúdo comuns
  5. Limpar Atributos: Remove atributos HTML desnecessários para reduzir o tamanho
  6. Converter para Markdown: Usa conversão markdown configurável com formatação adequada
  7. Pós-processar: Remove espaços em branco excessivos e linhas em branco

Raspagem Web Respeitosa

  • Limitação de Taxa: Intervalo mínimo de 1 segundo entre solicitações
  • User Agent: Identificação adequada como ferramenta "MCP-Fetch-As-Markdown"
  • Tratamento de Tempo Limite: Tempos limite configuráveis para evitar solicitações penduradas
  • Tratamento de Erros: Tratamento gracioso de problemas de rede, erros HTTP e conteúdo malformado
  • Suporte a Redirecionamentos: Segue redirecionamentos e relata URLs finais

Formato de Saída Estruturado

Todas as respostas incluem:

  • Bloco de Metadados: URL original, URL final, título da página, estatísticas de conteúdo, status HTTP
  • Bloco de Conteúdo: Conversão markdown limpa do conteúdo principal da página

Esta estrutura torna as respostas tanto legíveis por humanos quanto analisáveis por máquinas, minimizando o uso de tokens.

Tratamento de Erros

  • URLs Inválidas: Validação clara e mensagens de erro
  • Problemas de Rede: Tratamento de tempo limite, erro de conexão e falha de DNS
  • Erros HTTP: Tratamento adequado de 404, 500 e outros códigos de status HTTP
  • Conteúdo Malformado: Tratamento gracioso de HTML quebrado e problemas de codificação

Casos de Uso

Para Pesquisa e Análise

  • Converter artigos e postagens de blog em markdown limpo para análise
  • Extrair conteúdo principal de notícias e artigos de pesquisa
  • Coletar informações minimizando contexto irrelevante

Para Processamento de Conteúdo

  • Preparar conteúdo web para processamento adicional por IA
  • Extrair texto limpo de páginas web para resumo
  • Converter conteúdo HTML em markdown para documentação

Para Assistentes de IA

  • Buscar e processar conteúdo web com sobrecarga mínima de tokens
  • Extrair informações relevantes filtrando ruído
  • Fornecer conteúdo limpo e estruturado para raciocínio de IA

Exemplos

Busca Básica de Página

Pergunte ao seu assistente de IA: "Busque o conteúdo desta URL de artigo como markdown"

O servidor irá:

  1. Buscar a página web com cabeçalhos adequados e limitação de taxa
  2. Extrair a área de conteúdo principal, removendo navegação e anúncios
  3. Converter para formato markdown limpo
  4. Retornar metadados e conteúdo estruturados

Com Preservação de Links

Pergunte ao seu assistente de IA: "Busque esta página, mas mantenha todos os links intactos"

O servidor irá:

  1. Buscar e processar a página normalmente
  2. Preservar todos os hiperlinks em formato markdown [text](url)
  3. Manter a estrutura de links enquanto limpa outros elementos

Exemplo de Tratamento de Erros

Pergunte ao seu assistente de IA: "Tente buscar conteúdo desta URL quebrada"

O servidor irá:

  1. Validar o formato da URL
  2. Tentar a solicitação com tempo limite adequado
  3. Retornar uma mensagem de erro estruturada se a solicitação falhar
  4. Fornecer informações úteis sobre o que deu errado

Desenvolvimento

Estrutura do Projeto

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)

Dependências Principais

  • mcp: Framework Model Context Protocol
  • requests: Tratamento de solicitações HTTP
  • beautifulsoup4: Análise de HTML e extração de conteúdo
  • markdownify: Conversão de HTML para markdown

Personalização

O servidor pode ser facilmente personalizado modificando main.py:

  • Seletores de Conteúdo: Modifique os seletores CSS usados para encontrar o conteúdo principal
  • Limitação de Taxa: Ajuste o intervalo mínimo entre solicitações
  • Configurações de Tempo Limite: Altere os valores padrão e máximo de tempo limite
  • Filtragem de Conteúdo: Adicione regras personalizadas de processamento ou filtragem de conteúdo
  • Opções de Markdown: Personalize as configurações de conversão markdown

Testando o Servidor

Teste o servidor diretamente:

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

Ou com instalação local:

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

Para testes interativos, use o script de exemplo:

uv run python example.py

Solução de Problemas

Problemas Comuns

  1. Erros de Importação: Certifique-se de que todas as dependências estejam instaladas com uv sync
  2. Tempos Limite de Conexão: Alguns sites podem ser lentos; tente aumentar o parâmetro de tempo limite
  3. Limitação de Taxa: O servidor aplica intervalos de 1 segundo entre solicitações
  4. Solicitações Bloqueadas: Alguns sites podem bloquear solicitações automatizadas; isso é comportamento esperado

Depuração

Ative o registro de depuração modificando o nível de registro em main.py:

logging.basicConfig(level=logging.DEBUG)

Compatibilidade de Sites

  • Sites Modernos: Funciona melhor com estrutura HTML padrão
  • Sites com Muito JavaScript: Não pode executar JavaScript; busca apenas o HTML inicial
  • Conteúdo Protegido: Respeita robots.txt e restrições de acesso do site
  • Limites de Taxa: Implementa práticas respeitosas de raspagem

Uso Ético

Esta ferramenta foi projetada para pesquisa legítima, análise e processamento de conteúdo. Por favor:

  • Respeite os Termos de Serviço: Sempre verifique e cumpra os termos de serviço do site
  • Evite Sobrecarga: A limitação de taxa integrada ajuda, mas esteja atento à frequência de solicitações
  • Atribuição: Dê crédito adequado às fontes originais ao usar conteúdo extraído
  • Conformidade Legal: Certifique-se de que seu caso de uso esteja em conformidade com as leis e regulamentos aplicáveis

Contribuindo

Esta é uma implementação simples de arquivo único, projetada para clareza e facilidade de modificação. Sinta-se à vontade para:

  • Adicionar suporte para estratégias adicionais de extração de conteúdo
  • Implementar filtragem personalizada para tipos específicos de sites
  • Adicionar cache para melhor desempenho
  • Estender com opções adicionais de formatação markdown

Licença

Este projeto usa a mesma licença de suas dependências. O conteúdo buscado de sites permanece sujeito aos termos de serviço e direitos autorais do site original.