dsh-google-chrome-search

DeepSeek Harness (DSH) 플러그인으로, AI 에이전트가 CDP(Chrome DevTools Protocol)를 통해 로컬 Chrome 브라우저를 구동하여 실제 Google 웹 검색을 실행하고, 모든 페이지를 렌더링하여 콘텐츠를 추출할 수 있게 해줍니다. 검색 API 키가 필요 없습니다 — 머신에 이미 설치된 Chrome으로 동작합니다.

Google은 자동화 및 데이터센터 트래픽에 대해 사람 확인 페이지(CAPTCHA / "비정상적인 트래픽")를 자주 제공합니다. 이런 경우 이 플러그인은 보이는 Chrome 창을 열어 확인 페이지를 표시하고, 사람이 해결할 때까지 대기한 후, 이제 신뢰된 세션에서 결과를 추출합니다. 이것이 "사람에게 묻기" 단계입니다 — 설계상 에이전트는 절대 CAPTCHA를 스스로 해결하려 하지 않습니다.

구성 요소

Related MCP server: browser-search-mcp

요구 사항

• Node.js ≥ 18 (Node 22에서 테스트됨)

• 로컬 Chrome/Chromium 바이너리 (예: google-chrome, chromium). 일반적인 경로에서 자동 감지되며, CHROME_PATH 또는 --chrome으로 재정의할 수 있습니다.

• 보이는 확인 단계를 위해 디스플레이가 있는 데스크톱 세션이 필요합니다(Chrome 창을 사람에게 표시할 수 있어야 함). 헤드리스/SSH에서도 CAPTCHA를 감지하고 (스크린샷과 함께) 보고할 수 있습니다.

설치

git clone https://github.com/davidcastilloalvarado/dsh-google-chrome-search.git
cd dsh-google-chrome-search
npm install

의존성: puppeteer-core (여러분의 Chrome을 구동 — 브라우저를 다운로드하지 않음), @modelcontextprotocol/sdk (MCP 서버용), @mozilla/readability (콘텐츠 추출), zod (스키마 검증).

선택적으로 CLI를 전역에 링크하여 PATH에 포함시킬 수 있습니다:

npm link        # gives you: dsh-google-search "<query>"

CLI 사용

# Search:
node bin/google-search.mjs "nodejs streams" --max 8
# or, after npm install / npm link:
npm run search -- "nodejs streams" --json

# Search, then render + extract the top 3 result pages:
node bin/google-search.mjs "nodejs streams" --max 8 --fetch-top 3 --fetch-max-chars 8000

# Fetch one URL directly (render + extract readable content):
node bin/google-search.mjs fetch "https://nodejs.org/api/stream.html" --max-chars 8000

종료 코드: 0 = 성공 (결과 / 가져온 콘텐츠), 2 = 확인 필요 (CAPTCHA), 3 = 결과 없음 / 가져오기 차단 또는 실패, 1 = 오류, 64 = 사용법 오류.

페이지 가져오기 (렌더링 + 추출)

이 플러그인은 모든 URL을 렌더링하고 읽을 수 있는 주요 콘텐츠를 추출할 수도 있습니다:

• 동일한 전용 Chrome 프로필에서 페이지를 실행합니다(일관되고 신뢰된 지문을 보는 사이트가 더 잘 동작하도록).

• 페이지가 완전히 로드될 때까지 대기합니다(늦은 SPA 콘텐츠 포함).

• 라이브 페이지 내부에서 실행되는 Mozilla Readability로 기사를 추출합니다. 페이지에 뚜렷한 기사가 없으면 전체 페이지 텍스트로 대체합니다.

• 출력 상한(페이지당 기본 8,000자)으로 에이전트 컨텍스트에 친화적으로 유지합니다.

• 안티봇 벽을 감지하고 쓰레기를 반환하는 대신 blocked로 보고합니다. 사이트가 사람 확인 챌린지(예: DataDome의 "슬라이드하여 계속하기" 벽)를 제공하면 페이지가 있는 보이는 Chrome 창을 열고, 사람이 통과할 때까지 verifyTimeoutMs 동안 대기한 후 실제 콘텐츠를 추출합니다 — Google CAPTCHA 흐름과 동일한 사람에게 위임하는 철학입니다. 신뢰된 세션 쿠키는 프로필에 유지되므로 해당 사이트의 이후 페이지는 일반적으로 헤드리스로 통과합니다. --no-verify / autoVerify: false를 사용하면 blocked로만 보고합니다.

dsh-google-search fetch "https://example.com/article" --max-chars 10000
dsh-google-search fetch "https://example.com/article" --html --screenshot

검색과 읽기를 결합하는 두 가지 방법:

페이지는 순차적으로 렌더링됩니다(브라우저 하나, 페이지 한 번에 하나) — 페이지당 ~1–3초가 소요됩니다.

네이티브 DSH 도구로 사용 (MCP)

프로필 구성에서 DSH의 @deepseek-ai/dsh-mcp-client로 MCP 서버를 등록합니다 (예시 — command 및 args 경로를 환경에 맞게 조정):

- insert:
    - id: mcp-google
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: google
        transport: stdio
        command: /path/to/node
        args: [ /path/to/dsh-google-chrome-search/src/server.mjs ]
        env:
          CHROME_PATH: /usr/bin/google-chrome   # optional — auto-detected if unset
        toolCallTimeoutMs: 300000

DSH를 재시작하면 에이전트가 세 가지 네이티브 도구를 사용할 수 있습니다:

참고:

• 호출은 직렬화됩니다 (Chrome은 프로필당 하나의 프로세스만 허용), 따라서 동시 도구 호출은 병렬로 실행되지 않고 대기열에 들어갑니다.

• search_and_fetch는 일반 검색보다 느립니다: 위에 표시된 대로 toolCallTimeoutMs를 300000(5분)으로 유지하세요.

• 사람 확인 흐름은 Google 검색(CAPTCHA)과 브라우저를 차단하는 결과 페이지(안티봇 슬라이더) 모두에 적용됩니다: 사람을 위해 보이는 Chrome 창이 열리고, 이후 세션은 프로필에 유지됩니다.

DSH 스킬로 사용

skill/SKILL.md는 에이전트에게 검색 실행 방법과 CAPTCHA를 사람에게 넘겨주는 방법을 교육합니다. 설치하려면 DSH 스킬 디렉토리에 복사하세요, 예:

mkdir -p ~/.dsh/skills/google-chrome-search
cp skill/SKILL.md ~/.dsh/skills/google-chrome-search/

다른 머신에서 공유/사용하기 전에 SKILL.md 내부의 <INSTALL_DIR> 자리 표시자를 이 저장소를 클론한 위치로 편집하세요 (또는 npm link CLI를 PATH에 넣으면 바로 작동합니다).

구성 (환경 변수 / 옵션)

사람 확인 흐름, 단계별

1. Chrome이 헤드리스로 검색을 실행합니다 (전용 격리 프로필 — 절대 실제 브라우저가 아님).

2. 결과가 있으면 → 반환합니다 (status: ok).

3. Google이 CAPTCHA를 제공하면:

   • 스크린샷을 찍습니다.

   • 확인 페이지에서 보이는 Chrome 창을 엽니다 (동일 프로필).

   • 페이지를 폴링하면서 사람이 해결할 때까지 verifyTimeoutMs 동안 대기합니다.

   • 해결되면 → 결과를 추출 + 반환합니다 (verifiedViaHuman: true 표시). 시간 초과되면 → 최신 스크린샷과 함께 status: verification_required를 반환합니다.

4. 확인된 세션은 프로필에 유지되므로 다음 검색은 일반적으로 헤드리스로 성공합니다.

테스트

npm test

MCP 서버를 생성하고 search, fetch, search_and_fetch 도구가 나열되는지 확인하며, 머신에 Chrome 바이너리가 있으면 autoVerify: false로 라이브 검색을 수행합니다. 브라우저가 없는 환경(예: CI)에서는 라이브 호출이 정상적으로 건너뜁니다.

문제 해결

되돌리기 / 정리

• 구성: DSH 프로필 구성에서 mcp-google 항목을 제거하세요.

• 스킬: rm -rf ~/.dsh/skills/google-chrome-search

• 프로필/스크린샷: rm -rf ~/.dsh-chrome-google

라이선스

MIT