Aas-ee/open-webSearch

Open‑WebSearch – AI 에이전트를 위한 실시간 웹 검색 (API 키 필요 없음)

무엇인가요

• 로컬에서 실행 가능한 소형 Node‑JS 서비스로, MCP 호환 서버, CLI 도구, 또는 지속적인 HTTP 데몬으로 작동하여 LLM 기반 에이전트가 실시간 웹 검색과 기사 콘텐츠를 가져올 수 있게 합니다.
• Bing, DuckDuckGo, Baidu, Brave, Exa, Startpage, Sogou, HackerNews, CSDN, Juejin 등 다양한 공개 검색 엔진의 결과를 집계하며, GitHub README, CSDN 게시물, 일반 Markdown/HTML 페이지의 전체 텍스트를 가져올 수 있습니다.
• 외부 API 키나 인증이 필요 없으며, 제한된 사이트에 접근해야 하는 경우에만 HTTP 프록시가 선택적으로 필요합니다.

주요 기능

• 다중 엔진 검색 – 기본 엔진을 선택하거나 사용자가 선택할 수 있으며, ALLOWED_SEARCH_ENGINES를 통해 허용된 엔진을 제한할 수 있습니다.
• 구조화된 출력 – 각 결과에는 제목, URL, 설명이 포함되어 LLM 소비에 적합합니다.
• 콘텐츠 가져오기 – CSDN, GitHub README, Juejin, 일반 웹 페이지용 전용 가져오기 명령어를 제공하며, 향후 다른 블로그도 추가 예정입니다.
• 세 가지 실행 방식
  1. MCP 서버 – Claude Desktop, Cherry Studio, Cursor 등에 연결 가능.
  2. CLI – open-websearch search "prompt"와 같은 단일 명령어.
  3. 로컬 데몬 – 지속적인 HTTP 서비스로 GET /health, POST /search, POST /fetch‑*를 노출합니다.
• 프록시 지원 – 설치 시 (npm --proxy …) 및 런타임 (USE_PROXY=true PROXY_URL=…) 설정이 별도로 가능합니다.
• 옵션 Playwright 통합 – 설치 시, 단순 HTTP 요청을 차단하는 사이트(예: Bing의 봇 방지 페이지 또는 JavaScript 중심 페이지)에 대해 헤드리스 Chromium 브라우저로 대체할 수 있습니다. 모드는 강제(SEARCH_MODE=request 또는 playwright) 또는 자동 감지로 설정 가능합니다.
• 환경 변수를 통한 고도 조정 – CORS 처리부터 MCP용 사용자 정의 도구 이름, 지속 브라우저 프로필 위치까지 모든 설정이 환경 변수로 가능합니다.

일반적인 사용 패턴

시나리오	추천 진입점
스크립트나 터미널에서 단발 검색	npx open-websearch@latest search "my query" --json
안정적인 엔드포인트가 필요한 에이전트 (예: Claude Desktop)	open-websearch serve (또는 npm run serve)를 실행하고 에이전트의 MCP 설정을 http://localhost:3000/mcp로 지정
다른 프로그램에서 반복 호출	데몬을 한 번 시작 (open-websearch serve)하고 POST /search 또는 MCP 도구 이름 (search, fetchWebContent, …) 사용
방화벽 뒤 환경	데몬 시작 전에 USE_PROXY=true 및 PROXY_URL=http://127.0.0.1:7890 설정

설치 및 시작 방법

# 빠른 시작 – 빌드 필요 없음
npx open-websearch@latest               # 기본 모드(_STDIO_) 실행

# 데몬이나 MCP 서버가 필요할 경우
npm install -g open-websearch          # 글로벌 설치
npm run build                           # TypeScript 소스 컴파일
open-websearch serve                    # HTTP 데몬 시작 (기본 포트 3000)
open-websearch status --json            # 정상 작동 여부 확인

더 나은 페이지 렌더링을 위한 Playwright 추가 (JavaScript 기반 사이트에 추천):

npm install playwright               # Playwright 및 번들된 Chromium 설치
npx playwright install chromium
SEARCH_MODE=auto npx open-websearch@latest   # 데몬이 필요 시 브라우저 사용

또한 PLAYWRIGHT_CDP_ENDPOINT로 기존 Chrome/Chromium 인스턴스나 PLAYWRIGHT_WS_ENDPOINT로 원격 Playwright 서버에 연결할 수 있습니다.

설정 요약

• DEFAULT_SEARCH_ENGINE – 기본 엔진 선택 (예: duckduckgo).
• ENABLE_CORS – 데몬이 브라우저에서 호출될 경우 true로 설정.
• MCP_TOOL_SEARCH_NAME – MCP 노출 search 도구의 이름을 변경하거나 비활성화.
• PLAYWRIGHT_HEADLESS – 디버깅 시 브라우저를 보고 싶다면 false로 설정.
• OPEN_WEBSEARCH_PROFILE_DIR – 지속 브라우저 프로필 저장 위치; 이 폴더를 삭제하면 쿠키/캐시가 삭제됩니다.

AI 에이전트에게 중요한 이유

• LLM(Claude, GPT 등)은 일반적으로 정적 지식에 국한되지만, Open‑WebSearch는 실시간으로 키 없이 오픈 인터넷에 접근할 수 있는 다리가 됩니다.
• MCP 인터페이스 덕분에 커스텀 코드 없이 기존 에이전트 생태계에 직접 통합 가능합니다.
• 완전히 로컬에서 실행 가능하므로 데이터는 온프레미스에 유지되며, 제3자 API 비용이나 레이트 제한을 피할 수 있습니다.

로드맵 (README에 기재됨)

• Google 및 기타 주요 검색 엔진 추가.
• 지원하는 블로그, 포럼, 소셜 플랫폼 확장.
• 기사 추출 품질 향상 및 더 많은 사이트 전용 가져오기 도구 추가.

---

위 모든 정보는 리포지토리의 README에서 직접 가져왔으며, 추가 기능은 추측되지 않았습니다.