문서 크롤러 및 MCP 서버

이 프로젝트는 웹사이트를 크롤링하고, 마크다운 문서를 생성하고, 커서와 같은 도구와 통합되도록 설계된 MCP(Model Context Protocol) 서버를 통해 해당 문서를 검색할 수 있는 도구 세트를 제공합니다.

특징

• 웹 크롤러( crawler_cli ) :
  • crawl4ai 사용하여 주어진 URL에서 웹사이트를 크롤링합니다.
  • 구성 가능한 크롤링 깊이, URL 패턴(포함/제외), 콘텐츠 유형 등
  • Markdown으로 변환하기 전에 HTML을 선택적으로 정리합니다(탐색 링크, 헤더, 푸터 제거).
  • 크롤링된 콘텐츠로부터 단일의 통합된 마크다운 파일을 생성합니다.
  • 기본적으로 출력을 ./storage/ 에 저장합니다.
• MCP 서버( mcp_server ) :
  • ./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 서버를 실행하도록 설계되었습니다.

워크플로

1. 크롤링: crawler_cli 도구를 사용하여 웹사이트를 크롤링하고 ./storage/ 에 .md 파일을 생성합니다.
2. 서버 실행: mcp_server 구성하고 실행합니다(일반적으로 Cursor와 같은 MCP 클라이언트에서 관리).
3. 로드 및 임베드: 서버는 ./storage/ 에 있는 .md 파일의 콘텐츠를 자동으로 로드, 청크 및 임베드합니다.
4. 쿼리: MCP 클라이언트(예: 커서 에이전트)를 사용하여 서버 도구( list_documents , search_documentation 등)와 상호 작용하여 크롤링된 콘텐츠를 쿼리합니다.

설정

이 프로젝트에서는 종속성 관리와 실행에 uv 사용합니다.

1. uv 설치 : UV 웹사이트 의 지침을 따르세요.
2. 저장소를 복제합니다.지엑스피1
3. 종속성 설치:
   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 ).

패턴과 깊이를 활용한 크롤링 개선

때로는 문서 사이트의 특정 하위 섹션만 크롤링하고 싶을 수 있습니다. 이 경우 --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-* 에 있는 콘텐츠만 원한다고 가정해 보겠습니다.

1. 시작 URL: 개요 페이지에서 시작할 수 있습니다: https://pulsar.apache.org/docs/4.0.x/admin-api-overview/ .
2. 패턴 포함: admin-api 포함하는 링크만 필요합니다: --include-pattern "*admin-api*" .
3. 최대 깊이: 시작 페이지에서 관리자 API 링크가 몇 단계까지 연결되는지 파악해야 합니다. 2 부터 시작하여 필요에 따라 늘려야 합니다.
4. 자세한 모드: -v 사용하여 어떤 URL이 방문되거나 건너뛰어지는지 확인하여 패턴과 심도를 디버깅하는 데 도움이 됩니다.

출력 파일(이 경우 기본적으로 ./storage/pulsar.apache.org.md )을 확인하세요. 페이지가 누락된 경우 --max-depth 3 으로 늘려 보세요. 관련 없는 페이지가 너무 많이 포함된 경우 --include-pattern 더 구체적으로 지정하거나 --exclude-pattern 규칙을 추가하세요.

2. MCP 서버 실행

MCP 서버는 커서(Cursor)와 같은 MCP 클라이언트에서 stdio 전송을 통해 실행되도록 설계되었습니다. 서버를 실행하는 명령은 다음과 같습니다.

하지만 Python이 mcp_server 모듈을 찾을 수 있도록 프로젝트의 루트 디렉토리( MCPDocSearch )에서 실행해야 합니다.

3. 커서 구성

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" ).

종속성

사용된 주요 라이브러리:

• crawl4ai : 핵심 웹 크롤링 기능.
• fastmcp : MCP 서버 구현.
• sentence-transformers : 텍스트 임베딩을 생성합니다.
• torch : sentence-transformers 에 필요함.
• typer : 크롤러 CLI를 빌드합니다.
• uv : 프로젝트 및 환경 관리.
• beautifulsoup4 ( crawl4ai 통해): HTML 파싱.
• rich : 향상된 터미널 출력.

건축학

이 프로젝트는 다음과 같은 기본 흐름을 따릅니다.

1. crawler_cli : 시작 URL과 옵션을 제공하여 이 도구를 실행합니다.
2. 크롤링( crawl4ai ) : 이 도구는 crawl4ai 사용하여 웹 페이지를 가져오고, 구성된 규칙(깊이, 패턴)에 따라 링크를 따라갑니다.
3. 정리( crawler_cli/markdown.py ) : 선택적으로 BeautifulSoup를 사용하여 HTML 콘텐츠를 정리합니다(탐색, 링크 제거).
4. 마크다운 생성( crawl4ai ) : 정리된 HTML을 마크다운으로 변환합니다.
5. 저장소( ./storage/ ) : 생성된 마크다운 콘텐츠는 ./storage/ 디렉토리의 파일에 저장됩니다.
6. mcp_server 시작 : MCP 서버가 시작되면(일반적으로 Cursor의 구성을 통해) mcp_server/data_loader.py 실행됩니다.
7. 로딩 및 캐싱 : 데이터 로더는 캐시 파일( .pkl )을 확인합니다. 유효한 경우 캐시에서 청크와 임베딩을 로드합니다. 유효하지 않으면 ./storage/ 에서 .md 파일을 읽습니다.
8. 청킹 및 임베딩 : 마크다운 파일은 제목을 기준으로 청크로 파싱됩니다. 각 청크에 대한 임베딩은 sentence-transformers 사용하여 생성되어 메모리(및 캐시)에 저장됩니다.
9. MCP 도구( mcp_server/mcp_tools.py ) : 서버는 fastmcp 통해 도구( list_documents , search_documentation 등)를 제공합니다.
10. 쿼리(커서) : 커서와 같은 MCP 클라이언트는 이러한 도구를 호출할 수 있습니다. search_documentation 미리 계산된 임베딩을 사용하여 쿼리와의 의미적 유사성을 기반으로 관련 청크를 찾습니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

기여하다

기여를 환영합니다! 이슈를 개설하거나 풀 리퀘스트를 제출해 주세요.

보안 참고 사항

• 피클 캐시: 이 프로젝트는 Python의 pickle 모듈을 사용하여 처리된 데이터( storage/document_chunks_cache.pkl )를 캐시합니다. 신뢰할 수 없는 출처의 데이터를 피클링 해제하는 것은 안전하지 않을 수 있습니다. ./storage/ 디렉터리는 신뢰할 수 있는 사용자/프로세스만 쓸 수 있도록 설정하세요.