MCP 딥웹 연구 서버(v0.3.0)

고급 웹 연구를 위한 MCP(Model Context Protocol) 서버입니다.

특징

지능형 검색 대기열 시스템
- 속도 제한을 사용한 일괄 검색 작업
- 진행 상황 추적을 통한 대기열 관리
- 오류 복구 및 자동 재시도
- 검색 결과 중복 제거
향상된 콘텐츠 추출
- TF-IDF 기반 관련성 점수
- 키워드 근접 분석
- 콘텐츠 섹션 가중치
- 가독성 점수
- 개선된 HTML 구조 파싱
- 구조화된 데이터 추출
- 더 나은 콘텐츠 정리 및 서식
핵심 기능
- Google 검색 통합
- 웹페이지 콘텐츠 추출
- 연구 세션 추적
- 향상된 서식을 사용한 마크다운 변환

필수 조건

Node.js >= 18 ( npm 및 npx 포함)
클로드 데스크톱 앱

설치

Smithery를 통해 설치

Smithery 를 통해 Claude Desktop용 Deep Web Research Server를 자동으로 설치하려면:

지엑스피1

글로벌 설치(권장)

# Install globally using npm
npm install -g mcp-deepwebresearch

# Or using yarn
yarn global add mcp-deepwebresearch

# Or using pnpm
pnpm add -g mcp-deepwebresearch

로컬 프로젝트 설치

# Using npm
npm install mcp-deepwebresearch

# Using yarn
yarn add mcp-deepwebresearch

# Using pnpm
pnpm add mcp-deepwebresearch

Claude 데스크톱 통합

패키지를 설치한 후 claude_desktop_config.json 에 다음 항목을 추가하세요.

윈도우

{
  "mcpServers": {
    "deepwebresearch": {
      "command": "mcp-deepwebresearch",
      "args": []
    }
  }
}

위치: %APPDATA%\Claude\claude_desktop_config.json

맥OS

{
  "mcpServers": {
    "deepwebresearch": {
      "command": "mcp-deepwebresearch",
      "args": []
    }
  }
}

위치: ~/Library/Application Support/Claude/claude_desktop_config.json

이 구성을 사용하면 Claude Desktop이 필요할 때 웹 연구 MCP 서버를 자동으로 시작할 수 있습니다.

첫 번째 설정

설치 후 다음 명령을 실행하여 필요한 브라우저 종속성을 설치합니다.

npx playwright install chromium

용법

Claude와 채팅을 시작하고 웹 리서치에 도움이 될 만한 메시지를 보내세요. 심층적인 웹 리서치에 맞춰 미리 만들어진 프롬프트를 원하시면 이 패키지를 통해 제공되는 agentic-research 프롬프트를 사용하실 수 있습니다. Claude 데스크톱에서 채팅 입력란의 페이퍼클립 아이콘을 클릭한 다음, Choose an integration → deepwebresearch → agentic-research 선택하여 해당 프롬프트에 접속하세요.

도구

deep_research
- 콘텐츠 분석을 통해 포괄적인 연구를 수행합니다.
- 인수:
  { topic: string; maxDepth?: number; // default: 2 maxBranching?: number; // default: 3 timeout?: number; // default: 55000 (55 seconds) minRelevanceScore?: number; // default: 0.7 }
- 보고:
  { findings: { mainTopics: Array<{name: string, importance: number}>; keyInsights: Array<{text: string, confidence: number}>; sources: Array<{url: string, credibilityScore: number}>; }; progress: { completedSteps: number; totalSteps: number; processedUrls: number; }; timing: { started: string; completed?: string; duration?: number; operations?: { parallelSearch?: number; deduplication?: number; topResultsProcessing?: number; remainingResultsProcessing?: number; total?: number; }; }; }
parallel_search
- 지능형 대기열을 통해 여러 Google 검색을 병렬로 수행합니다.
- 인수: { queries: string[], maxParallel?: number }
- 참고: maxParallel은 안정적인 성능을 보장하기 위해 5로 제한됩니다.
visit_page
- 웹 페이지를 방문하여 콘텐츠 추출
- 인수: { url: string }
- 보고:
  { url: string; title: string; content: string; // Markdown formatted content }

프롬프트

`agentic-research`

클로드가 철저한 웹 조사를 수행하는 데 도움이 되는 가이드 조사 프롬프트입니다. 이 프롬프트는 클로드에게 다음을 지시합니다.

주제 환경을 이해하려면 광범위한 검색으로 시작하세요.
고품질의 권위 있는 출처를 우선시하세요
연구 결과를 바탕으로 연구 방향을 반복적으로 개선합니다.
귀하에게 정보를 제공하고 대화형으로 연구를 안내합니다.
항상 URL을 사용하여 출처를 인용하세요

구성 옵션

서버는 환경 변수를 통해 구성할 수 있습니다.

MAX_PARALLEL_SEARCHES : 동시 검색 최대 수 (기본값: 5)
SEARCH_DELAY_MS : 검색 간 지연 시간(밀리초) (기본값: 200)
MAX_RETRIES : 실패한 요청에 대한 재시도 횟수(기본값: 3)
TIMEOUT_MS : 요청 시간 초과(밀리초) (기본값: 55000)
LOG_LEVEL : 로깅 레벨(기본값: 'info')

오류 처리

일반적인 문제

속도 제한
- 증상: "요청이 너무 많습니다" 오류
- 해결 방법: SEARCH_DELAY_MS 늘리거나 MAX_PARALLEL_SEARCHES 줄이세요.
네트워크 시간 초과
- 증상: "요청 시간 초과" 오류
- 솔루션: 요청이 60초 MCP 시간 초과 내에 완료되도록 보장
브라우저 문제
- 증상: "브라우저를 시작하지 못했습니다" 오류
- 해결 방법: Playwright가 제대로 설치되었는지 확인하세요( npx playwright install )

디버깅

베타 소프트웨어입니다. 문제가 발생할 경우:

Claude Desktop의 MCP 로그를 확인하세요.
# On macOS tail -n 20 -f ~/Library/Logs/Claude/mcp*.log # On Windows Get-Content -Path "$env:APPDATA\Claude\logs\mcp*.log" -Tail 20 -Wait
디버그 로깅 활성화:
export LOG_LEVEL=debug

개발

설정

# Install dependencies
pnpm install

# Build the project
pnpm build

# Watch for changes
pnpm watch

# Run in development mode
pnpm dev

테스트

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

코드 품질

# Run linter
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type check
pnpm type-check

기여하다

저장소를 포크하세요
기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
브랜치에 푸시( git push origin feature/amazing-feature )
풀 리퀘스트 열기

코딩 표준

TypeScript 모범 사례를 따르세요
테스트 커버리지를 80% 이상으로 유지
새로운 기능 및 API 문서화
중요한 변경 사항이 있는 경우 CHANGELOG.md를 업데이트하세요.
의미적 버전 관리를 따르세요

성능 고려 사항

가능한 경우 일괄 작업을 사용하세요
적절한 오류 처리 및 재시도를 구현합니다.
대용량 데이터 세트의 메모리 사용량을 고려하세요
적절한 경우 캐시 결과
대용량 콘텐츠에 스트리밍을 사용하세요

요구 사항

노드.js >= 18
Playwright(종속성으로 자동 설치됨)

검증된 플랫폼

[x] 맥OS
[x] 윈도우
[ ] 리눅스

특허

MIT

크레딧

이 프로젝트는 mzxrai 가 개발한 mcp-webresearch 의 훌륭한 작업을 기반으로 합니다. 원본 코드베이스는 향상된 기능과 성능의 기반을 제공했습니다.

작가

qpd-v

MCP Deep Web Research Server

Integrations