网站转Markdown服务

一个强大的模型上下文协议(MCP)服务器,用于抓取网站内容并将其转换为Markdown格式,便于AI理解和处理网站信息。

  • by SunZhi-Will
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 SunZhi-Will/website-to-markdown-mcp

使用说明

🌐 网站到Markdown MCP服务器

语言: 英语 | 繁体中文

一个强大的模型上下文协议(MCP)服务器,用于获取网站内容并将其转换为Markdown格式,使人工智能更容易理解和处理网站信息。

✨ 主要特点

🌟 增强处理 📊 OpenAPI支持 ⚙️ 智能分析 🎯 高级提取
AI驱动的内容清理 OpenAPI 3.x/Swagger 2.0 读取时间计算 主要内容检测
自动广告删除 专业验证 字数统计 语言检测
内容摘要 结构化API解析 智能重试机制 多格式支持

🆕 v1.2.0的新增功能

🚀 主要增强功能

功能 状态 描述
🧠 增强型内容处理器 ✅ AI驱动的内容清理和提取
📊 智能分析 ✅ 字数、阅读时间、内容摘要
🌍 语言检测 ✅ 自动语言识别
🎯 智能重试 ✅ 具有指数回退的智能重试机制
🔍 隐形浏览器 ✅ 防检测浏览功能
⚡ 速率限制 ✅ 内置速率限制和并发控制
🧹 内容清理 ✅ 删除广告、导航和无关内容
📝 增强的Markdown ✅ 支持删除线、下划线、高亮显示

🚀 快速开始

🎯 方法1:NPX安装(🌟 推荐)

💡 最简单的方法:无需本地安装!

步骤1:创建配置文件📄

创建一个 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"
    }
  ]
}

步骤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:重新启动和测试🔄

  1. 重新启动游标
  2. 打开聊天并使用代理模式
  3. 测试命令: Please list all configured websites

🎉 完成!无需安装!


🎯 方法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输出

# 🚀 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...]

🆕 完整的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 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"
    }
  ]
}

📦 安装和设置

🛠️ 系统要求

  • Node.js 20.18.1+(推荐版本:v22.15.0 LTS)
  • npm 10.0.0+或 纱线
  • 光标 编辑

⚠️ 重要:某些依赖项需要Node.js v20.18.1或更高版本。如果遇到引擎兼容性警告,请更新您的Node.js版本。

⚡ NPM包安装

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

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

🔧 开发设置

# 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

🎛️ 高级配置选项

配置优先级顺序

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]

🎨 配置方法详细信息

📋 方法1:外部配置文件(🌟 推荐)

💡 优势:易于编辑,语法突出显示,版本控制友好

🔧 Detailed Setup Steps
  1. 创建配置文件

    # Can be placed anywhere
    touch my-api-configs.json
    
  2. 编辑配置内容

    {
      "websites": [
        {
          "name": "my_docs",
          "url": "https://docs.example.com",
          "description": "📚 My Documentation Website"
        }
      ]
    }
    
  3. 设置环境变量

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

📋 方法2:嵌入式JSON(向后兼容)

🔧 Configuration Example
{
  "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\"}]}"
      }
    }
  }
}

📋 方法3:本地config.json

🔧 Local Configuration

直接编辑 config.json 在项目根目录中:

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

🔧 可用工具

🌐 通用工具

工具名称 功能 参数 示例
fetch_website 获取任何网站 url:网站URL 获取OpenAPI规范文件
list_configured_websites 列出已配置的网站 无 查看所有可用网站

🎯 专用工具

每个配置的网站都会自动生成相应的专用工具:

  • fetch_petstore_openapi -获取宠物商店OpenAPI 3.0规范
  • fetch_petstore_swagger -获取宠物商店Swagger 2.0规范
  • fetch_github_api -获取GitHub API规范
  • fetch_tailwind_css -获取Tailwind CSS文档

📊 增强输出格式示例

🌐 带分析功能的一般网站内容

# 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...]

📋 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

🎯 使用示例

💻 基本用法

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

🔍 OpenAPI规范获取

Please use the fetch_petstore_openapi tool to fetch Petstore OpenAPI specification

📚 文档网站获取

Please fetch React official documentation content

🚨 故障排除

📋 完整的故障排除指南:参见 故障排除.md 了解常见问题的详细解决方案。

❓ 快速解决方案

🔧 Node.js Version Issues

错误: npm WARN EBADENGINE Unsupported engine

  • 解决方案:将Node.js更新到v20.18.1或更高版本
  • 下载: Node.js官方网站
  • 验证: node --version
🌐 Module Not Found Issues

错误: Cannot find module './db.json'

  • 解决方案1:清除npm缓存: npm cache clean --force
  • 解决方案2:更新Node.js版本
  • 解决方案3:使用本地安装而不是npx
⚙️ Configuration Issues

Q: 配置更改未生效?

  • ✅ 确认JSON格式正确
  • ✅ 重新启动游标
  • ✅ 检查环境变量名称

Q: JSON格式错误?

  • 🛠️ 使用 JSON验证器
  • 🛠️ 使用双引号确认
  • 🛠️ 检查是否有多余的逗号

🔍 调试模式

详细的日志在启动时输出到stderr:

# View debug messages
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驱动的清理功能增强内容处理
  • ✨ 添加 智能分析:字数统计、阅读时间、内容摘要
  • ✨ 添加 语言检测和多语言支持
  • ✨ 添加 隐形浏览器反检测功能
  • ✨ 添加 内置的速率限制和重试机制
  • ✨ 添加 高级内容过滤和广告删除
  • 🔧 增强 支持更多HTML元素的Markdown处理
  • 📊 改进的 具有丰富元数据的输出格式
  • 🎯 固定的 各种技术问题和依赖关系

🎯 v1.1.0(上一个)

🚀 主要功能更新

  • ✨ 添加 完全支持OpenAPI 3.x/Swagger 2.0
  • ✨ 添加 JSON/YAML格式自动检测
  • ✨ 添加 专业级规格验证和参考解决方案
  • ✨ 添加 版本自适应机制
  • ✨ 添加 结构化API文档摘要
  • 🔧 预配置 多个OpenAPI/Swagger示例
  • 📦 添加 支持npx的NPM包分发
  • 🎯 增强 更好的用户体验的安装方法

🎯 v1.0.0(稳定版)

  • 🎉 初始版本
  • 🌐 基本功能 网站内容获取
  • 📝 核心功能 Markdown转换
  • ⚙️ 配置支持 多网站管理

🤝 贡献

💡 如何做出贡献

  1. 🍴 分叉 这个项目
  2. 🌟 创建 特征分支(git checkout -b feature/AmazingFeature)
  3. 📝 提交 变化(git commit -m 'Add some AmazingFeature')
  4. 📤 推 分支机构(git push origin feature/AmazingFeature)
  5. 🔄 打开 拉取请求

🐛 问题报告

关于 问题 页面,请包括:

  • 🔍 问题描述
  • 🔄 繁殖步骤
  • 💻 环境信息
  • 📸 屏幕截图或日志

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。


🌟 如果这个项目对你有帮助,请给它一颗星!

💬 有问题或建议吗?欢迎打开一个问题!


由Sun制造 ❤️ 开发者社区