maru-deep-pro-search 0.29.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 에이전트를 위한 evidence-grade agent research infrastructure — 멀티 엔진 검색, 증거 원장, provider doctor JSON

🇺🇸 English

🌐 웹사이트 · 📦 PyPI · 💻 GitHub

---

🚀 주요 기능

기능	설명
🧠 내장 경량 LLM 리파이너	llama-cpp-python 기반 Qwen3.5(0.8B~4B)가 웹 콘텐츠를 자동 정제. 호스트 LLM 토큰 83% 절약. SHA-256 무결성 검증 + 손상 모델 자동 복구
🔍 하이브리드 멀티 엔진 검색	DuckDuckGo, Bing 등 9개 엔진 + 자동 페일오버. RetrievalHints 기반 검색 범위 힌트, RRF + BM25 + authority 랭킹
📄 trafilatura 정밀 추출	HTML→Markdown 변환에 trafilatura 사용. 헤딩·코드 블록·리스트 구조 보존, _evidence 메타데이터와 CSS 폴백 내장
📊 시맨틱 재랭킹	로컬 ibm-granite/granite-embedding-97m-multilingual-r2 임베딩 모델로 정교한 문서 순위 재조정
🛡️ 인용 파이프라인	모든 정보에 [N] 출처 태그를 안정적으로 매핑. 환각 최소화
🧾 증거 등급 인프라	metadata-only evidence ledger, get_evidence, list_evidence_runs, provider doctor JSON, policy-aware stealth 라우팅으로 조사 근거를 보존
🔗 34개 에이전트 지원	Cursor, Claude Code, Cline, Aider, Codex, OpenCode, Kimi 등 주요 AI 개발 도구 전격 대응
🦊 정책 인지 브라우저 라우팅	기본은 일반 fetch와 Playwright 폴백. 차단 신호가 있을 때만 예산·정책·로봇 설정을 확인한 뒤 policy-aware stealth로 명시적 상승
⚡ 완전 무료	상용 검색 API 키 없이 $0로 모든 기능 사용

💡 Host-led evidence substrate: 호스트 에이전트가 질의 분해, 도구 순서, 충분성 판단, 최종 종합을 직접 담당합니다. MCP는 search, fetch, fetch_bulk, verify로 검색 결과, 본문 증거, 메타데이터, 보안 경계를 안정적으로 제공합니다. 🧾 Evidence-grade agent research infrastructure: 경쟁 포지셔닝과 런타임 주장은 competitive source ledger와 competitive moat benchmark에서 확인한 항목만 공개 문서에 싣습니다.

---

🛠️ 핵심 도구 (MCP Tools)

Core Research Pipeline — 4종

도구	역할	파이프라인
search	웹 검색 + 랭킹	RetrievalHints → 엔진 선택 → 병렬 검색 → 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 호환 마커

Evidence & Diagnostics — 2종

도구	역할	증거 계약
get_evidence	마지막 또는 지정 run의 metadata-only evidence ledger 조회	raw HTML/body 없이 run_id, sources, warnings, access_risk 반환
list_evidence_runs	최근 evidence run 목록 조회	기본 20개 이내, provider doctor JSON과 함께 진단 가능

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나 기본 실행 경로로 올리지 않습니다.

v0.28.0 Host Delegation + 품질 게이트

• 고정 30-query live corpus로 Precision@5, NDCG@10, MRR, forbidden-domain rate, zero-relevance-visible rate, sanitizer leak rate, p50/p95 latency를 함께 측정합니다.
• benchmark/evaluation/paper/model-card/docs/spec, MCP tool annotations/structured output, latest-version, migration/tutorial, 한국어 소비자 질의, CVE/version/API 질의는 broad expansion과 자동 follow-up retry를 끄고 원 질의를 보존합니다.
• fetch/fetch_bulk는 기존 EXTERNAL CONTENT 보안 경계를 유지하면서 _evidence: 줄로 source type, extraction quality/method, access risk, taint status, fragments, citations를 노출합니다.

호스트 주도 툴 체인 예시

복합 질의: 호스트가 관점/키워드 선택 → search × N → fetch_bulk(선택 URL) → verify(필요 시) → 종합
단순 조회: search(fast) → 호스트 답변
보안 이슈: search(deep) → fetch_bulk(공식/권위 출처) → verify(증거 충돌 확인) → 코드 판단
비교 분석: 호스트가 비교 축 선택 → search × N(+fetch) → verify(증거 정렬 확인) → 종합

내부 안전장치

레이어	메커니즘
_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)

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

---

🧾 Evidence-Grade 경쟁 근거

Maru의 공개 경쟁 주장은 “더 좋다”는 감상이 아니라 측정 가능한 근거에 묶습니다. 아래 표의 모든 행은 competitive source ledger 또는 competitive moat benchmark에 연결됩니다.

검증 축	근거	Maru의 측정된 응답
차단 출처 투명성	ledger D-03~D-05, benchmark blocked_source_transparency	일반 fetch 우선, bot-wall metadata, policy-aware stealth 결정, get_evidence/list_evidence_runs로 확인 가능한 run 기록
provider doctor UX	ledger A-03~A-05, benchmark provider_doctor_status	maru-deep-pro-search-setup setup --check --json가 provider doctor JSON, browser 상태, evidence 경로, repair hint를 출력
durable evidence	ledger D-05~D-06, benchmark evidence_retrieval	metadata-only evidence ledger가 URL, 접근 위험, 추출 품질, 경고, citation metadata만 저장하고 본문·쿠키·토큰은 저장하지 않음
optional browser packaging	ledger C-02~C-04, packaging decision	CloakBrowser는 core dependency가 아니라 maru-deep-pro-search[stealth] extra이며 wheel/Docker/package data에 binary를 벤더링하지 않음

---

📦 설치 및 설정

빠른 설치

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
# 선택 사항: CAPTCHA·차단 페이지가 많은 환경에서 스텔스 브라우저 지원을 명시적으로 설치
pip install --user "maru-deep-pro-search[stealth]"
maru-deep-pro-search-setup browsers --check
maru-deep-pro-search-setup setup --check --json
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
maru-deep-pro-search-setup setup --check --json

에이전트 설정

설치 후 에이전트(예: 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)를 검색해 현재 프로젝트가 사용하는 버전이 안전한지 검증해줘."

---

📊 Evidence-Backed 운영 계약

검증 축	공개 계약	근거
Public tool surface	search, fetch, fetch_bulk, verify, get_evidence, list_evidence_runs는 기존 출력 마커를 유지하며 additive로 확장	output-contract artifacts, benchmark summary
차단 출처 투명성	일반 fetch 우선, bot-wall metadata 노출, policy-aware stealth 상승 여부 기록	source ledger D-03~D-05, benchmark summary
provider doctor JSON	setup --check --json이 provider/browser/evidence 상태와 repair hint를 read-only로 출력	source ledger A-03~A-05, benchmark summary
증거 보존	metadata-only evidence ledger는 raw body, cookies, tokens 없이 run/source metadata만 저장	source ledger D-05~D-06, benchmark summary

---

📈 품질 벤치마크

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

상세 설명: docs/search-quality-improvement-report.md

성능 지표	단일 엔진 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_EVIDENCE_DB	~/.maru/evidence.sqlite3	metadata-only evidence ledger 저장 위치
MARU_STEALTH_MODE	auto	auto, always, off 중 policy-aware stealth 동작
MARU_RESPECT_ROBOTS	1	스텔스 상승 시 robots 정책 존중 기본값
MARU_BENCHMARK_SUITE	—	stress 설정 시 부하 테스트 벤치마크 수행

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

---

🛠️ 문제 해결 (Troubleshooting)

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

---

🤝 기여 및 라이선스

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

⬆️ 맨 위로 돌아가기