Aas-ee/open-webSearch

Open‑WebSearch – AI 에이전트를 위한 플러그 앤 플레이 웹 검색 서비스

개요 – Open‑WebSearch는 다양한 공개 검색 엔진(Bing, DuckDuckGo, Baidu, Brave 등)을 쿼리하고 결과를 깔끔하고 구조화된 JSON 형식으로 반환하는 로컬 서버(또는 CLI)를 실행하는 오픈 소스 도구입니다. 또한 개별 페이지의 전체 텍스트(GitHub READMEs, CSDN articles, 일반적인 Markdown/HTML 페이지)를 가져올 수도 있습니다. 이 서비스는 MCP (Model‑Center‑Protocol) 인터페이스를 통해 AI 에이전트(Claude, Cursor 등)에서 사용하도록 설계되었지만, 간단한 명령줄 유틸리티나 장기 실행 HTTP 데몬으로도 작동합니다.

중요성 – 현대의 LLM 기반 에이전트는 종종 웹에서 최신 정보를 필요로 합니다. 대부분의 상용 API는 유료 키와 속도 제한이 필요합니다. Open‑WebSearch는 그 장벽을 제거합니다. API 키 없이 공개 검색 엔진을 스크래핑하며, 제한된 네트워크를 위한 프록시 설정을 지원하고, 사이트가 단순 HTTP 요청을 차단할 때 Playwright를 통한 헤드리스 브라우저로 전환할 수 있습니다. 이는 자율 에이전트, RAG 파이프라인 또는 실시간 웹 조회가 필요한 모든 워크플로우에 실용적인 구성 요소가 됩니다.

작동 방식

• 검색 (Search) – search 엔드포인트는 선택한 엔진에 접속하여 제목, URL, 스니펫을 수집하고 JSON으로 반환합니다. 환경 변수를 통해 기본 엔진을 선택하거나 허용된 목록을 제한할 수 있습니다.
• 가져오기 (Fetch) – 검색 후, fetch‑web (일반 페이지) 또는 특화된 페처(fetchGithubReadme, fetchCsdnArticle 등)를 호출하여 전체 기사 본문을 가져올 수 있습니다. Playwright를 사용할 수 있는 경우, 페처는 JavaScript가 많은 페이지를 렌더링하고 지속적인 브라우저 프로필의 쿠키를 재사용할 수 있습니다.
• 배포 옵션 –
  • MCP 서버 – Claude Desktop, Cherry Studio, VS Code 확장 프로그램 등에 직접 연결합니다.
  • CLI – open-websearch search "latest AI news" --json과 같은 일회성 명령을 실행합니다.
  • 로컬 데몬 – 반복적인 호출을 위한 시작 오버헤드를 줄이기 위해 지속적으로 실행되는 HTTP 서비스(POST /search, POST /fetch‑*)입니다.
  • Docker – 빠르고 격리된 배포를 위한 공식 컨테이너 이미지(ghcr.io/aas-ee/open-web-search)를 제공합니다.
• 설정 (Configuration) – 모든 동작은 환경 변수(기본 엔진, 프록시 설정, CORS, Playwright 모드 등)에로 제어됩니다. 이를 통해 기업용 방화벽에 맞추거나 헤드리스 브라우저 폴백(fallback)을 쉽게 활성화/비활성화할 수 있습니다.

전형적인 사용 사례

1. LLM 에이전트가 *"diffusion models에 대한 최근 논문을 찾아줘."*와 같은 사용자 쿼리를 받습니다.
2. 에이전트는 쿼리와 함께 Open‑WebSearch MCP 도구 search (또는 CLI)를 호출합니다.
3. 서비스는 URL과 스니펫 목록을 반환합니다.
4. 에이전트는 가장 유망한 결과를 선택하고 fetchWebContent (또는 특화된 페처)를 호출하여 전체 텍스트를 가져옵니다.
5. 가져온 콘텐츠를 요약하거나 인용하기 위해 LLM에 다시 전달합니다.

주요 강점

• API 키 불필요 – 공개 검색 엔진과 즉시 사용 가능합니다.
• 멀티 엔진 지원 – 지역이나 언어에 맞는 최적의 엔진을 선택합니다.
• 프록시 인식 – 검열되거나 기업용 네트워크를 위한 내장된 HTTP 프록시 처리를 지원합니다.
• Playwright 폴백 – JavaScript 렌더링이나 쿠키가 필요한 사이트를 처리합니다.
• 에이전트 친화적 – 표준 MCP 도구 인터페이스와 간단한 HTTP API를 제공합니다.

한계점

• 공개 검색 페이지를 스크래핑하는 방식이므로, 과도한 사용은 속도 제한이나 캡차(captcha)를 유발할 수 있습니다.
• 현재 일부 엔진만 구현되어 있으며, Google은 아직 지원되지 않습니다.
• 브라우저 폴백은 별도의 Playwright 설치 또는 기존 원격 브라우저가 필요합니다.

결론 – Open‑WebSearch는 LLM 에이전트와 실생 웹 사이의 가볍고 키가 필요 없는 가교교 역할을 하며, 최신 정보를 필요로 하는 모든 RAG 또는 자율 에이전트 스택에 유용한 구성 요소가 됩니다.

---

빠른 시작

# npx를 통해 서비스를 실행합니다 (설치가 필요 없습니다)
DEFAULT_SEARCH_ENGINE=duckduckgo npx open-websearch@latest

# 또는 반복 호출을 위한 데몬을 시작합니다
npm install -g open-websearch
open-websearch serve   # 그 후 http://localhost:3000 에 POST /search 를 보냅니다

---

추가 읽기 – 상세한 명령 및 환경 변수 옵션은 README의 Features, CLI and Local Daemon, Installation Guide, Docker Deployment 섹션을 참조하십시오.