research-mcp

상태 비저장 MCP 퍼사드로, 검색/읽기 제공자들의 피라미드를 단일 streamable-http MCP 엔드포인트 뒤에 숨기고, 좋은 러시아어 도움말 텍스트를 갖춘 3개의 깔끔한 도구만 노출합니다. LLM은 간단한 "검색 → 읽기" 도구 세트를 얻고, 그 뒤에서는 여러 제공자가 자동으로 시도되고, 병합되며, 장애 조치됩니다.

이 앱은 인증을 수행하지 않습니다 — 호스트에서 Traefik + basicAuth를 통해 게시됩니다. 애플리케이션 상태를 보유하지 않습니다: 유일하게 유지되는 것은 data/ 아래의 로그 파일(볼륨에 보관)뿐입니다.

도구

Related MCP server: serp-it

아키텍처: 유형 + 인스턴스

제공자는 플러그인입니다. 다음을 구분합니다:

• 유형 — 구현 클래스(예: searxng 검색 제공자), src/providers/의 모듈당 하나, @register("type")로 등록.

• 인스턴스 — 명명된 환경 변수에서 비밀/URL이 해석된 유형의 구성된 복사본(한 유형의 여러 인스턴스 허용, 예: 다른 키를 가진 tavily-1 / tavily-2).

어떤 인스턴스가 존재하고 각 파이프라인이 시도하는 순서는 코드에서 구성됩니다(src/pipeline_config.py); 키/URL은 변수 이름으로 ENV에서 가져옵니다.

• 검색 파이프라인 (searxng → brave → jina-search → serper → exa): 활성 인스턴스는 동시에 실행됩니다. 결과는 정규화된 URL로 병합 및 중복 제거됩니다(앞선 파이프라인 위치가 우선). JINA_API_KEY가 설정된 경우(그리고 SEARCH_RERANK_ENABLED가 꺼져 있지 않은 경우), 병합된 전체 목록은 jina-reranker-v3.5로 재순위화되어 num_results로 잘라낼 때 맹목적인 파이프라인 순서 접두사 대신 가장 관련성 높은 결과를 유지합니다. 재순위 실패 시 병합 순서로 대체됩니다. searxng와 brave는 추가로 로컬에서 자체 제한을 둡니다(각각 45초 및 1.1초당 하나의 쿼리, 측정된 업스트림 제한과 일치). 슬롯이 사용 중이면 대기하는 대신 현재 검색을 건너뜁니다.

• 읽기 파이프라인 (trafilatura → jina → crawl4ai → tavily-1 → tavily-2 → firecrawl): 단일 프로브 GET이 URL을 분류합니다. PDF(Content-Type / .pdf / %PDF 매직)는 pypdf로 추출됩니다. HTML의 경우 동일한 본문이 trafilatura에 전달되어 핫 경로가 두 번 GET하지 않습니다. 그런 다음 나머지 인스턴스가 순서대로 시도되고 >= FALLBACK_MIN_CHARS 콘텐츠를 반환하는 첫 번째 인스턴스가 승리합니다.

횡단 관심사: 짧은 백오프가 있는 일시적 재시도 1회(5xx / 전송 오류); 402(크레딧 부족) / 429(속도 제한)는 제공자 실패로 처리 → 다음 인스턴스(이것이 tavily-1 → tavily-2 장애 조치를 가능하게 합니다).

인스턴스는 필수 환경 변수가 설정된 경우에만 활성화됩니다. 그렇지 않으면 로그 줄과 함께 건너뜁니다. trafilatura는 구성이 필요 없습니다(항상 켜짐); jina는 키 없이 작동합니다(키는 선택 사항). 시작 시 서버는 검색 및 읽기 인스턴스가 각각 하나 이상 필요하며, 그렇지 않으면 명확한 메시지와 함께 종료됩니다.

제공자 추가

1. @register("<type>")로 데코레이트된 클래스를 가진 src/providers/<type>.py를 작성하고 SearchProvider.search(...) 또는 ReadProvider.read(...)를 구현합니다.

2. src/providers/__init__.py에서 모듈을 가져옵니다(데코레이터가 실행되도록).

3. src/pipeline_config.py에 Instance("name", "<type>", api_key_env="YOUR_ENV_NAME") 줄을 추가하고 SEARCH_PIPELINE / READ_PIPELINE에서 해당 name을 참조합니다. ENV 변수 이름을 사용하고, 값을 사용하지 마세요.

4. .env.example에 환경 변수를 문서화합니다.

빠른 시작

make install                # create .venv + install dev/test deps
cp .env.example .env        # fill in the keys you have  (shortcut: make env)
make test                   # run tests
make run                    # run the server (streamable-http on MCP_HOST:MCP_PORT, endpoint /mcp)

구성

모든 구성은 ENV / .env에서 옵니다(.env.example 참조). 제공자 비밀/URL은 Settings 필드로 선언되지 않고 인스턴스 로더에서 이름으로 읽힙니다. 비밀 아닌 노브(모두 기본값): MCP_HOST, MCP_PORT, LOG_LEVEL, LOG_FILE, LOG_ROTATION, LOG_RETENTION, REQUEST_TIMEOUT, FALLBACK_MIN_CHARS, READ_PAGES_CONCURRENCY, RETRIES, SEARCH_RERANK_ENABLED, JINA_TOKEN_BUDGET. read_pages의 호출당 URL 상한은 고정 20(도구 설명과 일치하는 하드 상수) — 구성 불가능합니다.

제공자 환경 변수: SEARXNG_URL, BRAVE_API_KEY, SERPER_API_KEY, EXA_API_KEY, JINA_API_KEY(하나의 키가 jina 리더를 키 모드로 활성화하고, jina-search 제공자와 검색 재순위화를 활성화합니다. 리더만 키 없이도 작동합니다), CRAWL4AI_URL + CRAWL4AI_TOKEN, TAVILY_1_API_KEY, TAVILY_2_API_KEY, FIRECRAWL_API_KEY.

프록시

외부 인스턴스는 <INSTANCE>_PROXY를 설정하여 자체 SOCKS5/HTTP 프록시를 통해 라우팅할 수 있습니다 — IP 기반 차단(예: Exa 앞의 Cloudflare)을 넘어 깨끗한 이그레스에 유용합니다. 인스턴스별 지원: EXA_PROXY, BRAVE_PROXY, SERPER_PROXY, JINA_PROXY, TAVILY_1_PROXY, TAVILY_2_PROXY, FIRECRAWL_PROXY. 내부 인스턴스(searxng, crawl4ai, trafilatura)에는 프록시가 없습니다.

값은 httpx에 직접 전달됩니다. socks5://host:port는 프록시 측 DNS를 수행합니다(대상 호스트 이름은 curl --socks5-hostname처럼 프록시가 해석합니다). socks5h:// / http://host:port도 허용됩니다. 설정되지 않으면 해당 인스턴스는 직접 연결됩니다. 파이프라인은 고유한 프록시 URL당 하나의 풀링된 httpx 클라이언트(및 하나의 직접 클라이언트)를 유지하며, 인스턴스별로 선택되므로 프록시된 제공자와 직접 제공자가 나란히 실행됩니다. socks 추가 기능(httpx[socks], 이미 고정됨)이 필요합니다.

로깅

stderr(Docker의 회전 제한 json-file 드라이버가 캡처) 외에도 서버는 영구 로그 파일을 data/research-mcp.log(기본값; LOG_ROTATION=20 MB, LOG_RETENTION=14 days)에 씁니다. 이 파일은 data/ 볼륨에 있으므로 컨테이너 재시작 및 이미지 업데이트 후에도 유지됩니다. 파일에는 도구 호출당 요청당 한 줄이 포함됩니다 — 검색(query, 실제로 실행된 제공자 인스턴스, 결과 수, 지연 시간) 및 읽기(url, 승리한 제공자/계층 또는 pdf, ok, 지연 시간), 그리고 read_pages count=N ok=K 요약 — 요청이 제공자 계층에 어떻게 분산되는지 분석하는 데 유용합니다. 요청 본문이나 비밀은 기록되지 않으며, URL/쿼리, 제공자 이름, 개수, 타이밍만 기록됩니다.

배포

Gitea Actions가 이미지를 빌드하고 Gitea 레지스트리 gitea.vvzvlad.xyz/projects/research-mcp(test → build, 태그 latest + sha)에 푸시합니다. 프로덕션에서는 docker-compose.yml을 통해 사전 빌드된 이미지를 가져옵니다(Traefik + basicAuth 뒤, watchtower가 latest를 자동 업데이트; data/ 볼륨이 업데이트 간 로그 파일을 유지) — 프로덕션에서 빌드하지 않습니다.

레이아웃