AI 에이전트용 문서 크롤러를 만들고 49초 만에 마크다운 60페이지를 가져왔습니다

AI 요약

개발자가 문서를 찾아 정리하고 프로젝트에 저장하던 일을 AI 에이전트가 직접 처리하도록 MCP 서버 pulpie-mcp를 만들었습니다. 요약이나 검색 결과 일부가 아니라 표, 링크, 이미지, 코드, 제목을 포함한 문서 전체를 깔끔한 마크다운으로 가져옵니다. 작성자는 Claude로 문서 60페이지를 크롤링해 저장하는 데 약 49초가 걸렸다고 소개합니다.

에이전트가 문서를 가져오고 보관하는 방식

pulpie-mcp는 네 가지 도구를 제공합니다. fetch_markdown은 페이지를 가져와 마크다운을 에이전트에 바로 전달합니다. save_markdown은 페이지를 파일로 저장하고, crawl_docs는 문서 섹션 전체를 크롤링해 로컬에 보관합니다. list_library는 이미 저장한 문서를 확인합니다.

crawl_docs는 각 페이지 내용을 에이전트에 한꺼번에 반환하지 않습니다. 파일을 디스크에 저장한 뒤 메타데이터를 전달합니다. 각 파일에는 원본 URL, 제목, 가져온 시각이 frontmatter로 기록됩니다. 프로젝트별 문서는 프로젝트 안에, 일반 조사 자료는 ~/.pulpie/library/에 저장할 수 있습니다. 이후 에이전트는 필요한 파일만 골라 읽습니다.

크롤러는 robots.txt와 문서 경로 아래 sitemap, 사이트 루트의 sitemap을 차례로 확인합니다. 이를 찾지 못하면 링크를 따라갑니다. 시작한 호스트와 문서 경로 범위를 벗어나지 않으며, 네 개의 작업자가 요청을 병렬 처리합니다.

로컬 모델과 실행 시간

콘텐츠 정리에는 feyninc/pulpie-orange-small 모델을 사용합니다. 2억 1천만 파라미터 규모의 encoder 모델이며, 작성자 환경에서는 VRAM 약 420MB를 사용합니다. MCP 서버와 별도 로컬 백엔드로 프로세스를 나눠 MCP 프로세스 자체는 PyTorch와 모델을 불러오지 않습니다. 백엔드가 실행 중이 아니면 MCP 서버가 자동으로 시작하고, 여러 에이전트 세션이 같은 백엔드를 공유합니다. 30분 동안 요청이 없으면 백엔드가 종료되며 메모리를 반환합니다.

작성자의 60페이지 테스트에서는 백엔드 시작과 GPU 모델 로딩에 약 10초, 크롤링과 저장에 약 37초가 걸려 총 약 49초가 소요됐습니다. 모델이 이미 로드된 상태라면 시작 시간은 빠집니다. 다만 작성자가 직접 시험한 환경은 Linux와 NVIDIA/CUDA이며, PDF는 처리하지 않습니다. 클라이언트 렌더링에 의존하는 페이지는 내용이 비어 있을 가능성도 있습니다. 코드는 Apache 2.0 라이선스지만 모델은 CC BY-NC 4.0으로, 별도 합의가 없다면 비상업적 용도로 제한됩니다.

dev.to 반응

• @slabb — 가져오기와 저장을 나눈 점이 적절합니다. frontmatter에 원본 URL, 제목, 가져온 시각을 기록하고 디스크를 라이브러리로 쓰는 방식은 많은 크롤러가 놓치는 부분입니다. 수치도 나눠 볼 필요가 있습니다. 작업자 네 명이 60페이지를 37초에 처리했다면 페이지당 약 600ms이고, 대부분은 모델 추론 시간입니다. ML 기반 정리의 비용이지만, 복잡한 마크업에서도 내용을 보존합니다. 반면 시스템 WebView로 DOM을 직접 추출하면 문서형 페이지에서 페이지당 약 10ms로, 모델이나 GPU도 필요하지 않습니다. 둘 중 하나가 늘 낫다는 뜻은 아닙니다. HTML이 복잡하면 pulpie가 유리하고, 구조가 깔끔한 문서 사이트가 대부분인 경우에는 네이티브 방식이 유리합니다. robots, sitemap, 링크 순으로 살피는 방식은 어느 쪽에도 적절합니다. 문서 라이브러리를 만드는 도구와 인증·스크린샷이 필요한 실시간 웹용 MCP 브라우저 navette가 함께 갖춰지면 에이전트의 웹 도구 구성이 제법 모양을 갖춥니다.
  • @sizzlebop — 타당한 지적입니다. 모델 기반 추출은 확실히 비용이 들고, 구조가 깔끔한 문서 사이트에서는 네이티브 DOM 방식이 훨씬 빠를 수 있습니다. 제가 원한 것은 사이트나 프레임워크마다 별도 규칙을 만들지 않고도, 웬만큼 구조가 있는 페이지라면 같은 형태의 정돈된 마크다운을 얻는 일관성이었습니다. 잘 정리된 문서에는 과한 방식일 수 있지만 HTML이 지저분해지면 모델이 제 몫을 합니다. 페이지 구조가 명확하면 먼저 저렴한 네이티브 추출을 시도하고, 그렇지 않을 때 Pulpie로 넘어가는 혼합 방식도 흥미롭습니다. 그러면 문서 대량 크롤링 속도를 높이면서 복잡한 페이지를 정리하는 기능도 유지할 수 있습니다. 지속적으로 쓰는 문서 라이브러리와 실시간 브라우저 도구를 함께 두면, 에이전트의 웹 기능이 검색과 요약을 넘어 더 쓸모 있어진다는 점에도 동의합니다.
• @reidmarlow — 로컬 백엔드가 30분 유휴 상태 뒤 종료되는 점이 일상적인 사용에 적합합니다. 로컬 MCP 도구는 VRAM을 계속 점유하는 상시 데몬으로 돌거나, 도구를 호출할 때마다 PyTorch를 불러오고 모델 가중치를 다시 로드하는 경우가 많습니다. 감시 타이머로 에이전트 작업이 끝난 뒤 메모리를 반환하면, 짧은 작업에서는 빠르게 처리하면서 백그라운드 서비스를 직접 관리하지 않아도 됩니다.
  • @sizzlebop — 바로 그 두 가지 상황을 피하려고 했습니다. 나중에 다시 쓸지도 모른다는 이유로 모델이 VRAM을 계속 차지하는 것도 싫었고, 매번 도구를 호출할 때마다 시작 비용을 치르는 것도 원치 않았습니다. 유휴 시간 제한은 적당한 절충안이었습니다. 짧은 작업은 백엔드가 이미 준비된 상태라 빠르게 처리하고, 한동안 쓰지 않으면 메모리를 반환합니다. 작은 구현 세부 사항이지만 설치해 두고 평소처럼 쓰기에 더 실용적으로 느껴지게 합니다.
• @smiley_lion — 에이전트에 전달하는 형식으로 깔끔한 마크다운을 고른 것은 소박하지만 실제적인 이유에서 적절합니다. 요약된 문서에서는 에이전트가 정확히 맞춰야 하는 문자열이 사라집니다. 저는 사람이 제 작업을 찾을 만한 곳을 찾을 때 반대 문제를 자주 겪습니다. 페이지를 친절하게 줄이는 과정에서 잘못된 방향이라는 사실을 알려줄 세부 내용까지 지워져 나중에 다시 가져오곤 합니다. 원문 마크다운을 보관하면 그 왕복을 줄일 수 있습니다. 49초라는 수치는 크롤링 시간인가요, 서버 시작까지 포함한 전체 시간인가요? 첫 호출이 느릴 때 도구 때문인지 네트워크 때문인지 고민하는 데 시간을 꽤 썼습니다.
  • @sizzlebop — 맞습니다. 에이전트가 정확한 옵션 이름, 메서드 시그니처, 오류 문자열이나 사소한 주의사항을 찾을 때는 친절한 요약이 오히려 방해가 됩니다. 중요한 부분을 미리 판단해 잘라내는 대신 전체 마크다운을 보존하려 한 주된 이유입니다. 49초는 콜드 스타트를 포함한 전체 시간입니다. 백엔드가 실행되지 않은 상태에서 시작해 모델을 GPU에 올리는 데 약 10초, 실제 60페이지 크롤링과 저장에 약 37초가 걸렸습니다. 백엔드가 준비된 뒤에는 시작 시간이 들지 않습니다.

원문: dev.to / 번역·요약: Trawling