maru-deep-pro-search 0.32.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

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

English · GitHub Pages · PyPI · Issues

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

빠른 시작

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

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

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

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

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

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

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

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

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

maru-deep-pro-search

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

{
  "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. 최종 판단, 인용 배치, 사용자 답변은 호스트 에이전트가 수행합니다.

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

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

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

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 도움말도 빠른 진단에 유용합니다.

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 scripts/verify_docs.sh

라이선스는 MIT입니다.