로컬 웹 검색 MCP 서버

오프라인 우선 MCP 서버로, 웹 검색 및 콘텐츠 가져오기를 제공합니다. 외부 API 키가 필요 없으며, 의도 분류, 선택적 교차 언어 검색, 의미론적 재순위화, 추출적 딥 검색 답변에 로컬 모델을 사용합니다.

기능

• 지속적인 Playwright 브라우저 인스턴스를 사용하는 브라우저 컨텍스트 풀링.

• 상태 추적과 순서가 있는 폴백을 지원하는 구성 가능한 공급자를 통한 웹 검색.

• URL 정규화, 공급자 간 중복 제거, Reciprocal Rank Fusion(RRF)을 사용하는 모든 구성 공급자에 대한 선택적 연합 검색.

• 보수적 휴리스틱, 로컬 분류기 폴백, 버전 관리되는 공급자 프로필을 사용하는 옵트인 의도 인식 검색 라우팅.

• 대상 사이트 쿼리를 위한 도메인 필터링 웹 검색.

• GitHub Raw 및 RSS 빠른 경로와 렌더링된 페이지를 위한 Playwright 폴백을 포함한 HTTP 우선 페이지 가져오기.

• fetch_content에 대한 SSRF 보호: localhost 및 사설 네트워크 대상 차단.

• 검색 및 가져오기 도구에 대한 토큰 버킷 속도 제한.

• SQLite 및 sqlite-vec 기반 의미론적 캐시.

• 로컬 Transformers.js 모델을 사용한 선택적 교차 언어 쿼리 확장.

• Readability, JSDOM, Turndown을 통한 깔끔한 Markdown 추출.

Related MCP server: searxng-mcp

요구 사항

• Node.js 20.9.0 이상.

• npm.

• 설치 중 npm 패키지, Playwright Chromium, 첫 실행 모델 다운로드를 위한 네트워크 액세스.

설치

npm install
npm run build

postinstall 스크립트가 Playwright Chromium을 다운로드합니다. 모델 기반 기능을 처음 사용할 때 Transformers.js가 필요한 모델 파일을 로컬 Hugging Face 캐시에 다운로드합니다. 모델을 로드하는 첫 요청은 느릴 수 있습니다. 이후 요청은 로컬 캐시를 재사용합니다. 가장 가벼운 첫 실행을 위해 ENABLE_CROSSLINGUAL=false를 유지하세요. 명백한 strategy=auto 의도는 의도 분류기를 로드하지 않고 휴리스틱으로 해결됩니다. 모호한 auto 쿼리는 첫 실행 분류기 다운로드를 트리거할 수 있습니다.

MCP 클라이언트 구성

빌드된 서버를 MCP 클라이언트 구성에 추가하세요:

{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": ["path/to/local-websearch-mcp/build/index.js"],
      "env": {
        "RATE_LIMIT_SEARCH_PER_MIN": "10",
        "RATE_LIMIT_FETCH_PER_MIN": "20",
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false",
        "CACHE_DB_PATH": "websearch_cache.db"
      }
    }
  }
}

패키지가 전역으로 설치되었거나 패키지 러너를 통해 사용되는 경우 바이너리 진입점을 사용하세요:

{
  "mcpServers": {
    "websearch": {
      "command": "local-websearch-mcp",
      "args": [],
      "env": {
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false"
      }
    }
  }
}

패키지 러너 기반 클라이언트의 경우, 패키지가 구성된 npm 레지스트리에서 사용 가능해지면 명령은 npx이고 args는 ["-y", "local-websearch-mcp"]로 설정할 수 있습니다.

도구

검색 전략

auto는 의도적으로 옵트인입니다. strategy를 생략하면 이전 버전과의 호환성을 위해 여전히 fallback을 사용합니다. 의미론적 쿼리 캐시는 aggregate 및 auto에 대해 우회됩니다. 쿼리 캐시 키가 아직 실행 전략/공급자 계획별로 네임스페이스되지 않았기 때문입니다. 딥 검색 페이지 콘텐츠는 일반 콘텐츠 캐시를 계속 사용합니다.

SEARCH_PROVIDERS는 허용 목록이자 구성된 공급자 집합입니다. 자동 라우팅은 SEARCH_PROVIDERS에서 생략된 공급자를 활성화하지 않습니다. 라우팅 프로필은 순서와 기본 후보로 선택되는 구성 공급자 수만 변경합니다.

집계 자동 프로필의 경우, 선택된 모든 기본 공급자가 사용 가능한 결과를 반환하지 않는 경우에만 보조 구성 공급자에 연락합니다. 부분적인 기본 성공은 결과 수를 늘리기 위해 요청을 확대하는 대신 수용됩니다. 이는 스크래핑 부하를 제한하고 불필요한 차단/CAPTCHA 노출을 줄입니다.

현재 라우팅 프로필: v1.

이러한 공급자 선호도는 초기 가설일 뿐 영구적인 품질 주장이 아닙니다. 버전이 관리되므로 이후 릴리스에서 결정적 및 실시간 평가 증거를 기반으로 조정할 수 있으며, 서버 전체에 라우팅 조건문을 분산시킬 필요가 없습니다.

의도 인식 검색 인수의 예:

{
  "query": "PostgreSQL connection pooling best practices",
  "strategy": "auto",
  "max_results": 5
}

react.dev 또는 github.com과 같은 대상 검색에는 domain을 사용하세요. 의도 감지는 항상 원래 쿼리를 수신합니다. site:<domain>은 공급자 실행을 위해 나중에만 추가됩니다.

{
  "query": "server components reference",
  "domain": "react.dev",
  "strategy": "auto",
  "max_results": 5
}

클라이언트가 서버가 상위 페이지를 가져와 페이지 텍스트에서 가능한 답변을 추출해야 하는 경우에만 deep=true를 사용하세요. MCP 클라이언트 LLM은 최종 추론과 요약에 대한 책임을 유지합니다.

오래된 감지 날짜가 있는 검색 스니펫에는 짧은 신선도 경고가 포함되어 클라이언트가 오래된 소스를 주의 깊게 처리할 수 있습니다.

연합 검색 인수의 예:

{
  "query": "postgres connection pooling strategies",
  "strategy": "aggregate",
  "max_results": 5
}

fetch_content는 브라우저를 열기 전에 빠른 소스별 경로를 사용합니다:

• GitHub 저장소, blob, tree 및 raw URL은 가능한 경우 raw.githubusercontent.com에서 읽습니다.

• RSS 또는 Atom 피드 URL과 일반적인 블로그/뉴스 피드 경로는 최근 항목의 Markdown 목록으로 변환됩니다.

• 일반 HTML 페이지는 여전히 HTTP 우선 Readability 파싱을 사용하고 Playwright 폴백을 사용합니다.

구성

Docker

npm run docker:build
npm run docker:up

Docker Compose는 SQLite 캐시를 /app/data에 마운트된 명명된 볼륨에 저장하고 Hugging Face 모델을 별도의 명명된 볼륨에 저장합니다. 컨테이너는 CACHE_DB_PATH=/app/data/websearch_cache.db를 설정합니다.

개발

npm run build
npm run typecheck
npm test
npm run smoke:mcp
npm audit --audit-level=moderate
npm pack --dry-run --json

npm run smoke:mcp는 stdio를 통해 컴파일된 서버를 시작하고, 세 가지 web_search 전략 값(fallback, aggregate, auto)을 확인하고, server_status에서 라우팅 진단을 확인하며, fetch_content가 localhost를 차단하는지 확인합니다. 실제 공급자 검색을 수행하지 않으므로 CI가 검색 엔진 HTML/네트워크 가용성과 독립적입니다.

결정적 TR/EN 라우팅 픽스처는 evals/search-routing/queries.jsonl에 있으며 일반 Vitest 스위트에서 실행됩니다. 실제 분류기를 로드하거나 공급자에 연락하지 않고 의도 범위, 보수적 휴리스틱 동작, 모호성 지연 사례, 공급자 허용 목록 적용을 검증합니다.

문제 해결

• 설치 후 시작이 실패하면 npx playwright install chromium을 실행하세요.

• 첫 번째 모델 기반 요청이 느리면 Transformers.js 모델 다운로드가 완료될 때까지 기다린 후 다시 시도하세요.

• 검색 결과가 없으면 SEARCH_PROVIDERS 순서/세트를 변경하거나 직접 fetch_content URL을 시도하세요.

• aggregate 모드가 너무 느리거나 공급자 차단을 유발하면 기본 fallback 전략을 사용하세요.

• auto가 사용 사례에 너무 광범위한 검색 계획을 선택하면 명시적 fallback 또는 aggregate를 사용하세요. 명시적 전략은 auto 플래너를 우회합니다.

• Docker가 Chromium을 찾을 수 없으면 npm run docker:build로 이미지를 다시 빌드하세요.

• 캐시 파일이 프로젝트 루트에 나타나면 CACHE_DB_PATH를 전용 데이터 디렉터리로 설정하세요.

npm 패키징

npm 패키지에는 build/, README.md, LICENSE, SECURITY.md만 포함됩니다. npm pack은 prepack을 통해 npm run build를 실행하므로 패키지에는 로컬 계획 파일, 테스트, 캐시 또는 소스 전용 산출물 대신 컴파일된 JavaScript가 포함됩니다.

보안

신고 지침 및 현재 의존성 감사 노트는 SECURITY.md를 참조하세요.

라이선스

ISC