AeternaLabsHQ/pullmd

PullMD – 자체 호스팅형 URL에서 Markdown으로 변환 서비스

무엇인가요

• 웹 페이지(또는 기타 미디어 유형)를 가져와 토큰 효율적인 깨끗한 Markdown 문서를 반환하는 자체 호스팅 웹 서비스입니다.
• 온라인 콘텐츠의 간결하고 구조화된 표현이 필요한 인간과 AI 에이전트를 위한 설계입니다.

주요 기능

기능	세부 사항
웹 페이지 추출	카스케이드 처리: Cloudflare 네이티브 Markdown → Mozilla Readability → Trafilatura → (백업) Playwright를 통한 헤드리스 Chromium. Reddit 및 Hacker News 스레드(댓글 트리 포함)도 완전히 지원합니다.
문서 변환(v3)	PDF, Word/PowerPoint/Excel, EPUB 등은 업로드하거나 URL로 제공 가능합니다. 선택적 OCR 타이어(?pdf=ocr)를 통해 고품질 테이블을 생성합니다.
미디어 처리	이미지 → 캡션 생성; 음성 → 음성 인식; YouTube URL → 제목, 설명, 타임스탬프가 포함된 전사본. 모든 기능은 사용자가 구성한 OpenAI 호환 비전/음성 인식 엔드포인트로 작동합니다.
출력 형식	Markdown 본문에는 # 제목 + 콘텐츠만 포함됩니다. 모든 메타데이터(원본 URL, 가져온 날짜, 저자, 서브레딧, 좋아요 수, OCR/모델 사용 여부 등)는 YAML 프론트마터 블록에 저장되며, PULLMD_FRONTMATTER_FIELDS로 필요 없는 필드를 제거할 수 있습니다.
공유 가능한 ID	모든 변환에는 8자리 16진수 ID가 부여됩니다. GET /s/:id로 캐시된 Markdown을 반환하며, 1시간 이상 경과한 경우 자동으로 갱신됩니다.
API 표면	• GET /api?url=… – 단일 변환(웹 전용). • POST /api/file – 문서, 이미지, 음성 파일 업로드 후 변환. • POST /mcp – 상태 없는 스트리밍을 지원하는 MCP(Claude 호환) 엔드포인트.
인증	세 가지 모드: disabled(공개), single-admin(단일 관리자), multi-user(자기 서비스 가입). 관리자는 제공된 CLI로 사용자 관리 가능.
보안	내장된 SSRF 보호 기능으로 개인, 루프백, 링크-로컬, 클라우드 메타데이터 주소를 차단합니다. PULLMD_ALLOWED_HOSTS로 호스트를 화이트리스트화 가능.
확장성	PULLMD_SITE_RECIPES를 통해 사이트별 "레시피"(JSON-LD → 프론트마터, 커스텀 선택자 등)를 추가 가능.
모니터링	사이드카 건강 엔드포인트(GET /api/status)는 렌더러(Playwright, MarkItDown 등)가 다운된 경우 503을 반환합니다.

실행 방법

1. Docker Compose(권장) – Docker Hub에서 사전 준비된 멀티아키텍처 이미지를 다운로드하고 단일 명령어로 시작:

   mkdir pullmd && cd pullmd
   curl -O https://raw.githubusercontent.com/AeternaLabsHQ/pullmd/main/docker-compose.yml
   docker compose up -d   # 서비스는 http://localhost:3000에서 작동
   

   .env 파일은 필요 없으며, 합리적인 기본값이 내장되어 있습니다. 설정을 재정의하려면 compose 파일과 같은 디렉터리에 .env 파일을 생성하세요.
2. 옵션 사이드카 – 스택에는 세 가지 보조 컨테이너가 포함됩니다:
   • pullmd-trafilatura – Trafilatura 추출 서비스.
   • pullmd-playwright – JavaScript가 풍부한 페이지용 헤드리스 Chromium/Firefox/WebKit 렌더러(이미지 캐시에 약 3.7GB 추가). 정적 추출만 필요하면 생략 가능.
   • pullmd-markitdown – 문서에서 Markdown으로 변환하는 도구(PDF/Office/EPUB에 필수). 문서 변환 기능을 비활성화하려면 생략.
3. 로컬 개발 – 리포지토리 클론 후 npm install 실행 후 npm start 실행.

설정 요약 (.env 파일에서 설정)

• PUBLIC_URL – 도움말 페이지 및 다운로드 가능한 Claude 스킬에서 사용되는 공개 원본.
• PULLMD_AUTH_MODE – disabled / single-admin / multi-user.
• PULLMD_ADMIN_EMAIL / PULLMD_ADMIN_PASSWORD – 관리자 자격 증명 초기화.
• PULLMD_VISION_API_KEY, PULLMD_STT_API_KEY – 임의의 OpenAI 호환 비전/음성 인식 엔드포인트로 이미지 캡션 또는 음성 인식 활성화.
• PULLMD_PDF_OCR_API_KEY – PDF용 프리미엄 OCR 타이어 활성화(?pdf=ocr).
• PULLMD_FRONTMATTER_FIELDS – LLM 파이프라인의 토큰 사용량을 줄이기 위해 유지할 프론트마터 키를 화이트리스트화.
• DISABLE_PUBLIC_HISTORY – 프라이버시 중심 배포에서 공개 변환 기록 숨기기.
• PULLMD_ALLOWED_HOSTS – 기본 SSRF 차단을 우회해 내부 호스트를 가져오려는 경우 화이트리스트화.

AI/LLM 워크플로우에서의 중요성

• 토큰 효율성: 모든 메타데이터를 프론트마터로 이동하고 본문을 최소화함으로써, LLM에 전달 시 반복된 URL이나 타임스탬프로 인한 컨텍스트 낭비를 방지합니다.
• 에이전트 준비: MCP 엔드포인트를 통해 Claude 스타일 에이전트가 스트리밍 호환 HTTP 호출로 변환을 요청할 수 있습니다.
• 자체 호스팅 제어: 기본 웹 추출에는 제3자 API 키가 필요 없어 데이터는 비공개이며 비용은 예측 가능합니다.
• 확장 가능한 미디어 처리: 이미지와 음성은 실시간으로 캡션/전사본으로 변환 가능하여 멀티모달 에이전트에 유용합니다.

일반적인 사용 예시

# 웹 페이지를 한 번만 Markdown으로 변환
curl "http://localhost:3000/api?url=https://example.com"

# PDF 업로드 후 변환 (markitdown 사이드카 필요)
curl -F file=@report.pdf http://localhost:3000/api/file

# ID를 통해 공유 가능한 Markdown 얻기
curl http://localhost:3000/s/1a2b3c4d

라이선스 – AGPL-3.0 (LICENSE 참조).

---

위 모든 세부 정보는 리포지토리의 README에서 직접 가져왔으며, 추가 기능은 추측되지 않았습니다.