web-search-mcp

완전 로컬, 제로 외부 API, 제로 키 올인원 MCP 도구로, DeepSeek Harness + LM Studio에 다음을 제공합니다:

1. 웹 검색 — 중국 본토에서 직접 접근 가능한 검색 엔진 결과 페이지(바이두 / 빙 중국판 / 360 / 소거우)를 직접 크롤링, 어떤 검색 API도 호출하지 않음;

2. 전체 페이지 파싱 — Crawl4AI(로컬 Chromium)로 웹페이지 구조 + 텍스트 + 이미지 추출;

3. 이미지 설명 — 로컬 LM Studio 비전 모델로 이미지를 중국어 텍스트 설명으로 변환(이미지 이해는 서버 측에서 발생하므로 DSH가 바이너리 이미지를 버리는 제한을 우회).

다섯 개의 MCP 도구:

크롤링된 markdown은 기본적으로 3중 노이즈 제거가 적용됩니다: ①PruningContentFilter 필터 버전(사용 가능 시); ②상단 내비게이션 바 제거 + 푸터/저작권/광고 노이즈 라인 삭제; ③max_chars 상한(기본 20000자, 초과 시 잘림). 광고 등 무효 콘텐츠가 컨텍스트를 불필요하게 차지하는 것을 방지합니다.

llm_extract는 로컬 LLM으로 본문 추출을 완전히 해결합니다: ①규칙으로 웹페이지 필터링 → ②SMALL_MODEL(소형 모델)로 청크별 빠른 핵심 추출 → ③LARGE_MODEL(대형 모델)로 일관된 요약 집계.

⚠️ 모델 전환으로 VRAM 절약(기본값): config.py에서 model_switching=true일 때 단일 인스턴스 순차 전환 — 소형 모델이 필요하면 자동으로 qwen3.5-4b로 전환(추론 비활성화), 처리 완료 후 다시 대형 모델 qwen/qwen3.8-27b로 전환해 요약, 동시에 하나의 모델만 로드하여 VRAM 부족 방지. false로 설정하면 이중 인스턴스 병렬 사용(충분한 VRAM 필요).

설정 파일(여기만 수정하면 됩니다)

모든 가변 설정은 **config.py**에 집중되어 있으며, 향후 유지보수는 이 파일 하나만 수정하면 됩니다:

환경 변수(예: DSH cordis.patch.yml의 env 섹션)로도 config.py의 기본값을 덮어쓸 수 있지만, 일상적으로는 config.py만 수정하면 됩니다. 수정 후 DSH를 재시작하면 적용됩니다.

아키텍처

                    ┌──────────────────────────────┐
                    │  web-search-mcp (本进程)        │
关键词 ─────────────►│  1. 抓取 百度/必应/360/搜狗 结果页 │──► 搜索结果(标题/URL/摘要)
                    │  2. Crawl4AI 整页解析           │──► markdown / links / images
                    │  3. 下载图片 ─► LM Studio 视觉模型 │──► 图片中文描述(文本)
                    └──────────────────────────────┘
                              ▲ MCP stdio
                    ┌─────────┴──────────┐
                    │ DeepSeek Harness    │  (cordis.yml 里的 @deepseek-ai/dsh-mcp-client)
                    │ LM Studio(主模型)    │
                    └────────────────────┘

• 검색, 크롤링, 이미지 설명이 모두 로컬에서 완료됩니다; 유일한 네트워크 접근은 "웹페이지 자체를 여는 것"(어떤 온라인 검색도 피할 수 없음), 제3자 API 없음, 키 없음, 데이터가 로컬을 벗어나지 않음.

• 이미지 설명은 서버 측 비전: Crawl4AI는 이미지 URL을 추출하는 역할만 하고, 이 도구가 이미지를 다운로드하여 LM Studio의 비전 모델을 호출, 이미지를 텍스트로 변환한 후 DSH에 반환합니다. 따라서 바이너리 이미지를 버리는 DSH의 MCP 브리지 계층은 문제가 되지 않습니다.

설치

1. 환경

• Python 3.10+ (Crawl4AI는 3.11 / 3.12 권장; 3.13에서 의존성 문제 발생 시 3.12로 롤백 가능)

• Docker 설치 여부는 선택 사항(이 프로젝트는 Docker 불필요; SearXNG도 필수가 아님, 검색은 직접 크롤링으로 처리)

• LM Studio가 실행 중이고 모델이 로드되어 있어야 함

2. 의존성 설치(중국 본토는 미러 사용)

cd web-search-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

# 下载 Crawl4AI 用的 Chromium(仅抓取功能需要;只用搜索可跳过)
playwright install chromium

의존성 설명: httpx + beautifulsoup4 필수(검색 + MCP 전송); lxml 선택 사항(미설치 시 표준 라이브러리로 자동 폴백); crawl4ai는 크롤링 기능에만 필요. MCP 전송 계층은 Python 표준 라이브러리만으로 직접 작성되어 mcp/pydantic에 의존하지 않으므로, 최악의 경우 httpx + beautifulsoup4만 설치해도 검색이 가능합니다.

3. LM Studio 비전 모델 설정(선택 사항이지만, 이미지 설명을 하려면 필수)

LM Studio에서 이미지 입력을 지원하는 비전 모델을 로드하세요(예: Qwen2.5-VL-7B-Instruct, MiniCPM-V, LLaVA).

환경 변수 설정(또는 .env에 작성, 단 이 도구는 .env를 자동으로 읽지 않으므로 시작 명령에서 설정하세요):

⚠️ 단일 인스턴스 vs 이중 인스턴스: LM Studio는 일반적으로 동시에 하나의 모델만 로드합니다. 메인 대화 모델이 비전 모델이 아니라면, LM Studio 인스턴스를 하나 더 열어(포트 변경, 예: 1235) 비전 모델을 전용으로 로드하고, VISION_BASE_URL을 http://localhost:1235/v1로 지정하는 것을 권장합니다.

DeepSeek Harness 연동

cordis.yml의 플러그인 목록에 다음을 추가하세요(예시는 cordis.example.yml 참조):

- id: mcp-websearch
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: websearch
    transport: stdio
    command: python
    args: ['C:/Users/LiangYuelin/Desktop/workspace/web-search-mcp/server.py']
    cwd: 'C:/Users/LiangYuelin/Desktop/workspace/web-search-mcp'
    env:
      VISION_BASE_URL: 'http://localhost:1234/v1'
      VISION_MODEL: 'qwen2.5-vl-7b-instruct'
      VISION_API_KEY: 'lm-studio'
    toolCallTimeoutMs: 300000   # 抓取 + 图片描述较慢,务必调大

• venv를 사용 중이라면 command를 .venv/Scripts/python.exe(절대 경로)로 변경하세요.

• 연동 후 모델에 세 개의 도구가 표시됩니다: mcp__websearch__search_web, mcp__websearch__scrape_url, mcp__websearch__search_and_extract.

사용 예시

모델 측에서 자연스럽게 도구를 호출합니다. 예:

• "『대형 모델 RAG 최신 동향』을 검색해줘" → search_web(query="대형 모델 RAG 최신 동향", engine="bing")

• "이 웹페이지를 크롤링해서 파싱하고, 안에 있는 이미지가 무엇인지 알려줘" → scrape_url(url="https://...", describe_images=true)

• "『비트코인 시세』를 검색하고 상위 3개 기사를 요약해줘" → search_and_extract(query="비트코인 시세", engine="bing", max_results=3)

검색 엔진 선택:

배포 상태(로컬)

완료되었고 로컬에서 실측 검증 완료:

• 의존성 설치 완료: crawl4ai 0.9.2 + playwright + lxml + Chromium(중국 미러 경유);

• DSH 설정이 ~/.dsh/profiles/web/cordis.patch.yml에 작성됨;

• 네 개의 검색 엔진(바이두/빙/360/소거우) 모두 결과 반환;

• 바이두 리다이렉트 링크 정상 복원;

• MCP stdio 프로토콜 전체 동작 확인(initialize / tools/list / tools/call / 오류 처리 / 중국어 UTF-8);

• scrape_url(전체 페이지 markdown + links + 이미지) 및 search_and_extract(검색→복원→크롤링→이미지 추출) 엔드투엔드 통과.

유일하게 남은 수동 단계(이미지 설명에 필요):

1. LM Studio 열기 → 로컬 서비스 시작(포트 1234);

2. 비전 모델 qwen/qwen3.8-27b 로드(mmproj 포함, 이미지 입력 지원);

3. DSH 재시작(dsh web), 모델에서 mcp__websearch__* 세 개의 도구를 확인할 수 있음.

파일 설명

• server.py —— MCP 서비스 진입점(직접 작성한 MCP stdio, mcp/pydantic 의존성 제로)

• engines.py —— 검색 엔진 크롤링 모듈(바이두/빙/360/소거우)

• vision.py —— LM Studio 비전 모델 이미지 설명

• cache.py —— 디스크 캐시 모듈(크롤링 결과 / 이미지 설명 재사용, 순수 표준 라이브러리)

• config.py —— 중앙 집중 설정(모든 가변 항목)

• requirements.txt —— 의존성

• .env.example —— 비전 모델 환경 변수 예시

• cordis.example.yml —— DSH 연동 설정 예시

성능 최적화(경로 A · 적용 완료)

20GB VRAM + 32GB 메모리 로컬 환경을 위해 새로운 대형 모델 추가 없이 네 가지 최적화를 적용했습니다:

F5는 선택 의존성 Pillow 필요(requirements.txt에 포함); 미설치 시 다운샘플링을 자동으로 건너뛰며 나머지 기능은 영향 없음. 캐시 디렉터리는 기본적으로 프로젝트 내 .cache/; CACHE_ENABLED=false로 설정하면 전체 비활성화.

알려진 제한 사항

• 검색 결과에 가끔 광고가 포함될 수 있음(바이두 baidu.php?url=...는 광고 링크로 복원 불가, 크롤링 시 건너뛰거나 오류 발생, 정상적인 동작);

• 검색 엔진 안티크롤링으로 인해 간헐적 실패 가능, 다른 엔진으로 전환하면 됨;

• 대형 페이지 / 다중 이미지 크롤링 시 느릴 수 있으므로, 반드시 DSH 설정에서 toolCallTimeoutMs를 늘리세요;

• 이미지 설명 품질은 로컬 비전 모델 자체에 달려 있습니다.