npm package: @leeseokwoon/mcp-websearch
Description: Real-time web search MCP server with no robots.txt restrictions
Author: Your Name
Latest version: 1.0.0

# MCP WebSearch

무제약 실시간 웹 검색 MCP 서버 - robots.txt 제약 없이 최신 정보를 LLM에게 제공합니다.

## 특징

- ✅ **무제약 접근**: robots.txt 제약 없이 모든 사이트 크롤링
- ✅ **실시간 검색**: DuckDuckGo HTML 기반 웹 검색
- ✅ **SPA 지원**: JavaScript 렌더링 완벽 지원 (Puppeteer)
- ✅ **본문 추출**: Mozilla Readability로 깨끗한 텍스트 추출
- ✅ **스마트 캐싱**: 6시간 TTL 메모리 캐시로 성능 최적화
- ✅ **다중 LLM 호환**: Claude, Gemini 등 MCP 지원 LLM에서 사용 가능

## 테스트 완료

```bash
npm run build
node test-manual.js

# 결과:
# web_search: ✅ 통과
# extract_url: ✅ 통과
# 🎉 모든 테스트 통과! MCP 서버가 정상 작동합니다.
```

## 설치

### 필수 요구사항

- Node.js 18 이상
- npm 또는 yarn

### 1. 프로젝트 클론 및 빌드

```bash
git clone <repository-url> mcp-websearch
cd mcp-websearch

# 의존성 설치
npm install

# TypeScript 빌드
npm run build
```

### 2. MCP 설정

#### Claude Desktop (macOS)

설정 파일: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": [
        "/절대/경로/mcp-websearch/dist/index.js"
      ]
    }
  }
}
```

#### Claude Desktop (Windows)

설정 파일: `%APPDATA%\\Claude\\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": [
        "C:\\절대\\경로\\mcp-websearch\\dist\\index.js"
      ]
    }
  }
}
```

#### Claude Code

설정 파일: `~/.config/claude/config.json`

```json
{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": [
        "/절대/경로/mcp-websearch/dist/index.js"
      ]
    }
  }
}
```

#### NPX 실행 (권장)

NPM에 배포 후:

```json
{
  "mcpServers": {
    "websearch": {
      "command": "npx",
      "args": ["-y", "mcp-websearch"]
    }
  }
}
```

로컬 개발 시:

```json
{
  "mcpServers": {
    "websearch": {
      "command": "npx",
      "args": [
        "-y",
        "--prefix",
        "/절대/경로/mcp-websearch",
        "mcp-websearch"
      ]
    }
  }
}
```

### 3. Claude 재시작

설정 파일 수정 후 Claude Desktop 또는 Claude Code를 재시작하세요.

## 사용법

### web_search - 웹 검색

DuckDuckGo HTML 검색을 통해 상위 결과를 크롤링하고 본문 텍스트를 추출합니다.

**파라미터**:
- `query` (필수): 검색어
- `max_results` (선택): 결과 개수 (기본값: 5, 최대: 10)
- `force_refresh` (선택): 캐시 무시 (기본값: false)

**예시**:

```
사용자: "2026년 최신 AI 뉴스 검색해줘"
Claude: [web_search 도구 자동 호출]
```

**응답 형식**:
```json
{
  "results": [
    {
      "title": "페이지 제목",
      "url": "https://example.com",
      "content": "추출된 본문 텍스트...",
      "snippet": "검색 결과 스니펫",
      "timestamp": "2026-02-05T00:00:00.000Z"
    }
  ],
  "query": "검색어",
  "cached": false,
  "search_time_ms": 5000
}
```

### extract_url - URL 콘텐츠 추출

특정 URL의 웹 페이지 텍스트를 추출합니다.

**파라미터**:
- `url` (필수): 대상 URL
- `use_readability` (선택): Readability 사용 여부 (기본값: true)

**예시**:

```
사용자: "이 블로그 포스트 요약해줘: https://example.com/article"
Claude: [extract_url 도구 자동 호출]
```

**응답 형식**:
```json
{
  "title": "페이지 제목",
  "url": "https://example.com/article",
  "content": "추출된 텍스트...",
  "length": 5000,
  "timestamp": "2026-02-05T00:00:00.000Z"
}
```

## 기술 스택

- **Node.js** - 런타임 환경
- **TypeScript** - 타입 안전성
- **@modelcontextprotocol/sdk** - MCP 서버 프레임워크
- **Puppeteer** - 헤드리스 브라우저 (SPA 지원)
- **@mozilla/readability** - 본문 추출 알고리즘
- **jsdom** - HTML 파싱
- **node-cache** - 메모리 캐싱

## 캐싱

동일한 검색어는 6시간 동안 캐시됩니다. 캐시를 무시하려면 `force_refresh: true`를 사용하세요.

**캐시 확인**:
```
캐시 히트: cached: true, 응답 시간 ~100ms
캐시 미스: cached: false, 응답 시간 ~5초
```

## 트러블슈팅

### MCP 서버 연결 실패

```bash
# 빌드 확인
npm run build

# dist/index.js 존재 확인
ls -la dist/index.js

# 직접 실행 테스트
node dist/index.js
```

### Puppeteer 에러

```bash
# Chromium 재설치
npm install puppeteer --force
```

### 검색 결과 없음

- Google CAPTCHA 발생 가능성 (과도한 요청)
- 잠시 기다린 후 재시도
- `force_refresh: false`로 캐시 사용 권장

## 제약사항

- **개인 용도**: robots.txt를 무시하므로 개인 용도로만 사용 권장
- **Google CAPTCHA**: 과도한 요청 시 CAPTCHA 발생 가능
- **메모리 사용**: Puppeteer는 메모리를 많이 사용 (병렬 5개 제한)
- **속도**: 실시간 크롤링이므로 API보다 느림 (캐싱으로 완화)

## 개발

```bash
# 개발 모드 (TypeScript watch)
npm run dev

# 빌드
npm run build

# 로컬 실행
npm start

# 디버그 모드
DEBUG=true node dist/index.js
```

## 라이선스

MIT

## 기여

이슈와 PR은 환영합니다!

## 참고 자료

- [MCP 공식 문서](https://modelcontextprotocol.io)
- [Puppeteer 문서](https://pptr.dev)
- [Readability 저장소](https://github.com/mozilla/readability)