Brave Search MCP/SSE 서버

스트리밍 인터페이스를 통해 AI 모델과 다른 클라이언트에게 웹 및 로컬 검색 기능을 제공하는 Brave Search API를 통합하는 SSE(Server-Sent Events)를 사용하는 MCP(Model Context Protocol) 구현입니다.

개요

이 서버는 모델 컨텍스트 프로토콜(MCP)을 이해하는 대규모 언어 모델(Large Language Models)을 위한 도구 제공자 역할을 합니다. SSE 연결을 통해 Brave의 강력한 웹 및 로컬 검색 기능을 제공하여 검색 결과의 실시간 스트리밍 및 상태 업데이트를 가능하게 합니다.

주요 디자인 목표:

• 중앙 집중식 액세스: 중앙 집중성을 염두에 두고 설계되어 조직이나 개인이 단일 Brave Search API 키를 관리하고 여러 내부 클라이언트나 애플리케이션에 대한 통제된 액세스를 제공할 수 있습니다.
• 관찰성: 요청, API 상호작용, 오류 및 속도 제한을 추적하는 강력한 로깅 기능을 제공하여 사용량에 대한 가시성을 제공하고 디버깅을 지원합니다.
• 유연한 배포: 네트워크 내에서 비공개적으로 배포하거나 Kubernetes Ingress나 직접 Docker 포트 매핑과 같은 방법을 통해 선택적으로 공개적으로 노출할 수 있습니다.

특징

• 웹 검색 : 일반적인 쿼리, 뉴스, 기사 등에 대한 Brave의 독립적인 웹 검색 인덱스에 액세스하세요. 페이지 매김 및 필터링 제어를 지원합니다.
• 지역 검색 : 주소, 전화번호, 평점 등 자세한 정보와 함께 업체, 레스토랑, 서비스를 찾아보세요.
• 스마트 폴백 : 로컬 검색은 쿼리에 대한 특정 로컬 결과가 발견되지 않으면 자동으로 필터링된 웹 검색으로 돌아갑니다.
• 서버 전송 이벤트(SSE) : 검색 결과와 도구 실행 상태를 효율적으로 실시간으로 스트리밍합니다.
• 모델 컨텍스트 프로토콜(MCP) : 호환되는 클라이언트와의 원활한 통합을 위해 MCP 표준을 준수합니다.
• Docker 지원 : 컨테이너화 및 배포를 쉽게 할 수 있는 Dockerfile 포함되어 있습니다.
• Helm 차트 : Kubernetes 클러스터에 간단하게 배포할 수 있는 Helm 차트를 제공합니다.

필수 조건

선택한 배포 방법에 따라 다음 중 일부가 필요합니다.

• Brave Search API 키 : 모든 배포 방법에 필요합니다. 아래 "시작하기"를 참조하세요.
• Docker : Docker를 사용하여 배포하는 경우 필요합니다.
• kubectl & Helm : Helm을 사용하여 Kubernetes에 배포하는 경우 필요합니다.
• Node.js & npm : 로컬 개발 에만 필요합니다(Node.js v22.x 이상 권장).
• Git : 로컬 개발을 위한 저장소 복제나 사용자 정의 Docker 이미지 빌드에 필요합니다.

시작하기

1. Brave Search API 키 얻기

1. Brave Search API 계정 에 가입하세요.
2. 플랜을 선택하세요(무료 플랜도 있습니다).
3. 개발자 대시보드 에서 API 키를 생성합니다.

2. 구성

서버에서는 BRAVE_API_KEY 환경 변수를 통해 Brave Search API 키를 설정해야 합니다.

기타 잠재적 환경 변수(자세한 내용은 src/config/config.ts 확인):

• PORT : 서버가 수신하는 포트(기본값은 8080 )
• LOG_LEVEL : 로깅 세부 정보(예: info , debug ).

로컬 개발의 경우 환경에서 이러한 변수를 설정하거나 프로젝트 루트에 있는 .env 파일을 사용합니다.

설치 및 사용

귀하의 요구 사항에 가장 적합한 배포 방법을 선택하세요.

옵션 1: Docker(배포에 권장됨)

필수 구성 요소: Docker가 설치되어 있어야 합니다.

1. Brave Search API 키를 받으세요: "시작하기" 섹션의 단계를 따르세요.
2. Docker 이미지 가져오기: Docker Hub에서 최신 이미지를 가져옵니다.지엑스피1또는 특정 버전 태그를 가져옵니다(예: 1.0.10 ):
   docker pull shoofio/brave-search-mcp-sse:1.0.10
   (또는 필요한 경우 로컬에서 이미지를 빌드할 수 있습니다. 저장소를 복제하고 docker build -t brave-search-mcp-sse:custom . )
3. Docker 컨테이너를 실행합니다. 가져온 태그를 사용합니다(예: latest 또는 1.0.10 ):
   docker run -d --rm \ -p 8080:8080 \ -e BRAVE_API_KEY="YOUR_API_KEY_HERE" \ -e PORT="8080" # Optional: Define the port if needed # -e LOG_LEVEL="info" # Optional: Set log level --name brave-search-server \ shoofio/brave-search-mcp-sse:latest # Or your specific tag
   이렇게 하면 서버가 분리 모드로 실행되어 호스트의 포트 8080이 컨테이너에 매핑됩니다.

옵션 2: Helm(Kubernetes 배포)

필수 구성 요소: 클러스터에 연결된 kubectl , 설치된 Helm.

1. Brave Search API 키를 받으세요: "시작하기" 섹션의 단계를 따르세요.
2. Helm 저장소를 추가합니다.
   helm repo add brave-search-mcp-sse https://shoofio.github.io/brave-search-mcp-sse/ helm repo update
3. API 키 비밀 준비(권장): 대상 네임스페이스에 Kubernetes 비밀을 만듭니다.
   kubectl create secret generic brave-search-secret \ --from-literal=api-key='YOUR_API_KEY_HERE' \ -n <your-namespace>
4. Helm 차트를 설치하세요. 차트 버전은 애플리케이션 버전과 일치합니다(최신 버전은 1.0.10 ). 다음 시크릿을 사용하여 설치하세요.
   helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \ -n <your-namespace> \ --set braveSearch.existingSecret=brave-search-secret # Optionally specify a version: --version 1.0.10
   또는 키를 직접 제공하세요(보안성이 낮음):
   helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \ -n <your-namespace> \ --set braveSearch.apiKey="YOUR_API_KEY_HERE"
5. 차트 구성: 기본값을 재정의하여 배포를 사용자 지정할 수 있습니다. 원하는 설정으로 YAML 파일(예: dev-values.yaml , prod-values.yaml )을 만들고 설치 중에 -f 플래그를 사용하세요: helm install ... -f dev-values.yaml .사용 가능한 모든 구성 옵션과 기본 설정을 보려면 차트의 기본값 values.yaml 파일을 참조하세요.

옵션 3: 지역 개발

필수 조건: Node.js 및 npm(v22.x 이상 권장), Git.

1. Brave Search API 키를 받으세요: "시작하기" 섹션의 단계를 따르세요.
2. 저장소를 복제합니다.
   git clone <repository_url> # Replace with the actual URL cd brave-search-mcp-sse
3. 종속성 설치:
   npm install
4. 환경 변수 설정: 루트 디렉토리에 .env 파일을 만듭니다.
   BRAVE_API_KEY=YOUR_API_KEY_HERE PORT=8080 # LOG_LEVEL=debug
5. TypeScript 코드를 작성합니다.
   npm run build
6. 서버를 실행합니다:
   npm start # Or for development with auto-reloading (if nodemon/ts-node-dev is configured) # npm run dev
   서버는 구성된 포트(기본값 8080 )에서 수신을 시작합니다.

API / 프로토콜 상호작용

클라이언트는 HTTP GET 요청을 통해 이 서버에 연결하여 SSE 연결을 설정합니다. 구체적인 엔드포인트는 배포 환경에 따라 다릅니다(예: http://localhost:8080/ , http://<k8s-service-ip>:8080/ 또는 Ingress).

연결되면 서버와 클라이언트는 SSE 스트림을 통해 MCP 메시지를 사용하여 통신합니다.

사용 가능한 도구

서버는 연결된 클라이언트에 다음 도구를 제공합니다.

1. brave_web_search
   • 설명 : Brave Search API를 사용하여 일반적인 웹 검색을 수행합니다.
   • 입력 :
     • query (문자열, 필수): 검색 쿼리.
     • count (숫자, 선택 사항): 반환할 결과의 개수(1-20, 기본값 10).
     • offset (숫자, 선택 사항): 페이지 오프셋(0-9, 기본값 0).
     • ( search_lang , country , freshness , result_filter , safesearch 와 같은 다른 Brave API 매개변수가 지원될 수 있습니다. src/services/braveSearchApi.ts 확인하세요)
   • 출력 : 검색 결과(제목, URL, 스니펫 등)를 포함하는 MCP 메시지를 스트리밍합니다.
2. brave_local_search
   • 설명 : Brave Search API를 사용하여 지역 업체 및 장소를 검색합니다. 지역 검색 결과가 없으면 웹 검색으로 돌아갑니다.
   • 입력 :
     • query (문자열, 필수): 로컬 검색 쿼리(예: "내 근처 피자", "도심의 카페")
     • count (숫자, 선택 사항): 최대 결과 수(1-20, 기본값 5).
   • 출력 : 로컬 비즈니스 세부 정보(이름, 주소, 전화번호, 평가 등)를 포함하는 MCP 메시지를 스트리밍합니다.

( curl 사용한 예 - 참고: 실제 MCP 상호 작용에는 클라이언트 라이브러리가 필요합니다)

클라이언트 구성 예(커서)

Cursor와 같은 MCP 클라이언트와 함께 이 서버를 사용하려면 클라이언트를 구성하여 서버의 SSE 엔드포인트에 연결해야 합니다.

커서 설정( mcp.json 또는 유사한 구성 파일)에 다음 구성을 추가하고 URL을 brave-search-mcp-sse 서버에 액세스할 수 있는 실제 주소와 포트로 바꾸세요.

설명:

• transport : 이 서버에서는 "sse" 로 설정해야 합니다.
• url : 이게 중요한 부분이에요.
  • Docker를 통해 로컬로 실행하는 경우(예시에서 보여준 대로) http://localhost:8080/sse 올바를 가능성이 높습니다.
  • Kubernetes에서 실행하는 경우 localhost:8080 적절한 Kubernetes 서비스 주소/포트 또는 서버의 포트 8080에 도달하도록 구성된 Ingress 호스트 이름/경로로 바꾸세요.
  • URL 경로가 /sse 로 끝나는지 확인하세요.

(최신 버전의 Claude Desktop과 같이 SSE 전송을 지원하는 다른 MCP 클라이언트에도 유사한 구성 단계가 적용될 수 있지만, 자세한 내용은 해당 클라이언트의 설명서를 참조하세요.)

프로젝트 구조

기여하다

기여를 환영합니다! 변경 사항을 포함하여 풀 리퀘스트를 제출해 주세요. 코드가 기존 스타일을 준수하고 필요한 경우 테스트를 포함하는지 확인하세요. 시간이 허락하는 대로 풀 리퀘스트를 검토하겠습니다.

특허

이 프로젝트는 MIT 라이선스 에 따라 라이선스가 부여됩니다(LICENSE 파일이 존재하거나 추가될 예정이라고 가정).