web-search-mcp

로컬 LLM을 위한 외부 웹 검색 및 페이지 가져오기 기능으로, MCP 도구 및 CLI로 노출됩니다. 구현은 Playwright 우선, 비동기 방식이며 기본적으로 시스템에 설치된 Chromium 바이너리를 실행합니다. 설계 이력은 docs/IMPLEMENTATION_PLAN.md에 문서화되어 있습니다.

도구

• search(provider, context)는 duckduckgo(기본값), google 또는 yandex에서 브라우저 기반 검색을 실행하고 최대 5개의 유기적 결과 URL을 반환합니다.

• fetch(urls)는 1..5개의 URL을 가져와 URL별 pages, errors, truncated 필드가 포함된 브라우저 렌더링 HTML을 반환합니다.

context는 호출자 호환성을 위해 의도적으로 검색 쿼리 문자열로 설정되었습니다.

Related MCP server: Web Search MCP

설정

uv sync
chromium --version

Chromium이 표준이 아닌 위치에 설치된 경우 PLAYWRIGHT_CHROMIUM_EXECUTABLE=/path/to/chromium을 설정하세요.

사용법

stdio를 통해 MCP 서버 실행:

uv run web-search serve-mcp

CLI 직접 실행:

uv run web-search search --context "python async playwright"
uv run web-search fetch https://example.com

stdio 대신 HTTP 전송 노출:

uv run web-search serve-mcp --transport streamable-http --host 127.0.0.1 --port 8000

설계 참고 사항

• 프로세스당 하나의 공유 브라우저를 사용하며, 요청마다 새로운 시크릿 컨텍스트를 사용합니다.

• Playwright는 Playwright가 다운로드한 브라우저 번들이 아닌 시스템 Chromium 바이너리를 실행합니다.

• 시스템 Chromium은 Playwright와 잘 작동하지만, 테스트된 시스템 Firefox 빌드는 실행 직후 종료되었습니다. 따라서 이 저장소는 지원되는 호스트 브라우저 경로로 시스템 Chromium을 대상으로 합니다.

• 브라우저 스모크 테스트는 일반 호스트 셸에서 실행해야 합니다. 제한된 샌드박스는 호스트 브라우저가 올바르게 작동하더라도 Chromium 시작을 차단할 수 있습니다.

• 전역 탐색 동시성 제한은 3입니다.

• 시간 제한: 페이지당 15s, search 총 20s, fetch 총 35s.

• SSRF 방지: http/https만 허용, 포함된 자격 증명 없음, 탐색 전 및 브라우저 하위 요청 시 루프백/사설/링크 로컬/예약된 IP 차단.

• JavaScript 챌린지 페이지에는 10s의 제한된 대기 시간이 주어지며, CAPTCHA 해결, 스텔스 핑거프린팅 또는 사이트별 우회 로직은 없습니다.

• HTML은 URL당 1 MiB로 제한되며, 크기가 초과된 응답은 잘리고 truncated 필드에 보고됩니다.

• v1에서는 robots.txt를 참조하지 않습니다.

개발

source .venv/bin/activate
pytest

파서 테스트는 저장된 HTML 픽스처에 대해 실행되며, 선택자 드리프트는 예상되는 유지 관리 비용입니다.