SearXNG MCP 브리지 서버

이 서버는 SearXNG 인스턴스에 대한 브리지 역할을 하는 MCP(Model Context Protocol) 서버입니다. 호환되는 클라이언트가 MCP 도구를 통해 구성된 SearXNG 인스턴스를 사용하여 검색을 수행할 수 있도록 합니다.

요구 사항

• Node.js 25.x

• npm 11.x 이상

빠른 시작 (npm 사용)

1. SearXNG 인스턴스 설정:

   # Using Docker
   docker run -d -p 8888:8080 --name searxng searxng/searxng

2. MCP 브리지 설치 및 실행

   기본값 (STDIO, 변경 없음):

   # Run directly with npx (default - stdio transport)
   npx -y @nitish-raj/searxng-mcp-bridge

   선택 사항: HTTP 서버로 실행 (새로운 기능, 선택적)

    # Using env variables (recommended)
     TRANSPORT=http PORT=3002 HOST=127.0.0.1 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge
   
   
   
   # Or run the built bundle
   TRANSPORT=http node build/index.js

3. MCP 설정 파일에 구성 (stdio / 레거시 클라이언트) MCP 설정 파일(예: ~/.vscode-server/.../mcp_settings.json)에 추가:

   {
     "mcpServers": {
       "searxng-bridge": {
         "command": "npx",
         "args": [
          "-y",
          "@nitish-raj/searxng-mcp-bridge"
          ],
          "env": {
            "SEARXNG_INSTANCE_URL": "http://localhost:8080"
          },
         "disabled": false
       }
     }
   }

HTTP 구성: TRANSPORT=http를 설정하여 stdio 대신 HTTP를 통해 브리지를 실행합니다. 전송 모드는 환경 변수를 통해 구성할 수 있습니다.

기능

• 검색 도구: 구성 가능한 매개변수를 사용하여 SearXNG로 웹 검색 수행

• 상태 확인: SearXNG 인스턴스 연결 및 성능 모니터링

• 이중 전송: STDIO(기본값) 및 HTTP 전송 모두 지원

• 세션 관리: HTTP 전송에는 세션 기반 연결 포함

• CORS 지원: 웹 클라이언트 통합을 위한 적절한 교차 출처 헤더

• 속도 제한: 과도한 요청에 대한 내장 보호 기능 (HTTP 모드)

구성

• SEARXNG_INSTANCE_URL — 필수. SearXNG 인스턴스의 전체 URL (예: http://localhost:8080).

• TRANSPORT — 전송 프로토콜: stdio (기본값) 또는 http

• PORT — HTTP 서버 포트. 기본값: 3000 (개발 시 3002 사용)

• HOST — 서버 바인딩 주소. 기본값: 127.0.0.1 (컨테이너의 경우 0.0.0.0 사용)

• CORS_ORIGIN — CORS에 허용된 출처의 쉼표로 구분된 목록. 기본값: localhost:3002 (개발) 또는 * (프로덕션)

• MCP_HTTP_BEARER — HTTP 인증을 위한 선택적 베어러 토큰 HTTP 전송 기능:

• mcp-session-id 헤더를 사용한 세션 관리

• 출처 화이트리스트 검증을 통한 보안 CORS

• 속도 제한 (IP당 분당 100개 요청)

• MCP_HTTP_BEARER를 통한 선택적 베어러 인증

• DNS 리바인딩 보호

보안 참고 사항:

• CORS는 개발 환경에서 보안 화이트리스트를 사용합니다 (localhost:3002만 허용)

• 프로덕션 환경은 자격 증명이 필요한 요청에 대해 특정 출처를 반영합니다 (CORS 준수)

• 사용 사례에 맞게 허용된 출처를 사용자 지정하려면 CORS_ORIGIN을 설정하세요

• stdio 모드로 되돌리려면 TRANSPORT=stdio를 설정하세요

HTTP 전송

HTTP 전송은 다음 엔드포인트와 함께 MCP Streamable HTTP 사양(2025-03-26)을 구현합니다:

MCP 엔드포인트:

• POST /mcp - MCP 요청 전송

• GET /mcp - 알림을 위한 서버 전송 이벤트(SSE)

• DELETE /mcp - 세션 종료

• OPTIONS /mcp - CORS 프리플라이트 요청

시스템 엔드포인트:

• GET /healthz - 상태 확인 및 상태 정보

HTTP 엔드포인트 테스트:

curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

이것은 사용 가능한 도구(search 및 health_check) 목록이 포함된 JSON-RPC 응답을 반환합니다.

Docker

Dockerfile은 HTTP 전송을 위해 포트 8081을 노출합니다. 컨테이너를 실행하고 HTTP 액세스를 허용하려면:

# Build (example)
docker build -t searxng-mcp-bridge .

# Run mapping port 8081
 docker run -d -p 8081:8081 --env SEARXNG_INSTANCE_URL=http://localhost:8080 --name searxng-mcp-bridge searxng-mcp-bridge

# To run HTTP transport inside container:
 docker run -d -p 8081:8081 -e TRANSPORT=http -e PORT=8081 -e SEARXNG_INSTANCE_URL=http://localhost:8080 searxng-mcp-bridge

참고: 컨테이너화된 경우 HOST=0.0.0.0으로 설정하거나 기본 노출 포트 매핑을 사용하세요.

사용법

STDIO 클라이언트: 도구를 변경 없이 사용하세요 - 구성 변경이 필요하지 않습니다.

HTTP 클라이언트: http://localhost:3002/mcp (개발 포트)에 연결하고 MCP JSON-RPC 요청을 보냅니다.

개발

• npm install: 종속성 설치.

• npm run build: TypeScript를 JavaScript로 컴파일.

• npm run watch: 변경 사항을 감시하고 자동으로 다시 빌드.

• npm run inspector: MCP 인스펙터를 실행하여 서버 테스트.

• npm run start:http: localhost:3002에서 HTTP 스트리밍 모드로 서버 시작.

마이그레이션 및 호환성

하위 호환성:

• STDIO는 기본 전송으로 유지됩니다 - 기존 사용자는 변경할 필요가 없습니다

• 모든 도구 이름, 매개변수 및 응답은 변경되지 않습니다

• 구성은 환경 변수를 통해 선택적으로 수행됩니다

HTTP로 마이그레이션:

• HTTP 전송을 활성화하려면 TRANSPORT=http를 설정하세요

• 필요에 따라 PORT 및 HOST를 구성하세요

• 클라이언트를 업데이트하여 stdio 대신 HTTP 엔드포인트를 사용하세요

롤백:

• stdio 모드로 돌아가려면 TRANSPORT=stdio를 설정하거나 변수를 생략하세요