maru-deep-pro-search 0.26.4

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% 절약
🔍 하이브리드 멀티 엔진 검색	DuckDuckGo, Bing 등 9개 엔진 + 자동 페일오버. RRF + BM25 하이브리드 랭킹
📊 시맨틱 재랭킹	로컬 ibm-granite/granite-embedding-97m-multilingual-r2 임베딩 모델로 정교한 문서 순위 재조정
🛡️ 인용 파이프라인	모든 정보에 [N] 출처 태그 강제 매핑. 환각 최소화
🔗 21개 에이전트 지원	Cursor, Claude Code, Cline, Aider 등 주요 AI 개발 도구 전격 대응
⚡ 완전 무료	상용 검색 API 키 없이 $0로 모든 기능 사용

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

---

🛠️ 핵심 도구 (MCP Tools)

도구	기능	특징
search	웹 검색 + 낮은 refiner 스니펫 정제	relevance score, authority badge 포함
fetch	웹 페이지 본문 추출 + 정제	원본 6000tok → ~1000tok 압축
fetch_bulk	다중 URL 병렬 fetch + 정제	대량 문서 처리 최적화
verify	다중 출처 사실 교차 검증	충돌 감지 및 신뢰도 점수 제공
decompose	복잡한 질의 분해	의도/엔티티 추출, 서브쿼리 생성

• 📖 상세 도구 가이드: 웹사이트 도구 소개
• 🤖 지원 에이전트 목록: 웹사이트 에이전트 목록

---

📦 설치 및 설정

빠른 설치

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
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	지원 안 함	지원 안 함
로컬 임베딩	Granite 97M (내장)	없음	없음
토큰 절약	83% (Refiner)	없음	없음

---

📈 품질 벤치마크

TREC(Text REtrieval Conference) 표준 데이터셋 기준 (10개 복합 쿼리)

성능 지표	단일 엔진 기준	다중 엔진 (maru)	개선율
Precision@5	baseline	+86%	🚀
NDCG@10	baseline	+36%	📈
MRR	baseline	+25%	⬆️

⚠️ 트레이드오프: 9개 엔진 통합으로 단일 엔진 대비 응답 시간이 약 2배 소요될 수 있습니다.

# 재현 명령어
uv run python benchmark/search_quality_benchmark.py

---

⚙️ 주요 환경 변수

환경 변수	기본값	설명
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 파일을 참고하세요.

⬆️ 맨 위로 돌아가기