website-to-markdown-mcp

v1.2.0

Published

9 months ago

Advanced MCP server for fetching websites and converting to markdown with AI-powered features and stealth capabilities

0High
0Medium
0Low

sunzhi

mcp model-context-protocol website markdown openapi swagger api-docs documentation stealth ai-scraping anti-detection

🌐 Website to Markdown MCP Server

語言: English | 繁體中文

一個強大的 Model Context Protocol (MCP) 伺服器，專為抓取網站內容並轉換為 Markdown 格式而設計，讓 AI 更容易理解和處理網站資訊。

✨ 主要特色

🆕 v1.2.0 版本新功能

🚀 重大功能增強

| 功能 | 狀態 | 描述 | |:-----|:----------:|:-----| | 🧠 增強內容處理器 | ✅ | AI 驅動的內容清理和擷取 | | 📊 智慧分析 | ✅ | 字數、閱讀時間、內容摘要 | | 🌍 語言檢測 | ✅ | 自動語言識別 | | 🎯 智慧重試 | ✅ | 指數退避智慧重試機制 | | 🔍 隱身瀏覽器 | ✅ | 反偵測瀏覽功能 | | ⚡ 速率限制 | ✅ | 內建速率限制和並發控制 | | 🧹 內容清理 | ✅ | 移除廣告、導航和無關內容 | | 📝 增強 Markdown | ✅ | 支援刪除線、底線、螢光標記 |

🚀 快速開始

🎯 方法 1：NPX 安裝（🌟 推薦）

💡 最簡單的方式：無需本地安裝！

步驟 1：建立配置檔案 📄

建立 my-websites.json 檔案：

{
  "websites": [
    {
      "name": "your_website",
      "url": "https://your-website.com",
      "description": "您的專案網站"
    },
    {
      "name": "api_docs",
      "url": "https://api.example.com/openapi.json",
      "description": "您的 API 規格文件"
    }
  ]
}

步驟 2：配置 MCP 伺服器 ⚙️

在 .cursor/mcp.json 中新增：

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

步驟 3：重啟並測試 🔄

重新啟動 Cursor
開啟 Chat 並使用 Agent 模式
測試指令：請列出所有已配置的網站

🎉 完成！無需安裝！

🎯 方法 2：本地安裝

💡 最佳實踐：適用於開發或客製化需求！

步驟 1：複製並建置

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

步驟 2：配置 MCP 伺服器

在 .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"
      }
    }
  }
}

🔥 增強輸出功能

📊 豐富內容分析

每次抓取的內容現在都包含：

📝 內容摘要：AI 生成的主要內容摘要
⏱️ 閱讀時間：基於內容長度的預估閱讀時間
🔢 字數統計：中英文準確字數統計
🌍 語言檢測：自動語言識別
🎯 內容品質評分：內容相關性評估

📋 增強 Markdown 輸出

# 🚀 範例網站

**來源**: https://example.com
**網站**: example_site - 範例網站
**📊 閱讀時間**: 5 分鐘
**🔢 字數**: 1,250 字
**🌍 語言**: 繁體中文
**📝 摘要**: 本文討論了網路技術的最新發展...

---

[增強格式的 Markdown 內容...]

🆕 OpenAPI/Swagger 完整支援

🔥 專業 API 文件

| 功能 | OpenAPI 3.x | Swagger 2.0 | 說明 | |:-----|:----------:|:-----------:|:-----| | 🔍 自動檢測 | ✅ | ✅ | 支援 JSON/YAML 格式 | | ✅ 專業驗證 | ✅ | ✅ | 使用 @readme/openapi-parser | | 📋 結構化解析 | ✅ | ✅ | 端點、參數、回應等 | | 🔗 引用解析 | ✅ | ✅ | 自動處理 $ref 引用 | | 📊 智慧摘要 | ✅ | ✅ | 生成 API 概覽 | | 📝 格式化輸出 | ✅ | ✅ | 易讀的 Markdown |

🌟 預配置範例網站

{
  "websites": [
    {
      "name": "petstore_openapi",
      "url": "https://petstore3.swagger.io/api/v3/openapi.json",
      "description": "🐕 Swagger Petstore OpenAPI 3.0 規格（示範）"
    },
    {
      "name": "petstore_swagger",
      "url": "https://petstore.swagger.io/v2/swagger.json",
      "description": "🐱 Swagger Petstore Swagger 2.0 規格（示範）"
    },
    {
      "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 規格"
    }
  ]
}

📦 安裝與設定

🛠️ 系統需求

Node.js 20.18.1+ (推薦：v22.15.0 LTS)
npm 10.0.0+ 或 yarn
Cursor 編輯器

⚠️ 重要提醒：某些依賴需要 Node.js v20.18.1 或更高版本。如果遇到引擎相容性警告，請更新您的 Node.js 版本。

⚡ NPM 套件安裝

# 全域安裝
npm install -g website-to-markdown-mcp

# 或直接使用 npx（推薦）
npx website-to-markdown-mcp

🔧 開發環境設定

# 1. 複製儲存庫
git clone https://github.com/your-username/website-to-markdown-mcp.git
cd website-to-markdown-mcp

# 2. 安裝相依套件
npm install

# 3. 建置專案
npm run build

🎛️ 進階配置選項

配置方式優先順序

graph TD
    A[🔍 檢查環境變數<br/>WEBSITES_CONFIG_PATH] --> B{檔案存在？}
    B -->|是| C[✅ 載入外部配置檔案]
    B -->|否| D[🔍 檢查環境變數<br/>WEBSITES_CONFIG]
    D --> E{JSON 有效？}
    E -->|是| F[✅ 載入內嵌配置]
    E -->|否| G[🔍 檢查 config.json]
    G --> H{檔案存在？}
    H -->|是| I[✅ 載入本地配置]
    H -->|否| J[🔧 使用預設配置]

🎨 配置方法詳解

📋 方法 1：外部配置檔案（🌟 推薦）

💡 優勢：易於編輯、語法高亮、版本控制友好

建立配置檔案

# 可以放在任何位置
touch my-api-configs.json

編輯配置內容

{
  "websites": [
    {
      "name": "my_docs",
      "url": "https://docs.example.com",
      "description": "📚 我的文件網站"
    }
  ]
}

設定環境變數

{
  "env": {
    "WEBSITES_CONFIG_PATH": "./my-api-configs.json"
  }
}

📋 方法 2：內嵌 JSON（向後相容）

{
  "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\":\"範例網站\"}]}"
      }
    }
  }
}

📋 方法 3：本地 config.json

直接編輯專案根目錄的 config.json：

{
  "websites": [
    {
      "name": "local_site",
      "url": "https://local.example.com",
      "description": "🏠 本地測試網站"
    }
  ]
}

🔧 可用工具

🌐 通用工具

| 工具名稱 | 功能 | 參數 | 範例 | |:--------|:-----|:-----|:-----| | fetch_website | 抓取任意網站 | url: 網站網址 | 抓取 OpenAPI 規格檔案 | | list_configured_websites | 列出配置的網站 | 無 | 查看所有可用網站 |

🎯 專用工具

每個配置的網站都會自動產生對應的專用工具：

fetch_petstore_openapi - 抓取 Petstore OpenAPI 3.0 規格
fetch_petstore_swagger - 抓取 Petstore Swagger 2.0 規格
fetch_github_api - 抓取 GitHub API 規格
fetch_tailwind_css - 抓取 Tailwind CSS 文件

📊 增強輸出格式範例

🌐 一般網站內容與分析

# 網站標題

**來源**: https://example.com
**網站**: example_site - 範例網站
**📊 閱讀時間**: 3 分鐘
**🔢 字數**: 650 字
**🌍 語言**: 繁體中文
**📝 摘要**: 本文提供了現代網頁開發實踐的全面概述，涵蓋前端框架、後端技術和部署策略。

---

[已清理廣告並擷取主要內容的增強 Markdown 內容...]

📋 OpenAPI 3.x 規格檔案

# 🚀 Example API (v2.1.0)

**來源**: https://api.example.com/openapi.json
**OpenAPI 版本**: 3.0.3
**驗證狀態**: ✅ 有效
**📊 處理時間**: 1.2 秒
**🔢 端點數量**: 25 個端點
**🌍 伺服器位置**: 3 台伺服器

---

## 📋 API 基本資訊

- **API 名稱**: Example API
- **版本**: 2.1.0
- **OpenAPI 版本**: 3.0.3
- **描述**: 一個適用於現代應用程式的強大範例 API

## 🌐 伺服器

1. **https://api.example.com**
   - 🏢 生產環境伺服器
2. **https://staging-api.example.com**
   - 🧪 測試環境伺服器

## 🛠️ API 端點

總共有 **25** 個端點：

### 👥 `/users`
- **GET**: 取得使用者列表
- **POST**: 建立新使用者

### 🔍 `/users/{id}`
- **GET**: 取得特定使用者
- **PUT**: 更新使用者資訊
- **DELETE**: 刪除使用者

## 🧩 元件

- **Schemas**: 12 個資料模型
- **Parameters**: 8 個可重用參數  
- **Responses**: 15 個可重用回應
- **Security Schemes**: 3 個安全機制

🎯 使用範例

💻 基本使用

請抓取 https://docs.example.com 的內容並轉換為 markdown

🔍 OpenAPI 規格抓取

請使用 fetch_petstore_openapi 工具抓取 Petstore 的 OpenAPI 規格

📚 文件網站抓取

請抓取 React 官方文件的內容

🚨 疑難排解

❓ 常見問題

錯誤: npm WARN EBADENGINE Unsupported engine

解決方案: 更新 Node.js 至 v20.18.1 或更高版本
下載: Node.js 官方網站
驗證: node --version

錯誤: Cannot find module './db.json'

解決方案 1: 清除 npm 快取: npm cache clean --force
解決方案 2: 更新 Node.js 版本
解決方案 3: 使用本地安裝而非 npx

Q: 配置修改後沒有生效？

✅ 確認 JSON 格式正確
✅ 重新啟動 Cursor
✅ 檢查環境變數名稱

Q: JSON 格式錯誤？

🛠️ 使用 JSON 驗證器
🛠️ 確認使用雙引號
🛠️ 檢查是否有多餘逗號

🔍 除錯模式

啟動時會在 stderr 輸出詳細日誌：

# 查看除錯訊息
npm run dev 2> debug.log

📈 效能與最佳化

⚡ 效能功能

🚀 智慧重試：指數退避智慧重試
💾 速率限制：內建速率限制防止過載
🎯 內容過濾：移除無關內容加快處理速度
🧹 廣告移除：自動廣告和彈窗移除
📊 隱身模式：反偵測瀏覽功能

🛡️ 安全考量

🔒 僅支援 HTTPS 網站（推薦）
🛠️ 自動過濾惡意腳本
📝 限制輸出內容長度
🔐 隱身瀏覽避免偵測

📦 相依套件

| 套件 | 版本 | 用途 | |:-----|:----:|:-----| | @modelcontextprotocol/sdk | ^1.0.0 | MCP 核心框架 | | @readme/openapi-parser | ^4.1.0 | 專業 OpenAPI 解析 | | axios | ^1.6.0 | HTTP 請求處理 | | cheerio | ^1.0.0 | HTML 解析引擎 | | turndown | ^7.1.2 | HTML 轉 Markdown | | yaml | ^2.8.0 | YAML 格式支援 | | zod | ^3.22.0 | 資料驗證框架 | | playwright | ^1.40.0 | 瀏覽器自動化 |

📝 更新日誌

🎉 v1.2.0 (最新版本)

🚀 重大功能更新

✨ 新增 AI 驅動的增強內容處理與清理
✨ 新增智慧分析：字數、閱讀時間、內容摘要
✨ 新增語言檢測和多語言支援
✨ 新增反偵測隱身瀏覽器功能
✨ 新增內建速率限制和重試機制
✨ 新增進階內容過濾和廣告移除
🔧 增強 Markdown 處理，支援更多 HTML 元素
📊 改進輸出格式，包含豐富元數據
🎯 修正各種技術問題和依賴項目

🎯 v1.1.0 (前一版本)