문서 크롤러 및 MCP 서버
이 프로젝트는 웹사이트를 크롤링하고, 마크다운 문서를 생성하고, 커서와 같은 도구와 통합되도록 설계된 MCP(Model Context Protocol) 서버를 통해 해당 문서를 검색할 수 있는 도구 세트를 제공합니다.
특징
웹 크롤러( :
crawl4ai사용하여 주어진 URL에서 웹사이트를 크롤링합니다.구성 가능한 크롤링 깊이, URL 패턴(포함/제외), 콘텐츠 유형 등
Markdown으로 변환하기 전에 HTML을 선택적으로 정리합니다(탐색 링크, 헤더, 푸터 제거).
크롤링된 콘텐츠로부터 단일의 통합된 마크다운 파일을 생성합니다.
기본적으로 출력을
./storage/에 저장합니다.
MCP 서버( :
./storage/디렉토리에서 Markdown 파일을 로드합니다.제목을 기준으로 마크다운을 의미적 부분으로 구문 분석합니다.
sentence-transformers(multi-qa-mpnet-base-dot-v1)를 사용하여 각 청크에 대한 벡터 임베딩을 생성합니다.캐싱: 처리된 청크와 임베딩을 저장하기 위해 캐시 파일(
storage/document_chunks_cache.pkl)을 활용합니다.첫 번째 실행: 새로운 문서를 크롤링한 후 서버를 처음 시작할 때는 모든 콘텐츠에 대한 구문 분석, 청크 분할, 임베딩 생성이 필요하므로 시간이 다소 걸릴 수 있습니다.
후속 실행: 캐시 파일이 존재하고
./storage/에 있는 소스.md파일의 수정 시간이 변경되지 않은 경우, 서버는 캐시에서 직접 로드하므로 시작 시간이 훨씬 빨라집니다.캐시 무효화: 캐시가 마지막으로 생성된 이후
./storage/에 있는.md파일이 수정, 추가 또는 제거되면 캐시가 자동으로 무효화되고 다시 생성됩니다.
Cursor와 같은 클라이언트를 위해
fastmcp통해 MCP 도구를 공개합니다.list_documents: 크롤링 가능한 문서를 나열합니다.get_document_headings: 문서의 제목 구조를 검색합니다.search_documentation: 벡터 유사성을 사용하여 문서 청크에 대한 의미 검색을 수행합니다.
커서 통합 : 커서 내에서 사용하기 위해
stdio전송을 통해 MCP 서버를 실행하도록 설계되었습니다.
Related MCP server: WebSearch
워크플로
크롤링:
crawler_cli도구를 사용하여 웹사이트를 크롤링하고./storage/에.md파일을 생성합니다.서버 실행:
mcp_server구성하고 실행합니다(일반적으로 Cursor와 같은 MCP 클라이언트에서 관리).로드 및 임베드: 서버는
./storage/에 있는.md파일의 콘텐츠를 자동으로 로드, 청크 및 임베드합니다.쿼리: MCP 클라이언트(예: 커서 에이전트)를 사용하여 서버 도구(
list_documents,search_documentation등)와 상호 작용하여 크롤링된 콘텐츠를 쿼리합니다.
설정
이 프로젝트에서는 종속성 관리와 실행에 uv 사용합니다.
uv: UV 웹사이트 의 지침을 따르세요.저장소를 복제합니다.
지엑스피1
종속성 설치:
uv sync이 명령은 가상 환경(일반적으로
.venv)을 생성하고pyproject.toml에 나열된 모든 종속성을 설치합니다.
용법
1. 문서 크롤링
crawl.py 스크립트를 사용하거나 uv run 통해 직접 크롤러를 실행합니다.
기본 예:
이렇게 하면 기본 설정으로 https://docs.example.com 크롤링하고 출력을 ./storage/docs.example.com.md 에 저장합니다.
옵션이 있는 예:
모든 옵션 보기:
주요 옵션은 다음과 같습니다.
--output/-o: 출력 파일 경로를 지정합니다.--max-depth/-d: 크롤링 깊이를 설정합니다(1~5 사이여야 함).--include-pattern/--exclude-pattern: 크롤링할 URL을 필터링합니다.--keyword/-k: 크롤링 중 관련성 점수를 매기기 위한 키워드입니다.--remove-links/--keep-links: HTML 정리를 제어합니다.--cache-mode:crawl4ai캐싱을 제어합니다(DEFAULT,BYPASS,FORCE_REFRESH).--wait-for: 콘텐츠를 캡처하기 전에 특정 시간(초) 또는 CSS 선택기(예:5또는'css:.content')를 기다립니다. 로딩이 지연되는 페이지에 유용합니다.--js-code: 콘텐츠를 캡처하기 전에 페이지에서 사용자 정의 JavaScript를 실행합니다.--page-load-timeout: 페이지가 로드될 때까지 기다리는 최대 시간(초)을 설정합니다.--wait-for-js-render/--no-wait-for-js-render: JavaScript가 많이 사용되는 단일 페이지 애플리케이션(SPA)을 더 효율적으로 처리하기 위해 특정 스크립트를 활성화합니다. 스크롤 및 "더 보기" 버튼 클릭을 통해 특정 스크립트의 대기 시간을 자동으로 설정합니다.--wait-for이 지정되지 않으면 기본 대기 시간이 자동으로 설정됩니다.
패턴과 깊이를 활용한 크롤링 개선
때로는 문서 사이트의 특정 하위 섹션만 크롤링하고 싶을 수 있습니다. 이 경우 --include-pattern 및 --max-depth 옵션을 사용하여 시행착오를 거쳐야 할 수 있습니다.
--include-pattern: 크롤러가 주어진 패턴과 일치하는 URL을 가진 링크만 추적하도록 제한합니다. 유연성을 위해 와일드카드(*)를 사용하세요.--max-depth: 크롤러가 시작 URL에서 얼마나 멀리 떨어져 "클릭"할지 제어합니다. 깊이가 1이면 시작 URL에서 직접 링크된 페이지만 크롤링합니다. 깊이가 2이면 해당 페이지 와 해당 URL에서 링크된 페이지(include 패턴과 일치하는 경우)를 크롤링합니다.
예: Pulsar Admin API 섹션만 크롤링
https://pulsar.apache.org/docs/4.0.x/admin-api-* 에 있는 콘텐츠만 원한다고 가정해 보겠습니다.
시작 URL: 개요 페이지에서 시작할 수 있습니다:
https://pulsar.apache.org/docs/4.0.x/admin-api-overview/.패턴 포함:
admin-api포함하는 링크만 필요합니다:--include-pattern "*admin-api*".최대 깊이: 시작 페이지에서 관리자 API 링크가 몇 단계까지 연결되는지 파악해야 합니다.
2부터 시작하여 필요에 따라 늘려야 합니다.자세한 모드:
-v사용하여 어떤 URL이 방문되거나 건너뛰어지는지 확인하여 패턴과 심도를 디버깅하는 데 도움이 됩니다.
출력 파일(이 경우 기본적으로 ./storage/pulsar.apache.org.md )을 확인하세요. 페이지가 누락된 경우 --max-depth 3 으로 늘려 보세요. 관련 없는 페이지가 너무 많이 포함된 경우 --include-pattern 더 구체적으로 지정하거나 --exclude-pattern 규칙을 추가하세요.
2. MCP 서버 실행
MCP 서버는 커서(Cursor)와 같은 MCP 클라이언트에서 stdio 전송을 통해 실행되도록 설계되었습니다. 서버를 실행하는 명령은 다음과 같습니다.
하지만 Python이 mcp_server 모듈을 찾을 수 있도록 프로젝트의 루트 디렉토리( MCPDocSearch )에서 실행해야 합니다.
⚠️ 주의: 임베딩 시간
MCP 서버는 처음 실행될 때 또는 ./storage/ 의 소스 마크다운 파일이 변경될 때마다 로컬에서 임베딩을 생성합니다. 이 프로세스에는 머신 러닝 모델을 로드하고 모든 텍스트 청크를 처리하는 과정이 포함됩니다.
시간 변동: 임베딩 생성에 필요한 시간은 다음 사항에 따라 크게 달라질 수 있습니다.
하드웨어: 호환 GPU(CUDA 또는 Apple Silicon/MPS)를 탑재한 시스템은 CPU만 탑재한 시스템보다 훨씬 빠릅니다.
데이터 크기: 마크다운 파일의 총 수와 콘텐츠 길이는 처리 시간에 직접적인 영향을 미칩니다.
인내심을 가지세요. 문서 세트가 많거나 하드웨어 속도가 느린 경우, 초기 시작(또는 변경 후 시작)에 몇 분이 걸릴 수 있습니다. 이후 캐시를 사용하면 훨씬 빠르게 시작할 수 있습니다. ⏳
3. 데스크톱용 Cursor/Claude 구성
Cursor와 함께 이 서버를 사용하려면 이 프로젝트의 루트( MCPDocSearch/.cursor/mcp.json )에 다음 내용으로 .cursor/mcp.json 파일을 만드세요.
설명:
"doc-query-server": Cursor 내의 서버 이름입니다."command": "uv":uv명령 실행자로 지정합니다."args":"--directory", "/path/to/your/MCPDocSearch": 중요한 점은 명령을 실행하기 전에uv작업 디렉터리를 프로젝트 루트로 변경하도록 지시한다는 것입니다./path/to/your/MCPDocSearch"run", "python", "-m", "mcp_server.main":uv명령은 올바른 디렉토리 및 가상 환경에서 실행됩니다.
이 파일을 저장하고 Cursor를 다시 시작하면 "doc-query-server"가 Cursor의 MCP 설정에서 사용 가능해지고 에이전트에서도 사용할 수 있게 됩니다(예: @doc-query-server search documentation for "how to install" ).
Claude for Desktop의 경우 이 공식 문서를 사용하여 MCP 서버를 설정할 수 있습니다.
종속성
사용된 주요 라이브러리:
crawl4ai: 핵심 웹 크롤링 기능.fastmcp: MCP 서버 구현.sentence-transformers: 텍스트 임베딩을 생성합니다.torch:sentence-transformers에 필요함.typer: 크롤러 CLI를 빌드합니다.uv: 프로젝트 및 환경 관리.beautifulsoup4(crawl4ai통해): HTML 파싱.rich: 향상된 터미널 출력.
건축학
이 프로젝트는 다음과 같은 기본 흐름을 따릅니다.
crawler_cli: 시작 URL과 옵션을 제공하여 이 도구를 실행합니다.크롤링( : 이 도구는
crawl4ai사용하여 웹 페이지를 가져오고, 구성된 규칙(깊이, 패턴)에 따라 링크를 따라갑니다.정리( : 선택적으로 BeautifulSoup를 사용하여 HTML 콘텐츠를 정리합니다(탐색, 링크 제거).
마크다운 생성( : 정리된 HTML을 마크다운으로 변환합니다.
저장소( : 생성된 마크다운 콘텐츠는
./storage/디렉토리의 파일에 저장됩니다.mcp_server: MCP 서버가 시작되면(일반적으로 Cursor의 구성을 통해)mcp_server/data_loader.py실행됩니다.로딩 및 캐싱 : 데이터 로더는 캐시 파일(
.pkl)을 확인합니다. 유효한 경우 캐시에서 청크와 임베딩을 로드합니다. 유효하지 않으면./storage/에서.md파일을 읽습니다.청킹 및 임베딩 : 마크다운 파일은 제목을 기준으로 청크로 파싱됩니다. 각 청크에 대한 임베딩은
sentence-transformers사용하여 생성되어 메모리(및 캐시)에 저장됩니다.MCP 도구( : 서버는
fastmcp통해 도구(list_documents,search_documentation등)를 제공합니다.쿼리(커서) : 커서와 같은 MCP 클라이언트는 이러한 도구를 호출할 수 있습니다.
search_documentation미리 계산된 임베딩을 사용하여 쿼리와의 의미적 유사성을 기반으로 관련 청크를 찾습니다.
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.
기여하다
기여를 환영합니다! 이슈를 개설하거나 풀 리퀘스트를 제출해 주세요.
보안 참고 사항
피클 캐시: 이 프로젝트는 Python의
pickle모듈을 사용하여 처리된 데이터(storage/document_chunks_cache.pkl)를 캐시합니다. 신뢰할 수 없는 출처의 데이터를 피클링 해제하는 것은 안전하지 않을 수 있습니다../storage/디렉터리는 신뢰할 수 있는 사용자/프로세스만 쓸 수 있도록 설정하세요.