Episkey-G/GrokSearch-rs

GrokSearch‑rs – 웹 검색 도구용 경량 Rust MCP 서버

개요 – Claude 스타일 어시스턴트가 사용하는 MCP(Model‑Client‑Protocol) 서버를 구현한 작고 자체 호스팅 가능한 Rust 바이너리입니다. web_search, get_sources, web_fetch, web_map, doctor, 선택적 x_search 등의 도구를 제공하여 LLM이 라이브 웹 콘텐츠를 검색, 인용, 렌더링할 수 있게 합니다. 서버는 stdio를 통해 로컬로 실행(클라이언트가 시작)하거나 모바일 및 다중 장치 사용을 위한 스트리밍 가능한 HTTP 엔드포인트로 노출할 수 있습니다.

중요성 – 최신 LLM 에이전트는 최신의 검증 가능한 정보가 필요합니다. GrokSearch‑rs는 다음을 통해 이를 제공합니다:

• 구성 가능한 순서로 여러 외부 검색 공급자(Tavily, Exa, TinyFish, Firecrawl)를 쿼리합니다.
• API 키 없이 작동하는 GitHub, StackExchange, arXiv, Wikipedia용 전문 추출기로 결과를 강화합니다.
• 세션 캐시를 유지하여 후속 호출(get_sources)이 재검색 없이 동일한 인용을 검색할 수 있습니다.
• 토큰 제한을 존중: 구성 가능한 문자 예산 내에서 응답을 다듬고 간결하거나 상세한 페이로드를 선택할 수 있습니다.
• xAI의 Grok Responses API와 OpenAI 호환 채팅 완성 게이트웨이를 모두 지원하며 환경 변수로 선택할 수 있습니다.

주요 기능(README에 나열됨)

기능	설명
인용 포함 라이브 웹 검색	상위 소스에 대한 요약과 메타데이터를 반환합니다. include_content는 추출된 전체 텍스트를 포함할 수 있습니다.
응답 예산	인라인 소스 텍스트(max_inline_sources)와 총 문자 수(response_max_chars)를 제한합니다.
구조화된 web_fetch	GitHub 이슈/PR, StackExchange 스레드, arXiv 논문, Wikipedia 페이지를 깨끗한 Markdown으로 파싱합니다. 다른 URL은 일반 소스 체인으로 폴백합니다.
두 가지 전송	네이티브 xAI Responses(/v1/responses) 또는 OpenAI 호환 chat/completions 엔드포인트.
선택적 Grok OAuth 모드	로컬 OAuth 토큰을 저장하여 API 키 없이 서버를 실행할 수 있습니다.
원격 HTTP 모드(기능 http)	다중 테넌트, 스트리밍 가능한 HTTP 서버. 키는 요청별로 헤더를 통해 전송되며 서버에 저장되지 않습니다.
플러그 가능한 소스 체인	순서가 지정된 공급자(Tavily → Exa → TinyFish → Firecrawl)와 라운드 로빈 키 순환 및 장애 조치.
X/Twitter 검색(x_search)	Grok Responses 전송에서만 사용 가능.
동시성	최대 8개의 동시 stdio 도구 호출을 처리합니다. 추가 호출은 대기열에 들어갑니다.
doctor 도구	연결성과 마스킹된 구성을 보고하는 빠른 상태 확인.

설치

npm install -g grok-search-rs   # 사전 빌드된 네이티브 Rust 바이너리를 가져옵니다

설치된 grok-search-rs 명령이 MCP 클라이언트가 시작하는 것입니다.

실행 옵션

• StdIO(로컬) – 기본값. 클라이언트가 바이너리를 하위 프로세스로 시작하고 stdin/stdout으로 통신합니다.
• 원격 HTTP – --features http로 컴파일(또는 제공된 Docker 이미지 사용). 서버는 구성 가능한 주소(GROK_MCP_BIND)에서 수신하고 스트리밍 가능한 HTTP 엔드포인트를 통해 동일한 도구를 제공합니다.

구성 – 모든 설정은 환경 변수(stdio 모드) 또는 HTTP 헤더(원격 모드)로 제공됩니다. 단일 전역 TOML 파일(~/.config/grok-search-rs/config.toml)에 키를 저장하여 여러 클라이언트가 공유할 수 있습니다.

핵심 변수(발췌):

GROK_SEARCH_API_KEY   – xAI/Grok용 Bearer 토큰(OAuth의 경우 비워 둠)
GROK_SEARCH_URL       – Grok 게이트웨이의 기본 URL(기본값 https://api.x.ai)
TAVILY_API_KEY        – 일반 웹 검색에 필수. 순환용 쉼표로 구분된 목록 가능
FIRECRAWL_API_KEY     – Firecrawl 폴백 활성화
EXA_API_KEY, TINYFISH_API_KEY – 체인에서 해당 공급자 활성화
GROK_SEARCH_MODEL     – 보낼 모델 이름(예: grok-4.20-fast)
GROK_SEARCH_RESPONSE_MAX_CHARS – 전체 응답 예산(기본값 45 000)

HTTP 전송용 헤더도 동일한 명명 체계를 따릅니다(예: X-Grok-Api-Key, X-Tavily-Api-Key).

일반적인 워크플로

1. 검색 – 쿼리로 web_search를 호출합니다. 서버는 간결한 답변과 소스 목록을 반환합니다. 상위 max_inline_sources에는 추출된 텍스트가 포함될 수 있습니다.
2. 세부 정보 가져오기 – 소스 URL에서 web_fetch를 사용하여 깨끗한 Markdown을 얻습니다(전문 추출기는 GitHub, StackExchange, arXiv, Wikipedia에서 더 풍부한 출력 제공).
3. 소스 페이지네이션 – 원래 검색에서 많은 인용이 생성된 경우 get_sources를 통해 클라이언트가 페이지를 넘길 수 있습니다.
4. 진단 – doctor를 실행하여 모든 업스트림 API에 연결할 수 있고 구성이 올바르게 로드되었는지 확인합니다.

자체 호스팅 – Linux x86_64 및 aarch64용 사전 빌드 바이너리와 Docker 이미지(ghcr.io/episkey-g/grok-search-rs)가 릴리스됩니다. Dockerfile과 함께 제공되는 docker‑compose.yml/Caddyfile을 통해 원커맨드 HTTPS 배포가 가능합니다.

개발 – 저장소는 표준 Rust 프로젝트입니다. 소스에서 빌드:

cargo build --release               # stdio 바이너리
cargo build --profile release-http --features http   # HTTP 지원 바이너리

표준 Rust 도구(cargo fmt, cargo clippy, cargo test)를 사용합니다.

대상 사용자 – 신뢰할 수 있는 인용 웹 검색 기능이 필요한 LLM 기반 어시스턴트(Claude, ChatGPT, 사용자 지정 에이전트)를 구축하는 모든 사람, 특히 키, 캐싱, 응답 크기를 완전히 제어하려는 경우.