项目介绍
<div align="center">
<picture>
<img alt="Doctor Logo" src="doctor.png" height="30%" width="30%">
</picture>
<br>
<h2>🩺 Doctor</h2>
一个用于发现、爬取和索引网站的工具，将其作为MCP服务器暴露给LLM代理，以实现更准确和及时的推理和代码生成。
</div>🔍 概述
Doctor 提供了一整套解决方案：
- 使用crawl4ai进行网页爬取，并跟踪层次结构
- 使用LangChain对文本进行分块
- 使用litellm通过OpenAI创建嵌入
- 在支持向量搜索的DuckDB中存储数据
- 通过FastAPI网络服务提供搜索功能
- 通过MCP服务器使这些能力可供LLM使用
- 使用分层站点地图浏览爬取的站点
🏗️ 核心基础设施
🗄️ DuckDB
- 存储文档数据和嵌入的数据库，具有向量搜索功能
- 由统一的Database类管理
📨 Redis
- 异步任务处理的消息代理
🕸️ 爬虫工作器
- 处理爬取任务
- 对文本进行分块
- 创建嵌入
🌐 网络服务器
- FastAPI服务，公开端点
- 获取、搜索和查看数据
- 公开MCP服务器
💻 安装
⚙️ 预备条件
- Docker 和 Docker Compose
- Python 3.10+
- uv（Python 包管理器）
- OpenAI API 密钥
📦 安装步骤
- 克隆此仓库
- 设置环境变量：
export OPENAI_API_KEY=your-openai-key - 运行堆栈：
docker compose up
👁 使用方法
- 访问 http://localhost:9111/docs 查看OpenAPI文档
- 查找
/fetch_url端点并提供URL开始爬取任务 - 使用
/job_progress查看当前任务状态 - 配置编辑器以使用
http://localhost:9111/mcp作为MCP服务器
☁️ 网络API
核心端点
POST /fetch_url: 开始爬取URLGET /search_docs: 搜索已索引的文档GET /job_progress: 检查爬取任务进度GET /list_doc_pages: 列出已索引的页面GET /get_doc_page: 获取页面的全文
站点地图功能
地图功能提供了爬取网站的分层视图，便于导航和探索已索引站点的结构。
端点：
GET /map: 查看所有爬取站点的索引GET /map/site/{root_page_id}: 查看特定站点的分层树结构GET /map/page/{page_id}: 查看特定页面及其导航（父级、同级、子级）GET /map/page/{page_id}/raw: 获取页面的原始Markdown内容
特性：
- 分层导航：页面维护父子关系，允许您在站点结构中导航
- 域分组：来自同一域的单独爬取页面自动分组在一起
- 自动标题提取：从HTML或Markdown内容中提取页面标题
- 面包屑导航：通过显示从根到当前页面路径的面包屑轻松导航
- 同级导航：快速访问层次结构中同一级别的页面
- 旧版页面支持：在层次结构跟踪之前爬取的页面按域分组，便于访问
- 无需JavaScript：所有导航仅使用纯HTML和CSS，以确保最大兼容性
使用示例：
- 使用
/fetch_url端点爬取一个网站 - 访问
/map查看所有爬取的站点 - 点击一个站点查看其分层结构
- 使用提供的链接浏览页面
🔧 MCP集成
确保您的Docker Compose堆栈正在运行，然后在Cursor或VSCode MCP服务器配置中添加：
"doctor": {
"type": "sse",
"url": "http://localhost:9111/mcp"
}
🧪 测试
运行测试
要运行所有测试：
# 运行所有测试并生成覆盖率报告
pytest
要运行特定测试类别：
# 只运行单元测试
pytest -m unit
# 只运行异步测试
pytest -m async_test
# 运行特定组件的测试
pytest tests/lib/test_crawler.py
测试覆盖率
项目配置为自动生成覆盖率报告：
# 运行测试并生成详细的覆盖率报告
pytest --cov=src --cov-report=term-missing
测试结构
tests/conftest.py: 所有测试的通用fixturetests/lib/: 库组件的测试test_crawler.py: 爬虫模块的测试test_crawler_enhanced.py: 带层次跟踪的增强型爬虫的测试test_chunker.py: 分块模块的测试test_embedder.py: 嵌入模块的测试test_database.py: 统一的Database类的测试test_database_hierarchy.py: 数据库层次操作的测试
tests/common/: 公共模块的测试tests/services/: 服务层的测试test_map_service.py: 地图服务的测试
tests/api/: API端点的测试test_map_api.py: 地图API端点的测试
tests/integration/: 集成测试test_processor_enhanced.py: 带层次跟踪的增强型处理器的测试
🐞 代码质量
提交前钩子
项目配置了提交前钩子，在每次提交前自动运行：
ruff check --fix: 检查代码并自动修复问题ruff format: 根据项目风格格式化代码- 移除尾随空格
- 修正文件末尾
- YAML验证
- 大文件检查
设置提交前钩子
要设置提交前钩子：
# 安装pre-commit
uv pip install pre-commit
# 安装git钩子
pre-commit install
手动运行提交前钩子
您可以手动在所有文件上运行提交前钩子：
# 运行所有提交前钩子
pre-commit run --all-files
或者只在暂存文件上运行：
# 在暂存文件上运行
pre-commit run
⚖️ 许可证
本项目采用MIT许可证 - 详情见LICENSE.md文件。