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. 打开一个包含详细错误信息的问题。