mcp-retrieval

이게 뭔가요

mcp-retrieval은 Go로 작성된 Model Context Protocol 서버입니다. MCP 호환 클라이언트(Claude Desktop, IDE 에이전트, 커스텀 LLM 앱)에 웹 검색 기능을 세 가지 읽기 전용 도구로 노출합니다. 내부적으로는 retrieval-go 라이브러리를 사용해 웹을 검색하고 페이지를 가져오며, 결과를 모델에 바로 전달할 수 있는 깔끔한 Markdown으로 반환합니다.

이 라이브러리는 API 키가 필요 없습니다: 웹 검색은 DuckDuckGo Lite를, 이미지 검색은 Bing Images를 거치며, 페이지 가져오기는 HTML을 readability 추출기에 통과시킨 후 Markdown으로 변환합니다. 봇 보호에 대비해 TLS 수준에서 실제 브라우저를 가장하며 브라우저 지문과 프록시를 모두 순환할 수 있습니다 — 검색 엔진을 참조하세요.

MCP SDK가 지원하는 두 전송 방식 모두 사용할 수 있으며 동일한 도구 세트를 노출합니다:

• stdio — 클라이언트가 바이너리를 실행하고 stdin/stdout으로 통신합니다(기본값, 데스크톱 클라이언트에 적합).

• http — 장기 실행 스트리밍 HTTP 서버(원격/공유 배포에 유용).

Related MCP server: mcp-web-calc

도구

세 도구 모두 읽기 전용으로 주석 처리되어 있습니다. 각 도구는 출력 스키마와 일치하는 구조화된 JSON 페이로드를 반환합니다. SDK는 structuredContent를 읽지 않는 클라이언트를 위해 동일한 JSON을 텍스트 콘텐츠 블록에도 미러링합니다.

web_search

web_search_images

web_scrape

queries/urls 목록은 모두 호출당 max_queries(10)개 항목으로 상한이 적용됩니다. 쿼리는 512자 이하여야 하며, URL은 2048자 이하이고 http/https만 허용됩니다.

결과 및 개수

모든 호출은 입력 목록 전체에 걸쳐 분산되며 쿼리/URL당 하나의 항목을 반환하고, 각 항목에는 success, failed, timeout 중 하나의 status가 포함되므로 부분 실패가 발생해도 성공한 항목은 계속 반환됩니다.

count는 실제로 반환된 항목 수이며, 요청한 max_results / max_images보다 낮을 수 있습니다: 단일 쿼리 결과 내의 중복은 상한이 적용되기 전에 제거되며, 업스트림에 제공할 항목이 단순히 더 적을 수도 있습니다. count가 더 작은 것은 정상적인 결과이지 오류가 아닙니다.

중복 제거는 쿼리별로 수행되며 쿼리 간에는 수행되지 않습니다. 각 항목은 자체적으로 중복 제거되므로, 같은 호출의 두 쿼리에서 발견된 링크는 두 항목 모두에 나타납니다 — 필요하다면 직접 합집합에서 중복을 제거하세요.

오류

요청 수준의 실패는 JSON-RPC 오류가 아닌 isError: true와 일반 텍스트 메시지가 포함된 도구 결과로 반환됩니다 — 모델이 메시지를 읽고 호출을 스스로 수정할 수 있습니다. 항목별 실패는 이렇게 처리되지 않으며 페이로드 안에 status: "failed" / "timeout"으로 유지됩니다.

호출이 완전히 실패하는 경우는 입력이 작업 시작 전에 거부되거나, 모든 항목이 실패한 경우뿐입니다:

전체 실패 메시지는 의도적으로 타임아웃과 다른 원인을 구분하지 않습니다: 혼합 배치는 여러 이유로 동시에 실패할 수 있으며, 항목별 status가 항목이 하나라도 살아남을 때마다 이미 그 세부 정보를 담고 있기 때문입니다.

알려진 제한 사항

• web_scrape는 HTML만 처리합니다. 페이지는 readability 추출기를 통과하며, 이 추출기는 기사 마크업이 필요하므로 text/plain 응답은 아무것도 생성하지 못하고 status: "failed"로 반환됩니다. 원시 파일 호스트가 일반적인 경우입니다: raw.githubusercontent.com, github.com/.../raw/..., cdn.jsdelivr.net. 원시 파일 대신 렌더링된 페이지를 스크래핑하세요.

• web_search_images의 관련성은 보장되지 않습니다. 일부 쿼리의 경우 Bing Images가 결과 집합이 아닌 페이지를 제공하며, 이를 결과 집합인 것처럼 파싱합니다 — 그러면 도구가 관련 없는 이미지를 status: "success"로 반환합니다. 이미지 결과는 최선의 노력(best-effort)으로 간주하고 사용자에게 보여주기 전에 검증하세요.

• JavaScript가 없습니다. 페이지는 있는 그대로 가져오며, 클라이언트 측에서 렌더링되는 콘텐츠는 추출기에 보이지 않습니다.

빠른 시작

설치

원하는 방식을 선택하세요 — 모두 동일한 서버를 제공합니다.

컨테이너 (Go 툴체인 불필요):

docker pull ghcr.io/role1776/mcp-retrieval:latest

사전 빌드된 바이너리 — 최신 릴리스에서 플랫폼에 맞는 아카이브를 받아 압축을 풀고 mcp-retrieval을 PATH에 추가하세요.

MCP 번들 — .mcpb 파일을 설치하는 클라이언트의 경우, 최신 릴리스에서 mcp-retrieval_<version>_<os>_<arch>.mcpb를 다운로드하여 클라이언트로 열면 됩니다. 번들에는 컴파일된 바이너리가 포함되어 있으므로 Docker도 Go도 필요하지 않습니다. OS 및 CPU 아키텍처와 일치하는 파일을 선택하세요: 번들에는 네이티브 바이너리 하나가 들어 있습니다.

소스에서:

go install github.com/Role1776/mcp-retrieval/app/cmd/mcp-retrieval@latest   # needs Go 1.25.5+

또는 바이너리를 제자리에서 빌드합니다(Go 모듈은 app/에 있습니다):

make build          # -> bin/mcp-retrieval

실행

# defaults: stdio transport, no configuration needed
./bin/mcp-retrieval

# with an explicit env file
./bin/mcp-retrieval -env /absolute/path/to/.env

플래그 하나는 선택 사항입니다:

MCP 클라이언트 연결 (stdio)

클라이언트를 빌드된 바이너리로 지정하세요. Claude Desktop 설정 예시:

{
  "mcpServers": {
    "retrieval": {
      "command": "/absolute/path/to/mcp-retrieval",
      "env": {
        "MAX_RESULTS": "20"
      }
    }
  }
}

env 블록은 선택 사항입니다 — "command"만으로 충분합니다.

MCP 클라이언트 연결 (컨테이너)

stdio로 이미지를 실행하세요. 구성은 여전히 env 블록을 통해 전달되지만, Docker는 각 변수가 프로세스에 도달하려면 -e 플래그로 명령줄에 명시되어야 합니다:

{
  "mcpServers": {
    "retrieval": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MAX_RESULTS",
        "-e", "DEFAULT_TIMEOUT_MS",
        "ghcr.io/role1776/mcp-retrieval:latest"
      ],
      "env": {
        "MAX_RESULTS": "20",
        "DEFAULT_TIMEOUT_MS": "5000"
      }
    }
  }
}

-i는 필수입니다 — 없으면 컨테이너가 stdin을 받지 못하고 클라이언트는 서버가 즉시 종료되는 것을 보게 됩니다. MCP 레지스트리에서 설치하는 클라이언트는 이 호출을 직접 구성하고 server.json에 선언된 변수를 입력하라는 메시지를 표시합니다.

HTTP로 실행

MCP_TRANSPORT=http로 설정하면 서버는 MCP_PATH의 SERVER_PORT에서 수신합니다 (기본값 http://localhost:8080/mcp).

구성

모든 것은 환경 변수를 통해 구성되며, 각 값은 시작 전에 검증됩니다: 숫자가 아니거나 양수가 아닌 값은 시작 오류입니다. 한도 간의 관계는 시작 시 확인되지 않습니다 — 한도를 참조하세요. 환경에 이미 존재하는 변수는 .env 파일보다 우선하므로, MCP 클라이언트의 env 블록이 항상 적용됩니다. 모든 필드에는 합리적인 기본값이 있으므로 서버는 구성 없이도 실행됩니다 (stdio 전송).

전체 목록과 기본값은 .env.example을 참조하여 .env로 복사할 수 있습니다.

MCP 서버

클라이언트에 광고되는 버전은 구성할 수 없습니다: 빌드 시 git 태그에서 바이너리에 고정됩니다.

HTTP 서버 (http 전송 전용)

HTTP 클라이언트 및 프록시

프록시가 구성되면 각 아웃바운드 요청은 로그인에 고유한 세션 ID가 추가되어, 업스트림 제공자가 요청마다 출구 IP를 순환시킵니다.

한도

각 값은 개별적으로 검사됩니다 — 0보다 커야 합니다 — 그러나 DEFAULT_*, MIN_* 및 MAX_* 세 쌍은 시작 시 서로 교차 검사되지 않습니다. 일관되지 않은 집합이 서버를 중단시키지는 않습니다. 대신 요청별로 조정됩니다:

• 호출자가 생략하거나 0 또는 음수로 전달한 값은 해당 DEFAULT_*로 대체됩니다;

• 그 결과는 [MIN_*, MAX_*] 범위로 제한되므로, DEFAULT_*가 해당 MAX_*보다 크면 단순히 MAX_*가 됩니다;

• MIN_*가 MAX_*를 초과하면 최대값이 우선합니다.

따라서 유효 한도는 항상 구성된 최대값 내에 있으며, 잘못된 구성은 시작 실패가 아닌 작동하는 서버로 이어집니다. 단점은 조용히 저하된다는 점입니다: MAX_RESULTS=2처럼 20 대신 오타가 있어도 경고가 발생하지 않고, 단지 응답이 조용히 작아질 뿐입니다. 결과가 잘린 것처럼 보일 때는 이 값을 다시 확인하는 것이 좋습니다.

로깅

아키텍처

이 프로젝트는 깔끔하고 계층화된 구조를 따릅니다. 의존성은 도메인을 향해 안쪽으로 향하며, 각 계층은 인터페이스를 통해 다음 계층과 통신합니다.

app/                       the Go module: sources plus its build files
                           (Dockerfile, .dockerignore, .goreleaser.yaml)

cmd/mcp-retrieval/main.go  entry point: parse flags, load config, run app

internal/
  app/                     wiring + lifecycle (build server, run, graceful shutdown)
  config/                  config loading (.env → env vars → validate)
  domain/                  core types (Query, Link, Document, Snippet, Image) and errors
  dto/web/                 request/response shapes for the MCP tools
  transport/mcp/           MCP layer
    router/                registers every tool group on the MCP server
    web/                   tool handlers
    utils/                 schema helpers and error → tool-result mapping
  usecase/web/             business logic: validation, parallelism, timeouts, dedupe/limit/rerank
  adapter/web/             retrieval-go client wiring (search, images, scrape, proxy)
  pkg/                     reusable building blocks (mcpserver, server, logger, validator)

도구 호출의 요청 흐름:

MCP client → transport/mcp/web (handler) → usecase/web → adapter/web → retrieval-go → the web
                     ↑ maps errors               ↑ validates, fans out, limits results

검색과 스크래핑은 모두 입력 목록 전체에 걸쳐 동시에 분산되며 항목별 결과를 집계하며, 각각 고유한 상태(success, failed, timeout)를 가집니다. 호출이 완전히 실패하는 경우는 해당 호출의 모든 항목이 실패한 경우뿐입니다.

검색 엔진

모든 네트워크 작업은 retrieval-go에 위임되며, app/internal/adapter/web에서 구성됩니다. 알아두면 좋은 사항:

• 소스. 웹 검색은 DuckDuckGo Lite를 사용합니다; 이미지 검색은 Bing Images를 사용합니다; 페이지 가져오기는 원시 HTML을 readability 추출기를 통해 처리하고 본문 기사를 Markdown으로 변환합니다 (표 포함). 검색 엔진 API 키가 필요하지 않습니다.

• 브라우저 가장. 어댑터는 WithBrowserRotation()을 활성화하므로 각 요청은 무작위로 선택된 ~11개의 실제 브라우저 프로필 중 하나에서 전송됩니다. 각 프로필은 실제 TLS/JA3 지문(uTLS 사용)과 일치하는 User-Agent 및 클라이언트 힌트 헤더를 쌍으로 사용합니다 — Chrome 133/131/120 (Windows/macOS/Linux), Edge 131, Firefox 120 (Windows/macOS), Safari 18.4 (macOS), iOS 18.4 Safari. 이렇게 하면 트래픽이 Go HTTP 클라이언트가 아닌 일반 브라우저처럼 보이며, 이것이 무료 소스에 계속 접근할 수 있게 하는 요소입니다.

• 프록시 순환. PROXY_HOST가 구성되면 어댑터는 모든 요청에서 프록시 사용자 이름에 고유한 session-<id>를 추가하는 프록시 팩토리를 설치합니다. 세션 기반 리지덴셜/순환 프록시 제공자를 사용하면 요청마다 새로운 출구 IP가 생성되어 부하를 분산하고 속도 제한을 피할 수 있습니다. 프록시가 없으면 요청은 직접 나갑니다.

• 응답 처리. 응답은 투명하게 압축 해제되며(gzip, br, zstd, deflate), keep-alive는 비활성화됩니다(WithDisableKeepAlive()) — 풀링된 연결이 요청 간에 단일 지문/IP에 고정되지 않도록 하기 위함입니다.

이 중 어떤 것도 작동하기 위해 구성이 필요하지 않습니다 — 위의 기본값이 자동으로 적용됩니다. 프록시 자격 증명만 선택적 추가 사항입니다.

개발

Go 관련 모든 것은 app/에 있으므로, 저장소 루트의 makefile을 사용하거나 도구 체인에 -C app을 전달하세요:

make build          # compile the binary
make test           # run tests

go -C app build ./...      # compile everything
go -C app test ./...       # run tests
go -C app vet ./...        # static checks

풀 리퀘스트 지침은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT 라이선스로 배포됩니다.