Metadata-Version: 2.4
Name: maru-deep-pro-search
Version: 0.31.0
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
Provides-Extra: semantic
Provides-Extra: stealth
Requires-Dist: cloakbrowser>=0.1.0; extra == "stealth"
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

Maru는 AI 에이전트가 최신 웹 근거를 직접 다룰 수 있게 해주는 로컬 MCP 연구 서버입니다.
호스트 에이전트가 질문 분해, 검색 전략, 충분성 판단, 최종 종합을 맡고 Maru는 검색 결과,
본문 추출, evidence metadata, 진단 정보를 안정적으로 제공합니다.

[English](./README.en.md) · [GitHub Pages](https://claudianus.github.io/maru-deep-pro-search/) · [PyPI](https://pypi.org/project/maru-deep-pro-search/) · [Issues](https://github.com/claudianus/maru-deep-pro-search/issues)

처음이라면 GitHub Pages의 한 줄 설치와 첫 검색 흐름부터 보세요.

## 빠른 시작

가장 짧은 경로는 설치 스크립트 한 줄입니다. Python/uv 확인, 패키지 설치, 선택적 setup wizard를
한 번에 처리합니다.

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

이미 `uv`를 쓰는 환경에서 패키지만 설치하려면 아래 한 줄이면 됩니다.

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

설정 상태를 쓰기 전에 확인하고 싶을 때만 read-only 진단을 실행하세요.

```bash
maru-deep-pro-search-setup setup --check --json
```

설치나 설정 후에는 MCP를 쓰는 에디터나 에이전트를 완전히 재시작하세요. 첫 실행 지연을 줄이고
싶다면 임베딩 가중치를 미리 받아둘 수 있습니다.

```bash
maru-deep-pro-search-setup warmup-embeddings -q
```

서버를 직접 실행해야 하는 환경에서는 아래 명령을 MCP stdio 서버로 등록합니다.

```bash
maru-deep-pro-search
```

Claude Code처럼 명령 배열을 요구하는 클라이언트에서는 다음 형태가 기본입니다.

```json
{
  "mcpServers": {
    "maru-deep-pro-search": {
      "command": "maru-deep-pro-search",
      "args": []
    }
  }
}
```

`maru-deep-pro-search-setup setup --check --json`은 설정을 쓰지 않는 read-only 진단입니다.
provider 상태, browser 지원, evidence 저장 위치, repair hint를 기계가 읽기 쉬운 JSON으로 확인할 때 사용합니다.

## MCP 도구

공개 MCP 표면은 아래 9개 도구입니다. 문서가 이 목록과 달라지면 코드와 문서를 함께 고쳐야 합니다.

| 도구 | 역할 | 보통 쓰는 순간 |
|:---|:---|:---|
| `search` | 웹 검색 결과를 검색 모드와 랭킹 신호에 맞춰 반환 | 최신 API, 보안 권고, 릴리스 노트, 여러 출처가 필요한 조사 |
| `fetch` | 단일 URL의 본문을 가져와 Markdown 중심으로 정제 | 공식 문서나 원문 하나를 자세히 읽어야 할 때 |
| `fetch_bulk` | 여러 URL을 병렬로 가져오고 중복·관련도 신호를 정리 | 검색 결과 중 후보 출처를 한 번에 검토할 때 |
| `verify` | 여러 출처의 주장 정렬과 충돌 신호를 보고 | 출처 간 의견이 다르거나 결론을 보수적으로 내려야 할 때 |
| `get_evidence` | 마지막 또는 지정 run의 metadata-only evidence ledger 조회 | 답변 뒤에 어떤 출처를 봤는지 감사해야 할 때 |
| `list_evidence_runs` | 최근 evidence run 목록 조회 | 세션별 조사 기록을 찾아야 할 때 |
| `version` | 현재 패키지 버전 반환 | 설치 상태와 문서 버전을 맞출 때 |
| `list_engines` | 등록된 검색 엔진과 품질 메타데이터 조회 | 엔진 가용성이나 지역별 검색 경로를 확인할 때 |
| `engine_health` | 엔진별 circuit breaker 상태 조회 | 실패가 엔진 장애인지 질의 문제인지 나눠볼 때 |

`search`는 `fast`, `balanced`, `deep` 모드를 지원합니다. `deep`은 더 많은 엔진과 랭킹 단계를
사용하므로 정확도 여지는 커지지만 지연 시간도 늘어납니다. 현재 레지스트리는 검색용 엔진
9개와 fetch 전용 alias를 lazy import로 관리합니다.

## 작동 방식

Maru는 답을 대신 쓰는 제품이 아니라, 답을 쓰는 호스트에게 웹 근거를 공급하는 실행 계층입니다.

1. 호스트가 질의의 범위, 키워드, 출처 우선순위를 정합니다.
2. `search`가 후보 출처를 찾고 랭킹·엔진 메타데이터를 붙입니다.
3. 호스트가 읽을 URL을 고르면 `fetch` 또는 `fetch_bulk`가 본문을 가져옵니다.
4. 출처 간 정렬이 필요하면 `verify`가 support, contradiction, conflict 신호를 냅니다.
5. `get_evidence`와 `list_evidence_runs`는 조사 run의 metadata-only 기록을 남깁니다.
6. 최종 판단, 인용 배치, 사용자 답변은 호스트 에이전트가 수행합니다.

에이전트 규칙에는 보통 이렇게 적습니다.

```text
최신 API, 보안 권고, 가격, 릴리스, 라이브러리 사용법처럼 변할 수 있는 내용은
Maru의 search/fetch 도구로 먼저 확인하고, 출처 번호를 붙여 답변한다.
```

도구 호출 의도는 다음처럼 잡으면 됩니다.

```text
search(query="FastAPI lifespan context manager official docs", mode="balanced", source_scope="docs")
fetch_bulk(urls=["https://fastapi.tiangolo.com/advanced/events/"], query="lifespan")
verify(sources=[...])
```

## 증거와 한계

Maru는 근거를 더 다루기 쉽게 만들지만, 웹 전체의 진실성을 보장하지 않습니다. 운영 계약은 보수적으로 잡습니다.

| 항목 | 계약 |
|:---|:---|
| Evidence ledger | `metadata-only` 기록입니다. URL, 제목, 접근 위험, 추출 품질, 경고, citation metadata를 남깁니다. |
| 저장하지 않는 것 | raw HTML, 원문 body 전체, 쿠키, 토큰, 개인 브라우저 세션 값은 evidence ledger에 저장하지 않습니다. |
| 차단 페이지 | 기본은 일반 HTTP fetch와 안전한 fallback입니다. CAPTCHA나 bot-wall은 접근 위험 metadata로 노출합니다. |
| Rate limiting | 엔진별 자동 rate limiter + circuit breaker가 내장되어 있습니다. `engine_health`로 실시간 상태를 확인할 수 있습니다. 검색 결과에 `_engine_status` 메타데이터가 포함됩니다. |
| Stealth 지원 | 필요한 사용자가 `maru-deep-pro-search[stealth]` extra를 명시적으로 설치합니다. 사이트 정책과 환경 설정을 우회 명분으로 삼지 않습니다. |
| 벤치마크 | 문서의 수치 주장은 재현 명령과 저장된 결과가 있을 때만 유지합니다. 없으면 기능 설명으로 낮춥니다. |
| 판단 책임 | 출처 선택, 충분성 판단, 최종 결론은 호스트가 맡습니다. Maru는 retrieval과 evidence plumbing을 담당합니다. |

상용 검색 API 키 없이 시작할 수 있지만, 대상 사이트의 robots, rate limit, 접근 정책은 여전히 적용됩니다.
Maru는 차단을 숨기지 않고, 실패와 경고를 가능한 한 도구 출력과 evidence metadata에 남기는 쪽을 택합니다.

## 문제 해결

| 증상 | 확인할 것 |
|:---|:---|
| MCP 서버가 에이전트에 보이지 않음 | `maru-deep-pro-search-setup setup --check --json`을 실행하고 에이전트를 완전히 재시작합니다. |
| 설치는 되었지만 오래된 명령이 실행됨 | `which maru-deep-pro-search`와 `maru-deep-pro-search --help`로 PATH를 확인합니다. |
| 첫 검색이 느림 | `maru-deep-pro-search-setup warmup-embeddings -q`로 임베딩 가중치를 미리 받습니다. |
| 특정 엔진만 실패함 | `engine_health`로 circuit breaker 상태를 확인합니다. 자동 복구(15-60s) 후 재시도됩니다. |
| 여러 출처가 서로 충돌함 | `fetch_bulk`로 원문을 다시 읽고 `verify`로 충돌 신호를 분리합니다. |
| 브라우저 기반 fallback이 필요함 | `maru-deep-pro-search-setup browsers --check`로 현재 지원 상태를 먼저 확인합니다. |
| 검색 결과가 부족함 | 쿼리 키워드를 3-8개로 줄이거나, 여러 개의 집중된 쿼리로 분할하세요. |

CLI 도움말도 빠른 진단에 유용합니다.

```bash
maru-deep-pro-search --help
maru-deep-pro-search-setup --help
maru-deep-pro-search-setup setup --list
```

## 기여와 라이선스

기여 문서는 한국어를 기본으로 유지하고, 영어 문서는 같은 의미와 구조를 맞춥니다. 공개 MCP 출력 형식,
도구 목록, evidence 계약을 바꿀 때는 코드, 프로브, README, GitHub Pages를 함께 갱신하세요.

검증은 저장소 정책에 맞춰 Ruff, mypy, build, 실행형 devtools probe, 브라우저 스모크 확인 중 위험도에
맞는 조합을 사용합니다. 별도 테스트 스위트는 이 저장소 정책상 추가하지 않습니다.
공개 문서만 확인할 때는 아래 명령을 사용합니다.

```bash
bash scripts/verify_docs.sh
```

라이선스는 [MIT](./LICENSE)입니다.
