Crawl4Claude

# 文档抓取器与 MCP 服务器 一个全面的、与领域无关的文档抓取和 AI 集成工具包。抓取任何文档网站，创建结构化数据库，并通过 MCP（模型上下文协议）与 Claude Desktop 集成，实现无缝的 AI 驱动文档辅助。 ## 🚀 特性 ### 核心功能 - **🌐 通用文档抓取器**：适用于任何文档网站 - **📊 结构化数据库**：具有全文搜索功能的 SQLite 数据库 - **🤖 MCP 服务器集成**：通过模型上下文协议与 Claude Desktop 原生集成 - **📝 LLM 优化输出**：为 AI 应用准备的上下文文件 - **⚙️ 配置驱动**：单个配置文件控制所有设置 ### 高级工具 - **🔍 查询接口**：用于搜索和分析抓取内容的命令行工具 - **🛠️ 调试套件**：全面的调试工具用于测试和验证 - **📋 自动配置**：自动生成 MCP 设置文件 - **📈 进度跟踪**：详细的日志记录和错误处理 - **💾 可恢复抓取**：智能缓存以应对中断的抓取 ## 📋 先决条件 - Python 3.8 或更高版本 - 互联网连接 - 每个文档网站约 500MB 的可用磁盘空间 ## 🛠️ 快速开始 ### 1. 安装 ```bash # 克隆代码库 git clone <repository-url> cd documentation-scraper # 安装依赖 pip install -r requirements.txt ``` ### 2. 配置目标 编辑 `config.py` 设置您的文档网站： ```python SCRAPER_CONFIG = { "base_url": "https://docs.example.com/", # 您的文档网站 "output_dir": "docs_db", "max_pages": 200, # ... 其他设置 } ``` ### 3. 运行抓取器 ```bash python docs_scraper.py ``` ### 4. 查询文档 ```bash # 搜索内容 python query_docs.py --search "tutorial" # 按章节浏览 python query_docs.py --section "getting-started" # 获取统计信息 python query_docs.py --stats ``` ### 5. 设置 Claude 集成 ```bash # 生成 MCP 配置文件 python utils/gen_mcp.py # 按照说明添加到 Claude Desktop ``` ## 🏗️ 项目结构 ``` 📁 documentation-scraper/ ├── 📄 config.py # 中央配置文件 ├── 🕷️ docs_scraper.py # 主抓取脚本 ├── 🔍 query_docs.py # 查询和分析工具 ├── 🤖 mcp_docs_server.py # 用于 Claude 集成的 MCP 服务器 ├── 📋 requirements.txt # Python 依赖 ├── 📁 utils/ # 调试和实用工具 │ ├── 🛠️ gen_mcp.py # 生成 MCP 配置文件 │ ├── 🧪 debug_scraper.py # 测试抓取器功能 │ ├── 🔧 debug_mcp_server.py # 调试 MCP 服务器 │ ├── 🎯 debug_mcp_client.py # 直接测试 MCP 工具 │ ├── 📡 debug_mcp_server_protocol.py # 通过 JSON-RPC 测试 MCP │ └── 🌐 debug_site_content.py # 调试内容提取 ├── 📁 docs_db/ # 生成的文档数据库 │ ├── 📊 documentation.db # SQLite 数据库 │ ├── 📄 documentation.json # JSON 导出 │ ├── 📋 scrape_summary.json # 统计信息 │ └── 📁 llm_context/ # LLM 准备的上下文文件 └── 📁 mcp/ # 生成的 MCP 配置 ├── 🔧 run_mcp_server.bat # Windows 启动脚本 └── ⚙️ claude_mcp_config.json # Claude Desktop 配置 ``` ## ⚙️ 配置 ### 主配置 (`config.py`) 整个系统由一个配置文件控制： ```python # 基本抓取设置 SCRAPER_CONFIG = { "base_url": "https://docs.example.com/", "output_dir": "docs_db", "max_depth": 3, "max_pages": 200, "delay_between_requests": 0.5, } # URL 过滤规则 URL_FILTER_CONFIG = { "skip_patterns": [r'/api/', r'\.pdf$'], "allowed_domains": ["docs.example.com"], } # MCP 服务器设置 MCP_CONFIG = { "server_name": "docs-server", "default_search_limit": 10, "max_search_limit": 50, } ``` ### 环境覆盖 您可以使用环境变量覆盖任何设置： ```bash export DOCS_DB_PATH="/custom/path/documentation.db" export DOCS_BASE_URL="https://different-docs.com/" python mcp_docs_server.py ``` ## 🤖 Claude Desktop 集成 ### 自动设置 1. **生成配置文件**： ```bash python utils/gen_mcp.py ``` 2. **将生成的配置复制到 Claude Desktop**： - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` 3. **重启 Claude Desktop** ### 手动设置 如果您更喜欢手动设置，请将以下内容添加到您的 Claude Desktop 配置中： ```json { "mcpServers": { "docs": { "command": "python", "args": ["path/to/mcp_docs_server.py"], "cwd": "path/to/project", "env": { "DOCS_DB_PATH": "path/to/docs_db/documentation.db" } } } } ``` ### 可用的 MCP 工具 连接后，Claude 可以使用以下工具： - **🔍 search_documentation**: 在所有文档中搜索内容 - **📚 get_documentation_sections**: 列出所有可用章节 - **📄 get_page_content**: 获取特定页面的完整内容 - **🗂️ browse_section**: 浏览章节内的页面 - **📊 get_documentation_stats**: 获取数据库统计信息 ## 🔧 命令行工具 ### 文档抓取器 ```bash # 基本抓取 python docs_scraper.py # 覆盖配置设置 python docs_scraper.py # 使用 config.py 中的设置 ``` ### 查询工具 ```bash # 搜索内容 python query_docs.py --search "authentication guide" # 浏览特定章节 python query_docs.py --section "api-reference" # 获取数据库统计信息 python query_docs.py --stats # 列出所有章节 python query_docs.py --list-sections # 导出章节到文件 python query_docs.py --export-section "tutorials" --format markdown > tutorials.md # 使用自定义数据库 python query_docs.py --db "custom/path/docs.db" --search "example" ``` ### 调试工具 ```bash # 测试抓取器功能 python utils/debug_scraper.py # 测试 MCP 服务器 python utils/debug_mcp_server.py # 直接测试 MCP 工具 python utils/debug_mcp_client.py # 测试 MCP 协议 python utils/debug_mcp_server_protocol.py # 调试内容提取 python utils/debug_site_content.py # 生成 MCP 配置文件 python utils/gen_mcp.py ``` ## 📊 数据库模式 ### 页面表 ```sql CREATE TABLE pages ( id INTEGER PRIMARY KEY, url TEXT UNIQUE NOT NULL, title TEXT, content TEXT, markdown TEXT, word_count INTEGER, section TEXT, subsection TEXT, scraped_at TIMESTAMP, metadata TEXT ); ``` ### 全文搜索 ```sql -- 使用 FTS5 搜索 SELECT * FROM pages_fts WHERE pages_fts MATCH 'your search term'; -- 或使用查询工具 python query_docs.py --search "your search term" ``` ## 🎯 示例用例 ### 1. 文档分析 ```bash # 获取文档概览 python query_docs.py --stats # 查找所有教程内容 python query_docs.py --search "tutorial guide example" # 导出特定章节 python query_docs.py --export-section "getting-started" > onboarding.md ``` ### 2. 与 Claude 的 AI 集成 ```python # 一旦 MCP 设置完成，询问 Claude： # "搜索文档中的认证示例" # "文档中有哪些章节可用？" # "给我显示 API 参考页面的内容" ``` ### 3. 自定义应用 ```python import sqlite3 # 连接到您的抓取文档 conn = sqlite3.connect('docs_db/documentation.db') # 查询特定内容 results = conn.execute(""" SELECT title, url, markdown FROM pages WHERE section = 'tutorials' AND word_count > 500 ORDER BY word_count DESC """).fetchall() # 在结构化数据上构建您自己的工具 ``` ## 🔍 调试和测试 ### 在全面运行之前测试抓取器 ```bash python utils/debug_scraper.py ``` ### 验证内容提取 ```bash python utils/debug_site_content.py ``` ### 测试 MCP 集成 ```bash # 测试服务器功能 python utils/debug_mcp_server.py # 直接测试工具 python utils/debug_mcp_client.py # 测试 JSON-RPC 协议 python utils/debug_mcp_server_protocol.py ``` ## 📈 性能和优化 ### 抓取性能 - **从小开始**：使用 `max_pages=50` 进行测试 - **调整深度**：`max_depth=2` 高效覆盖大部分内容 - **速率限制**：如果被阻止，增加 `delay_between_requests` - **缓存**：默认启用以支持可恢复抓取 ### 数据库性能 - **全文搜索**：自动 FTS5 索引以快速搜索 - **索引**：对 URL 和章节列进行优化索引 - **字数统计**：预计算以快速获取统计信息 ### MCP 性能 - **可配置限制**：设置适当的搜索和章节限制 - **片段长度**：调整片段大小以优化响应时间 - **连接池**：高效的数据库连接 ## 🌐 支持的文档网站 该抓取器适用于大多数文档网站，包括： - **静态网站**：Hugo、Jekyll、MkDocs、Docusaurus - **文档平台**：GitBook、Notion、Confluence - **API 文档**：Swagger/OpenAPI 文档 - **维基风格**：MediaWiki、TiddlyWiki - **自定义网站**：任何具有一致 HTML 结构的网站 ### 网站特定配置 为您的目标网站自定义 URL 过滤和内容提取： ```python URL_FILTER_CONFIG = { "skip_patterns": [ r'/api/', # 跳过 API 端点文档 r'/edit/', # 跳过编辑页面 r'\.pdf$', # 跳过 PDF 文件 ], "allowed_domains": ["docs.yoursite.com"], } CONTENT_FILTER_CONFIG = { "remove_patterns": [ r'Edit this page.*?\n', # 移除编辑链接 r'Was this helpful\?.*?\n', # 移除反馈部分 ], } ``` ## 🤝 贡献 我们欢迎贡献！以下是您可以帮助的领域： - **新的导出格式**：PDF、EPUB、Word 文档 - **增强的内容过滤**：更好的噪声去除 - **额外的调试工具**：更全面的测试 - **文档**：改善指南和示例 - **性能优化**：更快的抓取和查询 ## ⚠️ 负责任的使用 - **尊重 robots.txt**：检查目标网站的 robots.txt 文件 - **速率限制**：在请求之间使用适当的延迟 - **服务条款**：遵守文档网站的条款 - **合理使用**：用于教育、研究或个人目的 - **归属**：注明原始文档来源 ## 📄 许可证 该项目按原样提供，仅用于教育和研究目的。请遵守您抓取的文档网站的服务条款和许可协议。 --- ## 🎉 入门示例 ### 示例 1：抓取 Python 文档 ```python # config.py SCRAPER_CONFIG = { "base_url": "https://docs.python.org/3/", "max_pages": 500, "max_depth": 3, } ``` ### 示例 2：抓取 API 文档 ```python # config.py SCRAPER_CONFIG = { "base_url": "https://api-docs.example.com/", "max_pages": 200, } URL_FILTER_CONFIG = { "skip_patterns": [r'/changelog/', r'/releases/'], } ``` ### 示例 3：企业文档 ```python # config.py SCRAPER_CONFIG = { "base_url": "https://internal-docs.company.com/", "output_dir": "company_docs", } MCP_CONFIG = { "server_name": "company-docs-server", "docs_display_name": "公司内部文档", } ``` --- **祝您文档愉快！ 📚✨** 如有问题、意见或功能请求，请先检查调试日志，然后创建一个包含相关细节的问题。 --- ## 🙏 归属 该项目由 **[Crawl4AI](https://github.com/unclecode/crawl4ai)** 提供支持 - 一个出色的开源 LLM 友好的网络爬虫和抓取工具。 <a href="https://github.com/unclecode/crawl4ai"> <img src="https://img.shields.io/badge/Powered%20by-Crawl4AI-blue?style=flat-square" alt="Powered by Crawl4AI"/> </a> Crawl4AI 使得实现智能网络抓取的能力成为可能，从而使这个文档工具包得以实现。非常感谢 [@unclecode](https://github.com/unclecode) 和 Crawl4AI 社区构建如此出色的工具！ 🚀 **查看 Crawl4AI：** - **代码库**： https://github.com/unclecode/crawl4ai - **文档**： https://crawl4ai.com - **Discord 社区**： https://discord.gg/jP8KfhDhyN ## 📄 许可证