Html2md MCP

🚀 HTML 轉 Markdown MCP 服務器

這是一個用於將 HTML 網頁轉換為簡潔 Markdown 格式的 MCP（模型上下文協議）服務器。它能在保留表格、圖像和重要內容的同時，將 HTML 文件大小縮減約 90 - 95%，非常適合用於 AI 上下文。

✨ 主要特性

• 可將 URL 中的 HTML 轉換為簡潔的 Markdown 格式。
• 保留表格、圖像和鏈接。
• 移除不必要的元素（腳本、樣式、導航欄、頁腳、頁眉）。
• 顯著減小文件大小（通常壓縮率為 90 - 95%）。
• 可對圖像、表格和鏈接進行配置。
• 基於 trafilatura 和 BeautifulSoup4 構建，提取功能強大。
• 流式處理，可高效處理大頁面。
• 大小限制，防止下載過大的內容（1MB - 50MB）。
• 可選緩存，加快對相同 URL 的重複轉換速度。
• 🌐 支持使用 Playwright 的瀏覽器模式：可處理 JavaScript 密集型網站和需要身份驗證的頁面。
  • 執行 JavaScript（非常適合單頁應用：React、Vue、Angular）。
  • 使用帶有 cookie 的瀏覽器配置文件（可訪問需要身份驗證的頁面）。
  • 支持 Chrome、Firefox、WebKit。
  • 可對動態內容配置等待策略。

📦 安裝指南

前提條件

• Python 3.10 或更高版本。
• uv 包管理器（推薦）或 pip。

使用 uv 安裝（推薦）

# 克隆倉庫
git clone <your-repo-url>
cd html2md

# 安裝依賴
uv pip install -e .

# 安裝 Playwright 瀏覽器（瀏覽器模式需要）
playwright install chromium

使用 pip 安裝

# 克隆倉庫
git clone <your-repo-url>
cd html2md

# 創建虛擬環境
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 安裝依賴
pip install -e .

# 安裝 Playwright 瀏覽器（瀏覽器模式需要）
playwright install chromium

Docker 安裝（生產環境推薦）

使用 Docker 是使用 html2md 最簡單的方式：

# 構建鏡像
docker build -t html2md .

# 或者使用預構建的鏡像（發佈後）
docker pull your-registry/html2md:latest

對於 Claude Desktop，使用 Docker 進行配置：

{
  "mcpServers": {
    "html2md": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "html2md"
      ]
    }
  }
}

Docker 鏡像特性：

• 預安裝了帶有 Chromium 的 Playwright。
• 經過優化，體積最小化（約 1GB）。
• 使用非 root 用戶，提高安全性。
• 可直接使用，無需額外設置。

💻 使用示例

配置完成後，MCP 服務器將在 Claude Desktop 中可用。你可以使用 html_to_markdown 工具：

基礎用法

將此網頁轉換為 Markdown：https://example.com/article

帶選項的用法

使用 html_to_markdown 工具，參數如下：
- url: https://example.com/docs
- include_images: false
- include_tables: true

用於 JavaScript 密集型網站的瀏覽器模式

使用 html_to_markdown 工具，參數如下：
- url: https://spa-application.com
- fetch_method: playwright
- wait_for: networkidle

訪問需要身份驗證的頁面

使用 html_to_markdown 工具，參數如下：
- url: https://private-site.com/dashboard
- fetch_method: playwright
- use_user_profile: true
- browser_type: chromium

⚠️ 重要提示

當 use_user_profile=true 時，請確保在運行前關閉 Chrome。

工具參數

基本參數：

• url（必需）：要轉換的網頁 URL。
• include_images（可選，默認：true）：是否在 Markdown 中包含圖像。
• include_tables（可選，默認：true）：是否在 Markdown 中包含表格。
• include_links（可選，默認：true）：是否在 Markdown 中包含鏈接。
• timeout（可選，默認：30）：請求超時時間（秒），範圍為 5 - 120 秒。

性能參數：

• max_size（可選，默認：10MB）：要下載內容的最大字節數，範圍為 1MB - 50MB。
• use_cache（可選，默認：false）：是否啟用緩存以加快重複轉換速度。
• cache_ttl（可選，默認：3600）：緩存的生存時間（秒），範圍為 60 - 86400 秒。

瀏覽器模式參數：

• fetch_method（可選，默認："fetch"）：獲取方法 - "fetch"（快速）或 "playwright"（處理 JavaScript 和身份驗證）。
• browser_type（可選，默認："chromium"）：使用的瀏覽器 - "chromium"、"firefox" 或 "webkit"。
• headless（可選，默認：true）：是否以無頭模式運行瀏覽器。
• wait_for（可選，默認："networkidle"）：等待策略 - "load"、"domcontentloaded" 或 "networkidle"。
• use_user_profile（可選，默認：false）：是否使用帶有 cookie 的瀏覽器配置文件（需要關閉 Chrome）。

📚 詳細文檔

開發

安裝開發依賴

uv pip install -e ".[dev]"

運行測試

pytest

代碼格式化

# 使用 black 進行格式化
black src/ tests/

# 使用 ruff 進行檢查
ruff check src/ tests/

類型檢查

mypy src/

架構

該項目由三個主要模塊組成：

converter.py

核心 HTML 轉 Markdown 轉換功能：

• fetch_html()：從 URL 下載 HTML。
• clean_html()：使用 BeautifulSoup 移除不必要的元素。
• convert_to_markdown()：使用 trafilatura 將清理後的 HTML 轉換為 Markdown。
• html_to_markdown()：將所有步驟組合成的主要工作流程。

server.py

MCP 服務器實現：

• 註冊 html_to_markdown 工具。
• 處理工具調用和錯誤響應。
• 使用標準輸入輸出傳輸運行異步 MCP 服務器。

utils.py

實用函數：

• 用於緩存的哈希計算。
• 文本格式化和截斷。
• 域名提取。
• 文件名清理。

cache.py

內存緩存系統：

• 支持 TTL 的 SimpleCache 類。
• 全局緩存實例管理。
• 舊條目自動過期。
• 基於哈希的 URL + 參數緩存鍵。

browser.py

Playwright 瀏覽器自動化：

• fetch_html_playwright() - 基於異步瀏覽器的 HTML 獲取。
• 支持 Chromium、Firefox、WebKit。
• 集成用戶配置文件以進行身份驗證訪問。
• 可對動態內容配置等待策略。

故障排除

服務器未在 Claude Desktop 中顯示

1. 檢查 claude_desktop_config.json 中的路徑是否為絕對路徑且正確。
2. 完全重啟 Claude Desktop。
3. 檢查 Claude Desktop 日誌以查看錯誤信息。

安裝問題

# 驗證 Python 版本
python --version  # 應為 3.10 或更高版本

# 嘗試重新安裝依賴
uv pip install --force-reinstall -e .

轉換錯誤

• 超時錯誤：增加 timeout 參數。
• 內容為空：某些網站可能會阻止自動化請求或使用 JavaScript 渲染。
  • 解決方案：使用 fetch_method: playwright 執行 JavaScript。
• 解析錯誤：網頁結構可能不尋常或格式錯誤。
• 內容過大：增加 max_size 參數（最大 50MB）或頁面超過限制。
• 緩存問題：如果需要獲取最新內容，可使用 use_cache: false 禁用緩存。

瀏覽器模式問題

• Playwright 未安裝：運行 playwright install chromium。
• 瀏覽器啟動失敗：檢查是否有足夠的權限和磁盤空間。
• 用戶配置文件錯誤：在使用 use_user_profile: true 之前，確保 Chrome 已完全關閉。
• 頁面未完全加載：嘗試不同的 wait_for 策略：
  • "load" - 最快，等待頁面加載事件。
  • "domcontentloaded" - 等待 DOM 準備好。
  • "networkidle" - 最慢但最可靠，等待網絡空閒。
• 身份驗證失敗：確保使用 browser_type: chromium 和 use_user_profile: true。

性能

典型的轉換結果：

• 原始 HTML：約 500KB - 2MB。
• Markdown 輸出：約 25KB - 100KB。
• 壓縮率：90 - 95%。
• 處理時間：2 - 10 秒（取決於頁面大小和網絡情況）。

📄 許可證

本項目採用 MIT 許可證。

貢獻

歡迎貢獻代碼！請隨時提交問題或拉取請求。

鳴謝

本項目基於以下工具構建：

• MCP SDK - 模型上下文協議
• trafilatura - 網頁內容提取
• BeautifulSoup4 - HTML 解析