SourceWeave Web Search

웹 리서치를 위한 검색 우선 MCP 서버 및 CLI.

[!NOTE] sourceweave-search-mcp는 기본 로컬 진입점입니다. 명시적 SOURCEWEAVE_SEARCH_* 엔드포인트 변수가 없으면 로컬 Docker 기반 스택을 자동으로 발견하거나 시작합니다. 이미 서비스를 직접 실행 중이라면 명시적 엔드포인트를 설정하면 대신 이를 사용합니다.

개요 • 시작하기 • 관리형 로컬 런타임 • MCP 클라이언트 설정 • CLI • 컨테이너 배포 • OpenWebUI • 런타임 구성 • 개발

개요

SourceWeave Web Search는 MCP 클라이언트에게 웹 리서치를 위한 간결한 3-도구 계약을 제공합니다:

• search_web(query, domains?, urls?, effort?)는 소스를 검색하고 안정적인 page_id 핸들을 가진 간결한 결과를 반환합니다.

• read_pages(page_ids, focus?)는 page_id로 저장된 페이지를 읽습니다.

• read_urls(urls, focus?)는 검색 없이 직접 URL을 읽습니다.

다음 구성 요소를 결합합니다:

Related MCP server: Deep Search MCP Server

시작하기

요구 사항

• Python 3.12+

• 기본 관리형 로컬 런타임을 위한 Compose 지원 Docker

• 호스팅 또는 자체 관리 서비스를 원하는 경우에만 명시적 SOURCEWEAVE_SEARCH_* 엔드포인트

관리형 로컬 런타임

게시된 패키지에서 서버를 실행합니다:

uvx --from sourceweave-web-search sourceweave-search-mcp

또는 HTTP로 MCP 서버를 시작합니다:

uvx --from sourceweave-web-search sourceweave-search-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000

엔드포인트 환경 변수가 설정되지 않은 경우, sourceweave-search-mcp는:

관리 상태는 ~/.sourceweave-local/managed-runtime 아래에 있습니다. 동일한 머신의 여러 MCP 프로세스는 상태 디렉터리당 하나의 관리 스택을 공유합니다.

[!IMPORTANT] 관리형 런타임은 마지막 활성 SourceWeave 관리 프로세스가 종료될 때만 컨테이너를 제거합니다. 명명된 볼륨은 보존되므로 캐시 데이터는 재시작 후에도 유지됩니다. 원래 소유 프로세스가 종료되면 이후 프로세스가 Docker 프로젝트 ID와 유지된 런타임 상태에서 동일한 스택을 복구할 수 있습니다.

명시적 엔드포인트 모드

이미 SearXNG, Crawl4AI, Redis 또는 Valkey를 직접 실행 중이거나 호스팅 서비스를 가리키려면 명시적 엔드포인트를 설정하면 MCP 진입점이 관리형 Docker 시작을 우회합니다:

SOURCEWEAVE_SEARCH_SEARXNG_BASE_URL="http://127.0.0.1:19080/search?format=json&q=<query>" \
SOURCEWEAVE_SEARCH_CRAWL4AI_BASE_URL="http://127.0.0.1:19235" \
SOURCEWEAVE_SEARCH_CACHE_REDIS_URL="redis://127.0.0.1:16379/2" \
uvx --from sourceweave-web-search sourceweave-search-mcp

직접 CLI

sourceweave-search는 도구를 직접 실행합니다. 지원 서비스가 이미 사용 가능하거나 명시적 엔드포인트를 제공할 때 사용하세요. Docker를 시작하지 않습니다.

sourceweave-search --query "python programming" --read-first-pages 2
sourceweave-search --read-url "https://packaging.python.org/en/latest/"

[!TIP] 직접 CLI는 --searxng-base-url, --crawl4ai-base-url, --cache-redis-url 재정의도 허용합니다.

MCP 클라이언트 설정

OpenCode

예: opencode.json / opencode.jsonc / ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sourceweave": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "sourceweave-web-search",
        "sourceweave-search-mcp"
      ],
      "enabled": true,
      "timeout": 300000
    }
  }
}

대신 공유 HTTP 엔드포인트를 사용하려면:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sourceweave": {
      "type": "remote",
      "url": "http://127.0.0.1:18000/mcp",
      "enabled": true,
      "timeout": 300000
    }
  }
}

VS Code Copilot

예: .vscode/mcp.json:

{
  "servers": {
    "sourceweave": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "sourceweave-web-search",
        "sourceweave-search-mcp"
      ]
    }
  }
}

대신 공유 HTTP 엔드포인트를 사용하려면:

{
  "servers": {
    "sourceweave": {
      "type": "http",
      "url": "http://127.0.0.1:18000/mcp"
    }
  }
}

Claude Code

예: .mcp.json:

{
  "mcpServers": {
    "sourceweave": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "sourceweave-web-search",
        "sourceweave-search-mcp"
      ]
    }
  }
}

프로젝트 범위 공유 구성을 위해 동일한 블록을 저장소 루트의 .mcp.json에 배치하세요.

CLI

직접 CLI는 지원 서비스에 이미 접근할 수 있을 때 유용합니다. MCP 래퍼 없이 동일한 검색 우선 워크플로를 제공합니다.

sourceweave-search --query "react useEffect cleanup example" --read-first-page
sourceweave-search --query "HTTP overview" --domain developer.mozilla.org --read-first-page
sourceweave-search --read-url "https://packaging.python.org/en/latest/"

컨테이너 배포

관리형 로컬 런타임은 호스트 측 uvx 또는 uv run 실행을 위한 것입니다. 컨테이너화된 배포는 여전히 명시적 엔드포인트 연결을 사용합니다.

• Image: ghcr.io/mrnaqa/sourceweave-web-search-mcp

• Repo-local compose entrypoint: docker compose up -d --build mcp

컨테이너 실행 예:

docker run --rm -p 8000:8000 \
  -e SOURCEWEAVE_SEARCH_SEARXNG_BASE_URL="http://host.docker.internal:19080/search?format=json&q=<query>" \
  -e SOURCEWEAVE_SEARCH_CRAWL4AI_BASE_URL="http://host.docker.internal:19235" \
  -e SOURCEWEAVE_SEARCH_CACHE_REDIS_URL="redis://host.docker.internal:16379/2" \
  ghcr.io/mrnaqa/sourceweave-web-search-mcp:latest

OpenWebUI

이 저장소는 artifacts/sourceweave_web_search.py에 생성된 독립형 OpenWebUI 도구 파일도 제공합니다.

저장소 체크아웃에서 정식 구현과 동기화되었는지 확인하세요:

uv run sourceweave-build-openwebui --check

독립형 도구 파일 배포 경로를 원할 때 해당 아티팩트를 OpenWebUI에 붙여넣으세요. 생성된 파일은 기본 엔드포인트를 저장소 로컬 compose 서비스 이름으로 다시 작성하므로 컨테이너 배포 경로와 즉시 일치합니다.

런타임 구성

선택적 환경 변수:

엔드포인트 변수가 설정되지 않은 경우 sourceweave-search-mcp는 관리형 로컬 런타임을 기본으로 사용합니다.

• 표준 호스트 엔드포인트는 선호되는 기본값이자 외부 재사용 프로브 대상으로 유지됩니다.

• SourceWeave 관리 스택은 표준 기본값이 이미 사용 중인 경우 다른 사용 가능한 호스트 포트를 사용할 수 있습니다.

• 동일한 머신의 여러 MCP 프로세스는 로컬 런타임 상태 디렉터리당 하나의 관리 스택을 공유합니다.

기본 엔드포인트 값:

• SearXNG: http://127.0.0.1:19080/search?format=json&q=<query>

• Crawl4AI: http://127.0.0.1:19235

• Redis: redis://127.0.0.1:16379/2

관리형 시작을 위한 기본 선호 호스트 포트:

• SearXNG: 19080

• Crawl4AI: 19235

• Redis: 16379

• MCP: uvx로 직접 실행할 때 8000; 저장소의 mcp compose 서비스를 사용할 때 /mcp에서 18000

개발

git clone https://github.com/MRNAQA/sourceweave-web-search.git
cd sourceweave-web-search
uv sync --locked --group dev
uv run sourceweave-search-mcp

유용한 검사:

uv run sourceweave-build-openwebui --check
uv run sourceweave-search-mcp --help
uv run pytest tests/test_config.py tests/test_packaging.py tests/test_tool.py tests/test_managed_runtime.py -m "not integration"