Metadata-Version: 2.4
Name: maru-deep-pro-search
Version: 0.26.14
Summary: Universal AI search MCP server — Perplexity-level quality with zero API keys. Multi-engine web scraping, intelligent ranking, and citation-native answers.
Author-email: claudianus <claudianus@engineer.com>
License-Expression: MIT
Project-URL: Homepage, https://claudianus.github.io/maru-deep-pro-search/
Project-URL: Documentation, https://claudianus.github.io/maru-deep-pro-search/
Project-URL: Repository, https://github.com/claudianus/maru-deep-pro-search
Project-URL: Issues, https://github.com/claudianus/maru-deep-pro-search/issues
Keywords: mcp,model-context-protocol,web-search,deep-research,perplexity,ai-search,scraping,llm-tools,trafilatura,citations,cursor,claude,agent,coding-assistant,semantic-search,bm25
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: htmldate>=1.9.4
Requires-Dist: huggingface-hub>=0.20.0
Requires-Dist: llama-cpp-python>=0.3.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: pygments>=2.20.0
Requires-Dist: scrapling[fetchers]>=0.2.99
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: urllib3>=2.7.0
Requires-Dist: cloakbrowser>=0.1.0
Provides-Extra: semantic
Provides-Extra: gpu
Requires-Dist: llama-cpp-python>=0.3.0; platform_system != "Darwin" and extra == "gpu"
Provides-Extra: metal
Requires-Dist: llama-cpp-python>=0.3.0; platform_system == "Darwin" and extra == "metal"
Dynamic: license-file

# maru-deep-pro-search

<div align="center">

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

[🇺🇸 English](./README.en.md)

[![Version](https://img.shields.io/badge/version-v0.26.11-6C5CE7?style=flat-square&logo=github)](https://github.com/claudianus/maru-deep-pro-search)
[![PyPI](https://img.shields.io/pypi/v/maru-deep-pro-search?style=flat-square&color=2D98DA)](https://pypi.org/project/maru-deep-pro-search/)
[![Python](https://img.shields.io/pypi/pyversions/maru-deep-pro-search?style=flat-square&color=00B894)](https://pypi.org/project/maru-deep-pro-search/)
[![License](https://img.shields.io/badge/license-MIT-00B894?style=flat-square)](https://github.com/claudianus/maru-deep-pro-search/blob/main/LICENSE)
[![CI](https://github.com/claudianus/maru-deep-pro-search/actions/workflows/validate.yml/badge.svg)](https://github.com/claudianus/maru-deep-pro-search/actions/workflows/validate.yml)

[🌐 웹사이트](https://claudianus.github.io/maru-deep-pro-search/) · [📦 PyPI](https://pypi.org/project/maru-deep-pro-search/) · [💻 GitHub](https://github.com/claudianus/maru-deep-pro-search)

</div>

---

## 🚀 주요 기능

| 기능 | 설명 |
|:---:|:---|
| 🧠 **내장 경량 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` | 웹 검색 + 랭킹 + 정제 | intent 감지 → 엔진 선택 → 병렬 검색 → BM25/Authority 랭킹 → Granite 97M 재랭킹 → Qwen3.5 Refiner |
| `fetch` | 단일 URL 본문 수집·정제 | HTTP GET → trafilatura Markdown 추출 → Qwen3.5 Refiner (6000tok → ~1000tok) |
| `fetch_bulk` | 다중 URL 병렬 fetch | Semaphore 동시성 제어 + query 기반 relevance filter |
| `verify` | 다중 출처 교차 검증 | 주장 추출 → 정규화 → Jaccard 병합 → 충돌 탐지 → Confidence Score (0-100%) |
| `decompose` | 복합 질의 서브쿼리 분해 | intent 분류(12종) → entity 추출 → 복잡도 평가 → 의도별 규칙 분해 → Qwen3.5 다듬기 |

### `search` 3단계 모드

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

### 의도된 툴 체인

```
복합 질의: 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) |

- 🤖 **지원 에이전트 목록**: [웹사이트 에이전트 목록](https://claudianus.github.io/maru-deep-pro-search/#agents)

---

## 📦 설치 및 설정

### 빠른 설치

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

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

**Pip / Hatch:**
```bash
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:**
```bash
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)은 첫 실행 시 다운로드됩니다. 콜드스타트 지연을 방지하려면 사전에 실행하세요:
>
> ```bash
> maru-deep-pro-search-setup warmup-embeddings -q
> maru-deep-pro-search-setup setup --check
> ```

### 에이전트 설정

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

**Claude Code** (`~/.claude/settings.json`):
```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 + 자동 복구** | 없음 | 없음 |

---

## 📈 품질 벤치마크

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

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

> ⚠️ **트레이드오프**: 9개 엔진 통합으로 단일 엔진 대비 응답 시간이 약 **2배** 소요될 수 있습니다.
> 
> ```bash
> # 재현 명령어
> uv run python benchmark/search_quality_benchmark.py
> ```

---

## ⚙️ 주요 환경 변수

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

- 🔧 **전체 환경 변수 상세**: [웹사이트 설정 페이지](https://claudianus.github.io/maru-deep-pro-search/#config)

---

## 🛠️ 문제 해결 (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](CONTRIBUTING.md)를 참고하세요. 버그 리포트와 PR을 환영합니다!
- **라이선스**: MIT License — 자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.

<div align="center">

**[⬆️ 맨 위로 돌아가기](#maru-deep-pro-search)**

</div>
