LLM 문서 스크래퍼 (doc-scraper)

A configurable, concurrent, and resumable web crawler written in Go. 기술 문서를 스크랩하고 핵심 콘텐츠를 추출하며, 이를 대규모 언어 모델(LLMs)이 수집하기에 적합한 깨끗한 Markdown 형식으로 변환하여 로컬에 저장하도록 특별히 설계되었습니다.

doc-scraper는 문서 사이트를 깔끔한 Markdown으로 크롤링하고 MCP를 통해 코딩 에이전트에게 제공합니다. 사용자의 에이전트는 학습 데이터나 실시간 웹 검색을 추측하는 대신, 사용자가 선택한 문서를 오프라인에서 검색하고 읽습니다. doc-scraper add 명령어를 사용하여 어떤 문서 페이지에든 지정하면 프레임워크를 감지(Docusaurus, Starlight, Sphinx, VitePress, Material for MkDocs, mdBook 등 30개 이상의 문서 생성기 포함), 콘텐츠 셀렉터를 검증하고 설정을 초안 작성해줍니다.

문서: https://sriram-pr.github.io/doc-scraper/

기능 (Features)

• 에이전트를 위한 오프라인 검색: 저장된 코퍼스(corpus)를 대상으로 하는 BM25 전체 텍스트 검색(search_docs) 및 페이지 읽기(read_page) 기능을 네트워크 접근 없이 제공합니다.
• 프레임워크 감지 (Framework detection): 30개 이상의 문서 생성기를 인식하며, 각 셀렉터를 페이지에서 검증하고, Readability 폴백(fallback)을 지원하며, 크롤링된 빈 내용 대신 JavaScript 전용 셸을 보고합니다.
• 깨끗한 출력 (Clean output): 프론트매터가 포함된 GitHub-Flavored Markdown 형식의 페이지별 결과와 더불어 pages.jsonl, llms.txt, llms-full.txt 파일을 제공합니다.
• 정중하고 재개 가능 (Polite and resumable): robots.txt 및 sitemaps 지원, 호스트별 속도 제한(rate limits), 백오프를 사용한 재시도(retries with backoff), 재개 가능한 크롤링, 그리고 마지막 정상 복사본을 덮어쓰지 않는 단계적 출력(staged output) 기능을 갖추고 있습니다.
• 최신 상태 유지 (Stays fresh): 증분 재크롤링(incremental re-crawls), 워치 모드(watch mode), 크롤링 기록(get_freshness, diff_crawl)을 지원합니다.
• 동시 다수 사이트 처리: 공유 제한(shared limits)과 함께 병렬 크롤링을 수행할 수 있습니다.

설치 (Install)

릴리스 바이너리(Linux, macOS, Windows; amd64 및 arm64)를 Releases 페이지에서 다운로드하거나 다음을 사용하세요:

go install github.com/Sriram-PR/doc-scraper/v2/cmd/doc-scraper@latest

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD":/data ghcr.io/sriram-pr/doc-scraper:latest crawl -site rust_cli_book

Claude Desktop 사용자는 최신 릴리스에서 doc-scraper.mcpb를 설치할 수 있습니다. 자세한 내용은 설치를 참조하세요.

빠른 시작 (Quick start)

doc-scraper add -site rust_cli_book https://rust-cli.github.io/book/index.html   # 감지, 미리 보기, 확인
doc-scraper crawl -site rust_cli_book             # 마크다운 파일이 ./crawled_docs/rust_cli_book/에 저장됩니다.
doc-scraper search -site rust_cli_book "error handling"

그런 다음 Claude Code에서 사용하세요:

claude mcp add --transport stdio doc-scraper -- /path/to/doc-scraper mcp-server -config /path/to/config.yaml

범위(scopes) 및 첫 번째 프롬프트는 Claude Code 설정을 참조하세요.

문서 (Docs)

• 시작하기 (Getting started): 설치, 빠른 시작, 사이트 추가 방법
• 에이전트와 함께 사용하기 (MCP): Claude Code, Claude Desktop, 모든 stdio 클라이언트 및 11가지 도구
• 문서 프레임워크 (Docs frameworks): 감지 작동 방식, Docusaurus, Starlight, Sphinx, VitePress, Material for MkDocs, mdBook에 대한 가이드 포함
• 구성(Configuration) 및 CLI 참고 자료
• 감지 벤치마크 (Detection benchmark)

기여 (Contributing)

기여를 환영합니다. 시작하기 전에 CONTRIBUTING.md 파일을 읽어보세요: 이 파일에는 설정 방법, CI가 강제하는 테스트 규칙, 이슈를 할당받는 방법, 그리고 AI 지원 기여에 대한 정책이 포함되어 있습니다. good first issue 레이블이 붙은 이슈들은 시작하기 좋은 곳입니다.

보안 문제를 발견했다면 SECURITY.md에 설명된 대로 비공개로 보고해 주세요. 참여하는 모든 사람은 Code of Conduct를 따릅니다.

개인정보 보호정책 (Privacy Policy)

doc-scraper는 아무것도 수집하지 않습니다: 텔레메트리(telemetry), 분석 데이터(analytics), 계정 정보가 없습니다. 모든 출력과 상태는 사용자의 장치에 남아 있으며, 네트워크 요청은 사용자가 명시적으로 요청한 크롤링 및 가져오기 작업만 수행합니다. 전체 정책은 PRIVACY.md를 참고하세요.

라이선스 (License)

이 프로젝트는 Apache-2.0 License에 따라 라이선스가 부여되었습니다.

감사의 말 (Acknowledgements)

• HTML 파싱을 위한 GoQuery
• 변환을 위한 html-to-markdown
• 상태 지속성(state persistence)을 위한 BadgerDB
• MCP 서버 구현을 위한 mcp-go
• 콘텐츠 추출 폴백(fallback)을 위한 go-readability
• 순수 Go로 작성된 크롤링 기록 인덱스를 위한 modernc.org/sqlite
• robots.txt 파싱을 위한 robotstxt
• 설정 파싱을 위한 yaml.v3
• 크롤링 작업 ID를 위한 google/uuid
• 동시성을 제한하는 가중치 세마포어(weighted semaphores)를 위한 x/sync