crawl-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

开发命令

# 安装依赖
uv sync

# 运行测试（所有测试）
uv run pytest

# 运行特定测试文件
uv run pytest tests/unit/test_crawler_v2.py

# 运行特定测试类/函数
uv run pytest tests/unit/test_unified_crawl.py::TestUnifiedCrawlSingleFallback::test_fast_path_returns_markdown_format

# 带覆盖率报告的测试
uv run pytest -v --cov=src/crawl4ai_mcp --cov-report=term-missing

# 代码检查和格式化
uv run ruff check .
uv run ruff format .

# 运行 MCP 服务器（开发调试，HTTP 模式）
uv run python -m crawl4ai_mcp.fastmcp_server --http

# 运行 MCP 服务器（生产模式，STDIO）
uv run crawl-mcp

项目架构

核心设计：自动降级爬取 + 可选 LLM 插件

本项目定位为专业网页爬取工具，内置「快速提取 → 浏览器渲染」自动降级策略：

1. 阶段 0：快速提取（~0.3-0.6s）— 基于 ddgs.extract()，适用于静态页面
2. 阶段 1：浏览器降级（~15-23s）— 快速提取失败或内容不足时自动切换到 Playwright
3. 阶段 2：可选 LLM 插件 — 仅当提供 llm_config 且配置了 CRAWL_MCP_API_KEY 时执行

设计原则：不配置 API Key 时，工具完全作为纯爬取工具使用，零依赖外部 LLM 服务。 用户拿到 Markdown 后可自行调用任何 LLM 处理。静态页享受 0.5s 速度，SPA 自动降级到浏览器。

模块职责

模块	职责	关键类/函数
crawler.py	网页爬取核心（自动降级：快速提取→浏览器）	Crawler.crawl_single(), Crawler.crawl_batch()
searcher.py	搜索 + 内部快速提取（ddgs.extract，不作为 MCP 工具暴露）	Searcher.search_text(), Searcher.extract_url()
llm_config.py	LLM 配置管理	get_default_llm_config(), LLMConfig
fastmcp_server.py	MCP 服务器入口，注册所有工具	@mcp.tool 装饰器

异步处理模式

关键设计决策：使用 nest_asyncio 实现嵌套事件循环兼容

• _run_async() 辅助函数（在 utils.py 中统一提供）封装了异步调用
• 允许在已有事件循环的环境（如 Jupyter、某些测试框架）中运行
• 底层爬取使用 AsyncWebCrawler.arun() 和 arun_many()
• 快速提取路径（ddgs.extract）通过 ThreadPoolExecutor 并行化

并发控制

• 快速提取并发：crawl_batch Phase 1 使用 ThreadPoolExecutor 并行内部 Searcher.extract_url
• 浏览器爬取并发：Phase 2 使用 SemaphoreDispatcher（concurrent 参数）
• LLM 并发：批量 LLM 处理使用 concurrent.futures.ThreadPoolExecutor（llm_concurrent 参数）
• 图片分析并发：search_images 使用 asyncio.Semaphore（analyze_concurrent 参数）

LLM 配置格式（实验性功能）

llm_config 参数支持三种格式：

1. 字典：{"instruction": "提取产品信息", "schema": {...}}
2. JSON 字符串：'{"instruction": "总结"}'
3. 纯文本："总结页面内容"（自动作为 instruction）