mcp-research

웹 조사 도구를 제공하는 독립형 MCP(Model Context Protocol) 서버입니다. AI 어시스턴트를 위한 세 가지 검증된 도구(웹 검색, 페이지 가져오기 및 마크다운 변환, 복합 다중 소스 조사 실행)를 MCP stdio 프로토콜을 통해 제공합니다.

도구

모든 도구는 읽기 전용입니다. 공개 웹 콘텐츠를 가져와 변환할 뿐, 절대 수정하지 않습니다.

설치

pip install mcp-research

또는 uvx를 사용하여 직접 실행(설치 불필요):

uvx mcp-research

구성

모든 구성은 환경 변수를 통해 이루어지며, 별도의 구성 파일이 필요하지 않습니다.

Claude Code와 함께 사용

Claude Code MCP 구성(~/.claude/settings.json 또는 프로젝트 .mcp.json)에 추가하세요:

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["mcp-research"],
      "env": {
        "BRAVE_API_KEY": "BSA...",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

Claude Desktop과 함께 사용

claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["mcp-research"],
      "env": {
        "BRAVE_API_KEY": "BSA..."
      }
    }
  }
}

도구 세부 정보

web_search

web_search(query, max_results=5, summarize=False, auto_fetch_top=False)

최대 신뢰성을 위해 3단계 캐스케이드를 사용하여 웹을 검색합니다:

1. Brave Search API — 빠르고 고품질(BRAVE_API_KEY 필요)

2. DuckDuckGo 라이브러리 — API 키 불필요, 속도 제한 시 재시도

3. DuckDuckGo HTML 스크레이퍼 — 최후의 수단

옵션:

• summarize: Ollama를 사용하여 결과 요약(Ollama 실행 필요)

• auto_fetch_top: 상위 결과의 전체 콘텐츠를 가져와 반환

fetch_url

fetch_url(url, summarize=False, max_chars=50000)

URL을 가져와 깔끔한 마크다운으로 변환합니다:

• SSRF 보호: 로컬호스트, 사설 IP, 비 HTTP 스키마 차단

• 스마트 재시도: 429/5xx 오류 시 지수 백오프, 홉별 리다이렉트 검증

• 24시간 캐시: SHA-256 키 기반, 구성 가능한 TTL

• 콘텐츠 지원: HTML → 마크다운, JSON → 코드 블록, 바이너리 → 거부

• 스마트 잘림: 텍스트 중간이 아닌 제목/단락 경계에서 끊음

research

research(query, depth="standard", context="")

복합 조사 파이프라인:

1. 쿼리 재작성 — Ollama가 질문을 검색 키워드로 최적화

2. 웹 검색 — 관련 페이지 찾기(결과가 없을 경우 재시도 확장)

3. 병렬 가져오기 — 상위 N개 페이지를 동시에 가져오기

4. 요약 — Ollama가 각 페이지 요약

5. 합성 — Ollama가 최종 인용 답변 생성

심층 수준:

모든 단계는 Ollama 없이도 정상적으로 작동하며, 검색 결과와 원시 페이지 콘텐츠를 얻을 수 있습니다.

개발

git clone https://github.com/MABAAM/Maibaamcrawler.git
cd Maibaamcrawler
pip install -e .
python -m mcp_research

라이선스

MIT