SourceWeave Web Search

SourceWeave Web Search

以搜索为先的 MCP 服务和命令行工具，用于网络研究。

说明

sourceweave-search-mcp 是默认的本地入口点。如果未设置明确的 SOURCEWEAVE_SEARCH_* 端点变量，它会自动发现或启动由 Docker 支持的本地服务栈。如果你已自行运行这些服务，请设置明确的端点，它就会改用这些端点。

概览 • 快速入门 • 托管本地运行时 • MCP 客户端设置 • 命令行工具 • 容器部署 • OpenWebUI • 运行时配置 • 开发

概览

SourceWeave Web Search 为 MCP 客户端提供精简的三工具网络研究接口：

• search_web(query, domains?, urls?, effort?) 可发现来源，并返回带有稳定 page_id 句柄的精简结果。
• read_pages(page_ids, focus?) 通过 page_id 读取已存储的页面。
• read_urls(urls, focus?) 无需先搜索即可读取指定 URL。

它整合了：

组件	用途
SearXNG	搜索发现
Crawl4AI	提取整洁的 HTML
Redis or Valkey	持久化页面缓存和 page_id 存储
MarkItDown	转换 PDF 和其他受支持文件的文档

快速入门

要求

• Python 3.12+
• Docker，且支持 Compose，以便使用默认的托管本地运行时
• 只有在要使用托管服务或自我管理服务时，才需要设置明确的 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 托管服务栈
找到运行正常的外部服务栈	重用规范本地端口 19080、19235 和 16379，而不获取其所有权
没有可重用的服务栈	在规范本地端口或可用端口上启动并管理由 Docker 支持的服务栈

托管状态存储在 ~/.sourceweave-local/managed-runtime 下。同一台机器上的多个 MCP 进程会在每个状态目录中共享一个托管服务栈。

重要

只有最后一个仍在运行的 SourceWeave 托管进程退出时，托管运行时才会删除容器。命名卷会保留，因此缓存数据可在重启后继续使用。如果最初的所有者进程意外退出，后续进程可以通过 Docker 项目标识和持久化运行时状态恢复同一服务栈。

明确端点模式

如果你已自行运行 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

直接使用命令行工具

sourceweave-search 可直接运行该工具。如果支持服务已可用，或你提供了明确的端点，请使用此命令。它不会启动 Docker。

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

提示

直接使用命令行工具时，也可以通过 --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 启动。容器化部署仍需显式配置端点。

• 镜像：ghcr.io/mrnaqa/sourceweave-web-search-mcp
• 仓库本地 compose 入口：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

此仓库还提供了一个生成的独立 OpenWebUI 工具文件，路径为 artifacts/sourceweave_web_search.py。

在检出仓库后，验证它与规范实现保持同步：

uv run sourceweave-build-openwebui --check

如果要使用独立工具文件部署方式，请将该文件粘贴到 OpenWebUI 中。生成的文件会将默认端点改写为仓库本地 compose 服务名称，因此开箱即用，符合容器部署方式。

运行时配置

可选环境变量：

变量	用途
SOURCEWEAVE_SEARCH_SEARXNG_BASE_URL	SearXNG URL 模板。必须包含 <query>。
SOURCEWEAVE_SEARCH_CRAWL4AI_BASE_URL	Crawl4AI 基础 URL。
SOURCEWEAVE_SEARCH_CACHE_REDIS_URL	用于缓存的 Redis 或 Valkey URL。
FASTMCP_HOST	sse 或 streamable-http 传输方式的主机。
FASTMCP_PORT	sse 或 streamable-http 传输方式的端口。

如果未设置端点变量，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"