maru-deep-pro-search 0.27.0

Universal AI search MCP server — Perplexity-level quality with zero API keys. Multi-engine web scraping, intelligent ranking, and citation-native answers.

maru-deep-pro-search

AI 에이전트를 위한 멀티 엔진 딥 리서치 MCP 서버 — Perplexity급 품질, 완전 묶음

🇺🇸 English

🌐 웹사이트 · 📦 PyPI · 💻 GitHub

---

🚀 주요 기능

기능	설명
🧠 내장 경량 LLM 리파이너	llama-cpp-python 기반 Qwen3.5(0.8B~4B)가 웹 콘텐츠를 자동 정제. 호스트 LLM 토큰 83% 절약. SHA-256 무결성 검증 + 손상 모델 자동 복구
🔍 하이브리드 멀티 엔진 검색	DuckDuckGo, Bing 등 9개 엔진 + 자동 페일오버. RRF + BM25 하이브리드 랭킹
📄 trafilatura 정밀 추출	HTML→Markdown 변환에 trafilatura 사용. 헤딩·코드 블록·리스트 구조 보존, CSS 폴백 내장
📊 시맨틱 재랭킹	로컬 ibm-granite/granite-embedding-97m-multilingual-r2 임베딩 모델로 정교한 문서 순위 재조정
🛡️ 인용 파이프라인	모든 정보에 [N] 출처 태그 강제 매핑. 환각 최소화
🔗 34개 에이전트 지원	Cursor, Claude Code, Cline, Aider, Codex, OpenCode, Kimi 등 주요 AI 개발 도구 전격 대응
🦊 브라우저 안티-디텍션	3단계 캐스케이드: camofox (Firefox) → CloakBrowser (Chromium) → Playwright. CAPTCHA·블록 회피, 자동 감지
⚡ 완전 무료	상용 검색 API 키 없이 $0로 모든 기능 사용

💡 Perplexity-style 반복 리서치: decompose → search → fetch → verify 루프를 호스트 에이전트가 직접 제어하여 품질 기준 달성 시까지 반복합니다.

---

🛠️ 핵심 도구 (MCP Tools)

Core Research Pipeline — 5종

도구	역할	파이프라인
search	웹 검색 + 랭킹	QueryPlan → 엔진 선택 → 병렬 검색 → CandidateResult 정화 → BM25/RRF/Authority → Granite 97M 재랭킹
fetch	단일 URL 본문 수집·정제	HTTP GET → trafilatura Markdown 추출 → Qwen3.5 Refiner → EvidencePacket metadata
fetch_bulk	다중 URL 병렬 fetch	Semaphore 동시성 제어 + query 기반 relevance filter + EvidencePacket metadata
verify	다중 출처 교차 검증	주장 추출 → supporting/contradicting sources → conflict_count → overall_consensus
decompose	복합 질의 서브쿼리 분해	intent 분류(12종) → entity 추출 → 복잡도 평가 → 의도별 규칙 분해 → Qwen3.5 다듬기

search 3단계 모드

모드	엔진 수	재랭킹	리파이너	용도
fast	1	—	—	빠른 조회 (API 시그니처, 단순 팩트체크)
balanced	2	Granite 97M	—	기본 (버전 체크, 중간 복잡도)
deep	3+	Granite 97M	—	CVE 조사, 아키텍처, 보안

deep 출력은 ## Research:, _engines:, ### Sources, _score: 계약을 유지하면서 BM25, metadata, RRF, semantic, final score와 간단한 ranking reason을 _ranking: 줄에 함께 표시합니다. fast/balanced는 Search:와 번호 결과 형식을 유지합니다.

Qwen3 reranker, BGE-M3, ColBERT/SPLATE 계열 late interaction은 기본 품질 경로가 아니라 disabled-by-default optional adapter입니다. 고정 30-query corpus에서 품질 개선과 p95 latency 비회귀를 증명하기 전에는 core dependency나 기본 실행 경로로 올리지 않습니다.

의도된 툴 체인

복합 질의: decompose → [search × N] → fetch_bulk(top3) → verify → 코드 생성
단순 조회: search(fast) → 답변
보안 이슈: search(deep) → fetch_bulk(top5) → verify → 코드 생성
비교 분석: decompose → search × N(+fetch) → verify → 종합

내부 안전장치

레이어	메커니즘
_with_enforcement	세션 연구 완료 검사 — 미완료 시 툴 블록
_with_validation	입력 검증 (쿼리 길이, URL scheme, SSRF 가드)
_with_audit	모든 호출 → SQLite 감사 로그
CircuitBreaker	엔진별 3연속 실패 → 60초 OPEN
RateLimiter	엔진별 슬라이딩 윈도우 (10req/60s)
Semaphore(4)	전체 동시 검색 상한
프롬프트 인젝션 방어	Zero-width 제거, Chat token 중화

Utility — 3종

도구	역할
version	현재 maru-deep-pro-search 버전 반환
list_engines	등록된 9개 엔진 메타데이터 (quality tier, reliability %, latency)
engine_health	실시간 서킷 브레이커 상태 (CLOSED/OPEN/HALF-OPEN, failure count)

• 🤖 지원 에이전트 목록: 웹사이트 에이전트 목록

---

📦 설치 및 설정

빠른 설치

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/claudianus/maru-deep-pro-search/main/scripts/install.sh | bash

Windows:

irm https://raw.githubusercontent.com/claudianus/maru-deep-pro-search/main/scripts/install.ps1 | iex

Pip / Hatch:

pip install --user maru-deep-pro-search
# Optional: install browser anti-detection engine for CAPTCHA-heavy sites
pip install --user cloakbrowser
maru-deep-pro-search-setup setup

uv:

uv tool install --python 3.12 maru-deep-pro-search

[!NOTE] 설치 스크립트가 시스템 하드웨어를 자동 감지하고 최적의 Qwen3.5 모델(0.8B~4B)을 다운로드합니다. GPU(CUDA/Metal)가 있으면 가속 wheel을 자동 설치합니다.

[!NOTE] Granite 97M 가중치 파일(Hugging Face)은 첫 실행 시 다운로드됩니다. 콜드스타트 지연을 방지하려면 사전에 실행하세요:

maru-deep-pro-search-setup warmup-embeddings -q
maru-deep-pro-search-setup setup --check

에이전트 설정

설치 후 에이전트(예: Cursor)를 완전히 종료 후 재시작하세요.

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "maru-deep-pro-search": {
      "command": "python3",
      "args": ["-m", "maru_deep_pro_search.server"]
    }
  }
}

---

🎯 사용 방법

에이전트 시스템 프롬프트(User Rules) 또는 첫 대화에 아래 지침을 지정하여 검색 활용을 강제할 수 있습니다:

• "코드 작성 전에 반드시 웹 검색을 수행하여 최신 명세를 확인하고 [1], [2] 형식으로 명확한 출처를 표기해줘."
• "Next.js 15 App Router의 Server Action revalidate 에러 관련 최신 해결 방법을 검색해서 알려줘."
• "CVE-2026-40347 취약점 관련 공식 권고(Advisory)를 검색해 현재 프로젝트가 사용하는 버전이 안전한지 검증해줘."

---

📊 기능 비교

비교 항목	maru	Tavily MCP	Perplexity MCP
이용 비용	무료 ($0)	제한적 무료 / 유료	월 $5 이상
연동 엔진	9개 + 자동 페일오버	단일 API	단일 API
리서치 강제화	3단계 게이트	지원 안 함	지원 안 함
리서치 모니터링	Trace 및 Insights	지원 안 함	지원 안 함
HTML→Markdown 추출	trafilatura (정밀)	단순 파싱	단순 파싱
로컬 임베딩	Granite 97M (내장)	없음	없음
토큰 절약	83% (Refiner)	없음	없음
모델 무결성 검증	SHA-256 + 자동 복구	없음	없음

---

📈 품질 벤치마크

고정 30-query live corpus 기준 (.omo/evidence/search-quality-gate/metrics.json)

성능 지표	단일 엔진 web_search	deep search v3	변화
Precision@5	0.187	0.473	+154%
NDCG@10	0.332	0.585	+76%
MRR	0.447	0.840	+88%

⚠️ 트레이드오프: 30-query live corpus 기준 deep 검색 p50은 약 9.9초, p95는 약 20.9초이며, 정확 질의는 broad expansion을 끄고 원 질의를 보존합니다.

# 재현 명령어
uv run python benchmark/search_quality_benchmark.py --queries .omo/evidence/search-quality-baseline/queries.jsonl --output .omo/evidence/search-quality-gate/metrics.json

---

⚙️ 주요 환경 변수

환경 변수	기본값	설명
MARU_STRICT_QUERY	1	모호하거나 불완전한 검색어 필터링 및 정규화
MARU_EMBEDDING_MODEL	Granite 97M R2	문서 재랭킹에 사용할 시맨틱 임베딩 모델
MARU_BENCHMARK_SUITE	—	stress 설정 시 부하 테스트 벤치마크 수행

• 🔧 전체 환경 변수 상세: 웹사이트 설정 페이지

---

🛠️ 문제 해결 (Troubleshooting)

발생 현상	해결 방법
MCP 서버가 에이전트에 노출되지 않음	maru-deep-pro-search-setup setup 재실행 후 에이전트 완전 재시작
첫 검색 실행 시 지나치게 느림	maru-deep-pro-search-setup warmup-embeddings -q로 가중치 파일 사전 캐시
설정 변경 사항이 반영되지 않음	maru-deep-pro-search-update --with-setup 또는 setup --repair 실행
간헐적인 검색 엔진 에러 발생	engine_health 도구로 실시간 헬스 상태 점검

---

🤝 기여 및 라이선스

• 기여: CONTRIBUTING.md를 참고하세요. 버그 리포트와 PR을 환영합니다!
• 라이선스: MIT License — 자세한 내용은 LICENSE 파일을 참고하세요.

⬆️ 맨 위로 돌아가기