Markdown MCP

🚀 Markdown MCP 服務器

Markdown MCP 服務器是一個基於模型上下文協議（MCP）的工具，它藉助 Playwright 從網頁中提取簡潔的 Markdown 內容。該服務器提供了 get_page_markdown 工具，可從任意 URL 提取網頁的主要內容，同時過濾掉導航欄、頁眉、頁腳等非內容元素。

✨ 主要特性

• 🎯 智能內容提取：自動識別並提取網頁的主要內容。
• 🧹 簡潔輸出：過濾掉導航欄、頁眉、頁腳、側邊欄和廣告等內容。
• 🎨 豐富的 Markdown 格式：保留包括標題、粗體、斜體、代碼塊、列表和表格等格式。
• 🖼️ 圖片支持：可選擇在 Markdown 中包含圖片引用。
• 🔗 鏈接支持：可選擇在 Markdown 中包含超鏈接。
• ⚡ 快速可靠：使用 Playwright 進行強大的網頁抓取。
• 🔄 動態內容處理：能夠處理 JavaScript 豐富的網站和動態內容加載。
• 🛡️ 錯誤處理：具備強大的錯誤處理機制，包含備用提取方法。

📦 安裝指南

1. 克隆或下載本倉庫：

   git clone <repository-url>
   cd markdown-mcp
   

2. 安裝依賴項：

   npm install
   

3. 安裝 Playwright 瀏覽器：

   npx playwright install chromium
   

4. 使腳本可執行（可選）：

   chmod +x markdown-mcp.js
   

💻 使用示例

作為 MCP 服務器啟動

啟動服務器：

node markdown-mcp.js

服務器提供了一個工具：get_page_markdown

工具參數

• url（必需）：要提取 Markdown 內容的 URL。
• includeImages（可選，默認值：true）：是否在 Markdown 中包含圖片引用。
• includeLinks（可選，默認值：true）：是否在 Markdown 中包含超鏈接。
• waitForSelector（可選）：在提取內容前等待的 CSS 選擇器（適用於動態內容）。
• timeout（可選，默認值：30000）：導航超時時間（以毫秒為單位）。

基礎用法

{
  "name": "get_page_markdown",
  "arguments": {
    "url": "https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html",
    "includeImages": true,
    "includeLinks": true,
    "timeout": 30000
  }
}

高級用法

從特定部分提取內容：

{
  "name": "get_page_markdown",
  "arguments": {
    "url": "https://example.com/article",
    "waitForSelector": ".main-content",
    "includeImages": false,
    "includeLinks": true
  }
}

使用自定義超時時間提取內容：

{
  "name": "get_page_markdown",
  "arguments": {
    "url": "https://slow-loading-site.com",
    "timeout": 60000
  }
}

📚 詳細文檔

文件結構

本項目包含兩個針對不同客戶端優化的 MCP 服務器文件：

• markdown-mcp.js - 針對 Claude Desktop 進行了優化。
• markdown-mcp-gemini.js - 針對 Gemini CLI 進行了優化。

兩個文件都提供了相同的 get_page_markdown 工具，但針對每個客戶端進行了不同的配置，以實現最佳性能。

添加到 AI 客戶端

此 MCP 服務器可與多個支持模型上下文協議的 AI 客戶端一起使用。以下是針對最流行客戶端的使用說明。

Claude Desktop 集成

要在 Claude Desktop 中使用此 MCP 服務器，需要將其添加到 Claude Desktop 的配置文件中。

步驟 1：定位 Claude Desktop 配置文件

• macOS：配置文件路徑為 ~/Library/Application Support/Claude/claude_desktop_config.json。
• Windows：配置文件路徑為 %APPDATA%\Claude\claude_desktop_config.json。
• Linux：配置文件路徑為 ~/.config/claude/claude_desktop_config.json。

步驟 2：編輯配置文件

1. 使用文本編輯器打開配置文件。
2. 將 markdown-mcp 服務器添加到 mcpServers 部分。
3. 更新路徑，指向你的 markdown-mcp.js 文件。

步驟 3：配置示例

macOS 配置

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["/Users/yourusername/path/to/markdown-mcp/markdown-mcp.js"],
      "env": {}
    }
  }
}

Windows 配置

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\path\\to\\markdown-mcp\\markdown-mcp.js"],
      "env": {}
    }
  }
}

Linux 配置

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["/home/yourusername/path/to/markdown-mcp/markdown-mcp.js"],
      "env": {}
    }
  }
}

步驟 4：重啟 Claude Desktop

更新配置文件後，重啟 Claude Desktop 以使更改生效。

步驟 5：驗證安裝

1. 打開 Claude Desktop。
2. 開始一個新的對話。
3. 嘗試讓 Claude 使用 markdown-mcp 工具從網頁中提取內容。
4. 示例：“使用 markdown-mcp 從 https://example.com 提取內容”。

故障排除

如果 MCP 服務器無法正常工作：

1. 檢查文件路徑：確保 markdown-mcp.js 的路徑正確，且文件存在。
2. 驗證 Node.js：確保 Node.js 已安裝，並且可以從命令行訪問。
3. 檢查權限：確保腳本具有執行權限。
4. 手動測試：嘗試在終端中運行 node markdown-mcp.js，查看是否有錯誤。
5. 檢查 Claude Desktop 日誌：在 Claude Desktop 的開發者控制檯中查找錯誤消息。

常見問題：

• 路徑未找到：仔細檢查配置文件中的文件路徑。
• 未找到 Node.js：確保 Node.js 已安裝，並已添加到系統路徑中。
• 權限被拒絕：運行 chmod +x markdown-mcp.js 使腳本可執行。
• 缺少依賴項：在 markdown-mcp 目錄中運行 npm install。

Gemini CLI 集成

要在 Gemini CLI 中使用此 MCP 服務器，請按照以下步驟操作：

步驟 1：安裝 Gemini CLI

如果你尚未安裝 Gemini CLI，請運行以下命令：

npm install -g @google/gemini-cli

驗證安裝：

gemini --version

步驟 2：將 MCP 服務器添加到 Gemini CLI

將你的 markdown-mcp 服務器添加到 Gemini CLI：

gemini mcp add markdown-mcp /Users/yourusername/path/to/markdown-mcp/markdown-mcp-gemini.js

重要提示：請將 /Users/yourusername/path/to/markdown-mcp/markdown-mcp-gemini.js 替換為你實際的 markdown-mcp-gemini.js 文件路徑。

步驟 3：驗證集成

列出所有配置的 MCP 服務器，以驗證集成是否成功：

gemini mcp list

你應該會在服務器列表中看到 markdown-mcp。

步驟 4：測試集成

使用 Gemini CLI 測試 markdown-mcp 服務器：

# 示例：從網頁中提取內容
gemini "使用 markdown-mcp 工具從 https://example.com 提取內容"

或者你可以直接使用該工具：

# 如果該工具作為命令公開
gemini get_page_markdown "https://example.com"

步驟 5：完整示例 - 提取並保存 Markdown

以下是一個完整的示例，它從網頁中提取 Markdown 內容並保存到文件中：

# 從網頁中提取內容並保存到 result.md
gemini "使用 get_page_markdown 從 https://www.confluent.io/blog/event-driven-flink-agents-enterprise-ai/ 提取內容，並將響應保存為 result.md"

此命令將：

1. 使用 get_page_markdown 工具從 Confluent 博客文章中提取簡潔的 Markdown 內容。
2. 將提取的 Markdown 內容保存到當前目錄下名為 result.md 的文件中。
3. 為你提供網頁內容的簡潔、易讀的 Markdown 版本。

其他示例：

# 從文檔中提取內容並使用自定義文件名保存
gemini "使用 get_page_markdown 從 https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html 提取內容，並保存為 flink-docs.md"

# 從 GitHub 倉庫的 README 中提取內容
gemini "使用 get_page_markdown 從 https://github.com/microsoft/vscode 提取內容，並保存為 vscode-readme.md"

# 使用特定選項提取內容
gemini "使用 get_page_markdown，設置 includeImages=false，從 https://example.com 提取內容，並保存為 clean-content.md"

Gemini CLI 故障排除

如果 MCP 服務器在 Gemini CLI 中無法正常工作：

1. 檢查文件路徑：確保 markdown-mcp-gemini.js 的路徑正確且為絕對路徑。
2. 驗證 Node.js：確保可以從命令行訪問 Node.js。
3. 檢查權限：確保腳本具有執行權限（chmod +x markdown-mcp-gemini.js）。
4. 手動測試服務器：運行 node markdown-mcp-gemini.js 檢查是否有錯誤。
5. 檢查 Gemini CLI 日誌：在 Gemini CLI 輸出中查找錯誤消息。

常見的 Gemini CLI 問題：

• 路徑未找到：添加 MCP 服務器時使用絕對路徑。
• 權限被拒絕：運行 chmod +x markdown-mcp-gemini.js 使腳本可執行。
• 未找到 Node.js：確保 Node.js 已安裝，並已添加到系統路徑中。
• 服務器無響應：使用 node markdown-mcp-gemini.js 檢查服務器是否正常啟動。

與多個 AI 客戶端一起使用

你可以同時將同一個 markdown-mcp 服務器與多個 AI 客戶端一起使用。該 MCP 服務器設計為能夠高效處理多個併發請求。

多客戶端設置的優勢

• 靈活性：在不同的 AI 模型中使用相同的工具。
• 效率：在多個客戶端之間共享同一個服務器實例。
• 一致性：無論使用哪個 AI 客戶端，都能獲得相同的提取質量。
• 資源優化：無需運行多個服務器實例。

多客戶端設置步驟

1. 使用 markdown-mcp.js 設置 Claude Desktop（如上述說明）。
2. 使用 markdown-mcp-gemini.js 設置 Gemini CLI（如上述說明）。
3. 兩個客戶端可以使用各自的服務器文件 - 針對每個客戶端進行了優化。

使用示例

與 Claude Desktop 一起使用：

使用 markdown-mcp 從 https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html 提取內容

與 Gemini CLI 一起使用：

# 提取並保存到文件
gemini "使用 get_page_markdown 從 https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html 提取內容，並保存為 result.md"

# 或者僅提取不保存
gemini "使用 get_page_markdown 從 https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html 提取內容"

性能考慮

• 服務器能夠高效處理多個併發請求。
• 每個請求使用一個全新的瀏覽器上下文以確保安全性。
• 內存使用量隨併發請求數量的增加而增加。
• 典型響應時間：每個請求 5 - 15 秒。

🔧 技術細節

測試

服務器已經過測試，並驗證了在各種網站上的正常工作，包括：

• ✅ 文檔網站（Confluent、GitHub 等）
• ✅ 新聞文章和博客文章
• ✅ 包含代碼示例的技術文檔
• ✅ 電子商務頁面和產品描述
• ✅ JavaScript 豐富的網站和動態內容

測試功能

• ✅ 提取標題、段落和文本內容。
• ✅ 保留粗體和斜體格式。
• ✅ 處理代碼塊和內聯代碼。
• ✅ 處理列表（有序和無序列表）。
• ✅ 提取格式正確的表格。
• ✅ 過濾掉導航欄和頁腳內容。
• ✅ 處理圖片和鏈接（啟用時）。
• ✅ 響應 MCP 協議請求。
• ✅ 處理動態內容和 JavaScript 豐富的網站。

手動測試

你可以通過運行以下命令手動測試服務器：

# 使用簡單的 URL 進行測試
node -e "
const { spawn } = require('child_process');
const server = spawn('node', ['markdown-mcp.js'], { stdio: ['pipe', 'pipe', 'pipe'] });
const request = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'get_page_markdown',
    arguments: { url: 'https://example.com' }
  }
};
server.stdin.write(JSON.stringify(request) + '\n');
setTimeout(() => {
  server.kill();
  console.log('測試完成');
}, 10000);
"

支持的網站

此 MCP 服務器在以下類型的網站上表現良好：

• 文檔網站：Confluent、GitHub、GitLab 等。
• 新聞和博客：大多數主要的新聞網站和博客。
• 技術內容：Stack Overflow、Medium、Dev.to。
• 電子商務：產品頁面和描述。
• 學術內容：研究論文和文章。
• 社交媒體：Twitter 線程、LinkedIn 文章。

性能

• 典型提取時間：根據頁面複雜度，通常為 5 - 15 秒。
• 內存使用量：每次提取約 50 - 100MB。
• 支持的內容大小：最多可達幾 MB 的文本內容。
• 併發請求：能夠高效處理多個請求。

要求

• Node.js：版本 18 或更高。
• Playwright：Chromium 瀏覽器（自動安裝）。
• 內存：至少 512MB 可用 RAM。
• 磁盤空間：Playwright 瀏覽器約需 200MB。

安全考慮

• 服務器以無頭模式運行，以確保安全性。
• 不存儲任何 cookie 或持久數據。
• 每個請求使用一個全新的瀏覽器上下文。
• 網絡請求受超時設置限制。
• 不記錄或存儲任何敏感數據。

🤝 貢獻代碼

1. 分叉倉庫。
2. 創建一個功能分支。
3. 進行更改。
4. 進行全面測試。
5. 提交拉取請求。

🆘 支持

如果你遇到問題：

1. 查看上述故障排除部分。
2. 驗證所有要求是否滿足。
3. 首先使用簡單的 URL 進行測試。
4. 檢查 Claude Desktop 日誌中的錯誤消息。
5. 打開一個包含詳細錯誤信息的問題。