Website to Markdown MCP Server

🌐 Website to Markdown MCP Server

Um poderoso servidor Model Context Protocol (MCP) projetado para buscar conteúdo de sites e convertê-lo para o formato Markdown, facilitando o entendimento e o processamento de informações de sites por IA.

✨ Principais Recursos

🆕 Novidades na v1.2.0

🚀 Início Rápido

🎯 Método 1: Instalação via NPX (🌟 Recomendado)

💡 Forma mais fácil: Não é necessária instalação local!

Passo 1: Criar Arquivo de Configuração 📄

Crie um arquivo my-websites.json:

{
  "websites": [
    {
      "name": "your_website",
      "url": "https://your-website.com",
      "description": "Your Project Website"
    },
    {
      "name": "api_docs",
      "url": "https://api.example.com/openapi.json",
      "description": "Your API Specification"
    }
  ]
}

Passo 2: Configurar o Servidor MCP ⚙️

Adicione ao .cursor/mcp.json:

{
  "mcpServers": {
    "website-to-markdown": {
      "command": "npx",
      "args": ["-y", "website-to-markdown-mcp"],
      "disabled": false,
      "env": {
        "WEBSITES_CONFIG_PATH": "./my-websites.json"
      }
    }
  }
}

Passo 3: Reiniciar e Testar 🔄

1. Reinicie o Cursor
2. Abra o Chat e use o modo Agente
3. Comando de teste: Please list all configured websites

🎯 Método 2: Instalação Local

💡 Melhor Prática: Use este método para desenvolvimento ou personalização!

Passo 1: Clonar e Compilar

git clone https://github.com/your-username/website-to-markdown-mcp.git
cd website-to-markdown-mcp
npm install
npm run build

Passo 2: Configurar o Servidor MCP

Adicione ao .cursor/mcp.json:

{
  "mcpServers": {
    "website-to-markdown": {
      "command": "cmd",
      "args": ["/c", "node", "./website-to-markdown-mcp/dist/index.js"],
      "disabled": false,
      "env": {
        "WEBSITES_CONFIG_PATH": "./my-websites.json"
      }
    }
  }
}

🔥 Recursos Aprimorados de Saída

📊 Análise Rica de Conteúdo

Cada conteúdo buscado agora inclui:

• 📝 Resumo do Conteúdo: Resumo gerado por IA do conteúdo principal
• ⏱️ Tempo de Leitura: Tempo estimado de leitura com base no tamanho do conteúdo
• 🔢 Contagem de Palavras: Contagem precisa de palavras para inglês e chinês
• 🌍 Detecção de Idioma: Identificação automática de idioma
• 🎯 Pontuação de Qualidade do Conteúdo: Avaliação da relevância do conteúdo

📋 Saída Markdown Aprimorada

# 🚀 Example Website

**Source**: https://example.com
**Website**: example_site - Example Website
**📊 Reading Time**: 5 minutes
**🔢 Word Count**: 1,250 words
**🌍 Language**: English
**📝 Summary**: This article discusses the latest developments in web technology...

---

[Enhanced Markdown content with better formatting...]

🆕 Suporte Completo a OpenAPI/Swagger

🌟 Sites de Exemplo Pré-configurados

{
  "websites": [
    {
      "name": "petstore_openapi",
      "url": "https://petstore3.swagger.io/api/v3/openapi.json",
      "description": "🐕 Swagger Petstore OpenAPI 3.0 Spec (Demo)"
    },
    {
      "name": "petstore_swagger",
      "url": "https://petstore.swagger.io/v2/swagger.json",
      "description": "🐱 Swagger Petstore Swagger 2.0 Spec (Demo)"
    },
    {
      "name": "github_api",
      "url": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
      "description": "🐙 GitHub REST API OpenAPI Spec"
    }
  ]
}

📦 Instalação e Configuração

🛠️ Requisitos do Sistema

• Node.js 20.18.1+ (Recomendado: v22.15.0 LTS)
• npm 10.0.0+ ou yarn
• Cursor Editor

⚠️ Importante: Algumas dependências exigem Node.js v20.18.1 ou superior. Atualize sua versão do Node.js se encontrar avisos de incompatibilidade de engine.

⚡ Instalação do Pacote NPM

# Global installation
npm install -g website-to-markdown-mcp

# Or use directly with npx (recommended)
npx website-to-markdown-mcp

🔧 Configuração de Desenvolvimento

# 1. Clone repository
git clone https://github.com/your-username/website-to-markdown-mcp.git
cd website-to-markdown-mcp

# 2. Install dependencies
npm install

# 3. Build project
npm run build

🎛️ Opções Avançadas de Configuração

graph TD
    A[🔍 Check Environment Variable<br/>WEBSITES_CONFIG_PATH] --> B{File exists?}
    B -->|Yes| C[✅ Load External Config File]
    B -->|No| D[🔍 Check Environment Variable<br/>WEBSITES_CONFIG]
    D --> E{Valid JSON?}
    E -->|Yes| F[✅ Load Embedded Config]
    E -->|No| G[🔍 Check config.json]
    G --> H{File exists?}
    H -->|Yes| I[✅ Load Local Config]
    H -->|No| J[🔧 Use Default Config]

🎨 Detalhes dos Métodos de Configuração

📋 Método 1: Arquivo de Configuração Externo (🌟 Recomendado)

💡 Vantagens: Fácil de editar, realce de sintaxe, amigável para controle de versão

📋 Método 2: JSON Incorporado (Compatível com Versões Anteriores)

{
  "mcpServers": {
    "website-to-markdown": {
      "command": "cmd",
      "args": ["/c", "node", "./website-to-markdown-mcp/dist/index.js"],
      "disabled": false,
      "env": {
        "WEBSITES_CONFIG": "{\"websites\":[{\"name\":\"example\",\"url\":\"https://example.com\",\"description\":\"Example Website\"}]}"
      }
    }
  }
}

📋 Método 3: config.json Local

{
  "websites": [
    {
      "name": "local_site",
      "url": "https://local.example.com",
      "description": "🏠 Local Test Website"
    }
  ]
}

🔧 Ferramentas Disponíveis

🌐 Ferramentas Gerais

🎯 Ferramentas Dedicadas

Cada site configurado gera automaticamente ferramentas dedicadas correspondentes:

• fetch_petstore_openapi - Buscar especificação OpenAPI 3.0 do Petstore
• fetch_petstore_swagger - Buscar especificação Swagger 2.0 do Petstore
• fetch_github_api - Buscar especificação da API do GitHub
• fetch_tailwind_css - Buscar documentação do Tailwind CSS

📊 Exemplos de Formato de Saída Aprimorado

🌐 Conteúdo Geral de Site com Análises

# Website Title

**Source**: https://example.com
**Website**: example_site - Example Website
**📊 Reading Time**: 3 minutes
**🔢 Word Count**: 650 words
**🌍 Language**: English
**📝 Summary**: This article provides a comprehensive overview of modern web development practices, covering frontend frameworks, backend technologies, and deployment strategies.

---

[Enhanced cleaned Markdown content with ads removed and main content extracted...]

📋 Arquivo de Especificação OpenAPI 3.x

# 🚀 Example API (v2.1.0)

**Source**: https://api.example.com/openapi.json
**OpenAPI Version**: 3.0.3
**Validation Status**: ✅ Valid
**📊 Processing Time**: 1.2 seconds
**🔢 Endpoints**: 25 endpoints
**🌍 Server Locations**: 3 servers

---

## 📋 API Basic Information

- **API Name**: Example API
- **Version**: 2.1.0
- **OpenAPI Version**: 3.0.3
- **Description**: A powerful example API for modern applications

## 🌐 Servers

1. **https://api.example.com**
   - 🏢 Production server
2. **https://staging-api.example.com**
   - 🧪 Testing server

## 🛠️ API Endpoints

Total of **25** endpoints:

### 👥 `/users`
- **GET**: Get user list
- **POST**: Create new user

### 🔍 `/users/{id}`
- **GET**: Get specific user
- **PUT**: Update user information
- **DELETE**: Delete user

## 🧩 Components

- **Schemas**: 12 data models
- **Parameters**: 8 reusable parameters  
- **Responses**: 15 reusable responses
- **Security Schemes**: 3 security mechanisms

🎯 Exemplos de Uso

💻 Uso Básico

Please fetch the content from https://docs.example.com and convert to markdown

🔍 Busca de Especificação OpenAPI

Please use the fetch_petstore_openapi tool to fetch Petstore OpenAPI specification

📚 Busca de Site de Documentação

Please fetch React official documentation content

🚨 Solução de Problemas

📋 Guia Completo de Solução de Problemas: Consulte TROUBLESHOOTING.md para soluções detalhadas para problemas comuns.

❓ Soluções Rápidas

🔍 Modo de Depuração

Logs detalhados são enviados para stderr na inicialização:

# View debug messages
npm run dev 2> debug.log

📈 Desempenho e Otimização

⚡ Recursos de Desempenho

• 🚀 Nova Tentativa Inteligente: Nova tentativa inteligente com backoff exponencial
• 💾 Limitação de Taxa: Limitação de taxa integrada para evitar sobrecarga
• 🎯 Filtragem de Conteúdo: Remove conteúdo irrelevante para processamento mais rápido
• 🧹 Remoção de Anúncios: Remoção automática de anúncios e pop-ups
• 📊 Modo Furtivo: Capacidades de navegação anti-detecção

🛡️ Considerações de Segurança

• 🔒 Apenas sites HTTPS (recomendado)
• 🛠️ Filtro automático de scripts maliciosos
• 📝 Limitar o tamanho do conteúdo de saída
• 🔐 Navegação furtiva para evitar detecção

📦 Dependências

📝 Histórico de Versões

🎉 v1.2.0 (Mais Recente)

• ✨ Adicionado Processamento aprimorado de conteúdo com limpeza por IA
• ✨ Adicionado Análises inteligentes: contagem de palavras, tempo de leitura, resumo de conteúdo
• ✨ Adicionado Detecção de idioma e suporte a múltiplos idiomas
• ✨ Adicionado Capacidades de navegador furtivo para anti-detecção
• ✨ Adicionado Mecanismos integrados de limitação de taxa e nova tentativa
• ✨ Adicionado Filtragem avançada de conteúdo e remoção de anúncios
• 🔧 Aprimorado Processamento de Markdown com suporte a mais elementos HTML
• 📊 Melhorado Formato de saída com metadados ricos
• 🎯 Corrigido Vários problemas técnicos e dependências

🎯 v1.1.0 (Anterior)

• ✨ Adicionado Suporte completo a OpenAPI 3.x/Swagger 2.0
• ✨ Adicionado Detecção automática de formato JSON/YAML
• ✨ Adicionado Validação de especificação de nível profissional e resolução de referências
• ✨ Adicionado Mecanismo de adaptação automática de versão
• ✨ Adicionado Resumo estruturado de documentação de API
• 🔧 Pré-configurados Múltiplos exemplos de OpenAPI/Swagger
• 📦 Adicionada Distribuição de pacote NPM com suporte a npx
• 🎯 Aprimorados Métodos de instalação para melhor experiência do usuário

🎯 v1.0.0 (Estável)

• 🎉 Lançamento Inicial
• 🌐 Funções Básicas Busca de conteúdo de sites
• 📝 Funções Principais Conversão para Markdown
• ⚙️ Suporte a Configuração Gerenciamento de múltiplos sites

🤝 Contribuindo

💡 Como Contribuir

1. 🍴 Faça um Fork deste projeto
2. 🌟 Crie um branch de recurso (git checkout -b feature/AmazingFeature)
3. 📝 Faça Commit das alterações (git commit -m 'Add some AmazingFeature')
4. 📤 Envie para o branch (git push origin feature/AmazingFeature)
5. 🔄 Abra um Pull Request

🐛 Relatando Problemas

Relate problemas na página Issues, incluindo:

• 🔍 Descrição do Problema
• 🔄 Passos para Reproduzir
• 💻 Informações do Ambiente
• 📸 Capturas de Tela ou Logs

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.