reliable-web-search v0.3.0 — CLI and MCP

English | 简体中文

English

reliable-web-search v0.3.0 — Unified CLI, Interactive Setup, MCP Server

This release introduces the rws CLI, interactive setup wizard, stdio-based MCP server, and agent host adapters for OpenClaw, Codex, and Claude Code. Search is now configurable at the command line in one continuous flow.

Highlights

• Unified CLI (rws) — single entry point for setup, search, agent registration, and diagnostics
• Interactive setup wizard — provider selection, hidden API key input, connection verification, agent detection, multi-host installation
• Stdio MCP server (rws mcp) — exposes reliable_web_search via @modelcontextprotocol/sdk
• Agent adapters — OpenClaw (verified), Codex (beta), Claude Code (beta), Generic MCP (standard)
• Proxy support — HTTP_PROXY, HTTPS_PROXY, NO_PROXY via undici EnvHttpProxyAgent
• Local config storage — config.json + credentials.json (0600 on Unix), atomic writes
• rws doctor — Node.js, config, credentials, providers, MCP, and agent health checks
• 8 packaged CLI/MCP smoke tests

Install

npm install --global reliable-web-search

Quick Start

rws setup
rws "latest RISC-V news"
rws doctor

Full Changelog

See CHANGELOG.md.

---

简体中文

reliable-web-search v0.3.0 — 统一 CLI、交互式配置、MCP 服务器

本版本引入了 rws CLI、交互式配置向导、基于 stdio 的 MCP 服务器，以及 OpenClaw、Codex 和 Claude Code 的 Agent 适配器。现在可以在一个连续流程中通过命令行完成搜索配置。

亮点

• 统一 CLI（rws） ——配置、搜索、Agent 注册、诊断的单一入口
• 交互式配置向导——供应商选择、隐藏的 API Key 输入、连接验证、Agent 检测、多宿主安装
• Stdio MCP 服务器（rws mcp）——通过 @modelcontextprotocol/sdk 暴露 reliable_web_search
• Agent 适配器——OpenClaw（已验证）、Codex（Beta）、Claude Code（Beta）、Generic MCP（标准）
• 代理支持——通过 undici EnvHttpProxyAgent 支持 HTTP_PROXY、HTTPS_PROXY、NO_PROXY
• 本地配置存储——config.json + credentials.json（Unix 0600），原子写入
• rws doctor——Node.js、配置、凭据、供应商、MCP 和 Agent 健康检查
• 8 个打包 CLI/MCP 冒烟测试

安装

npm install --global reliable-web-search

快速开始

rws setup
rws "latest RISC-V news"
rws doctor

完整变更日志

参见 CHANGELOG.md。

reliable-web-search v0.4.0 — Multi-provider and Multi-credential Routing

English | 简体中文

English

reliable-web-search v0.4.0 — Multi-Provider, Multi-Credential, Credential Failover

v0.4.0 is the most significant upgrade to date. It transforms the project from a single-credential-per-provider tool into a multi-provider, multi-credential search router with credential-level failover, iterative setup, and route-aware MCP output.

Highlights

• Multiple credential profiles per provider — e.g., tavily.personal, tavily.backup, brave.workspace. Each profile is a separate API key.
• Credential-level failover — rate_limited, quota_exhausted, and authentication_failure switch to the next credential for the same provider before falling back to the next provider.
• Two-layer failover semantics — Layer 1: try next credential (same provider). Layer 2: try next provider.
• Iterative multi-credential setup wizard — rws setup now lets you add multiple providers and multiple credentials in one session. Route review and confirmation happens before agent detection.
• Credential and route management commands — rws credentials list|add|remove|enable|disable and rws routes list|move|enable|disable.
• Route-aware providerPath and AttemptRecord — providerPath uses route identifiers (tavily.personal → tavily.backup → brave.default). AttemptRecord includes routeId and credentialProfile.
• Ephemeral environment variable routes — TAVILY_API_KEY etc. automatically create a <provider>.env route at runtime. Higher priority than file credentials. Never persisted to disk.
• Automatic v1→v2 migration — existing configs from 0.3.x are migrated atomically on first load. Backups are created. Corrupted files are preserved.
• Route-aware rws doctor — per-route configuration completeness, credential status, ephemeral env routes. --live --all-credentials warns and checks every credential individually.
• 196 tests, 0 failures — all previous tests pass plus new env route, credential failover, and multi-credential tests.

Install / Upgrade

npm install --global reliable-web-search@0.4.0
rws setup

Existing v1 configurations are migrated automatically.

Example Route

After setup with two Tavily keys and one DuckDuckGo route:

 1. tavily.default        (highest priority)
 2. tavily.backup-2       (same provider, backup key)
 3. duckduckgo            (keyless fallback)

Quick Start

rws setup
rws "latest RISC-V news"
rws credentials list
rws routes list
rws doctor

Migration

If you were using v0.3.x, your existing config is automatically migrated to the new v2 format on first run:

• config.json — flat providers: string[] → routes[] with id, providerId, priority
• credentials.json — flat key-value map → { version: 2, profiles: { ... } }

Both migrations are atomic. A backup of the original files is preserved. If a file is corrupted, the tool reports the error and uses defaults without overwriting.

Security

• API keys are stored only in credentials.json (Unix: 0600 permissions)
• Never written into config.json, MCP host configs, stdout, stderr, logs, or tool responses
• CLI output shows only masked keys: BSA••••7A9
• Ephemeral env routes are never persisted to disk
• Same-key dedup prevents duplicate credentials

Compatibility

• The old providers: string[] SDK signature is fully backwards-compatible
• Agent host adapters remain unchanged (still just rws mcp)
• ESM + CJS dual build
• Node 18+ required (uses native fetch)

Known Limitations

• Setup wizard requires a TTY. Non-TTY environments should use rws credentials add, rws routes list, etc.
• Credential policy supports failover only. Round-robin, weighted, or health-score-based selection is not implemented.
• No usage accounting, cloud accounts, or Web UI. This is a local CLI tool.
• DuckDuckGo is an Instant Answer API fallback, not full web search. Not suitable for production search volume.

Full Changelog

See CHANGELOG.md.

---

简体中文

reliable-web-search v0.4.0 — 多供应商、多凭据、凭据级故障转移

v0.4.0 是迄今为止最重要的升级。它将项目从"每个供应商一个凭据"的工具，转变为多供应商、多凭据搜索路由引擎，具备凭据级故障转移、循环式配置和路由感知的 MCP 输出。

亮点

• 同一供应商多个凭据——如 tavily.personal、tavily.backup、brave.workspace。每个 profile 是一个独立的 API Key。
• 凭据级故障转移——rate_limited、quota_exhausted、authentication_failure 会在同一供应商内切换凭据，才考虑降级到下一个供应商。
• 双层故障决策——第一层：切换凭据（同一供应商）。第二层：切换供应商。
• 循环式多凭据配置向导——rws setup 现在允许在一次会话中添加多个供应商和多个凭据。路由审查和确认在 Agent 检测之前进行。
• 凭据和路由管理命令——rws credentials list|add|remove|enable|disable 和 rws routes list|move|enable|disable。
• 路由感知的 providerPath 和 AttemptRecord——providerPath 使用路由标识符（tavily.personal → tavily.backup → brave.default）。AttemptRecord 包含 routeId 和 credentialProfile。
• 临时环境变量路由——TAVILY_API_KEY 等自动在运行时创建 <provider>.env 路由。优先级高于文件凭据。决不写入磁盘。
• 自动 v1→v2 迁移——现有 0.3.x 配置首次加载时自动原子迁移。创建备份。保留损坏文件。
• 路由感知 rws doctor——每条路由的配置完整性、凭据状态、临时环境变量路由。--live --all-credentials 逐个验证每个凭据。
• 196 测试，0 失败——所有之前的测试通过，新增环境变量路由、凭据故障转移和多凭据测试。

安装 / 升级

npm install --global reliable-web-search@0.4.0
rws setup

已有 v1 配置会自动迁移。

示例路由

配置两个 Tavily Key 和一个 DuckDuckGo 路由后：

 1. tavily.default        (最高优先级)
 2. tavily.backup-2       (同一供应商，备用 Key)
 3. duckduckgo            (无需 Key 的兜底)

快速开始

rws setup
rws "latest RISC-V news"
rws credentials list
rws routes list
rws doctor

迁移

如果你使用的是 v0.3.x，现有配置会在首次运行时自动迁移到新的 v2 格式：

• config.json 扁平 providers: string[] → routes[]（含 id、providerId、priority）
• credentials.json 扁平 key-value 映射 → { version: 2, profiles: { ... } }

两次迁移均为原子操作。原始文件的备份会保留。如果文件损坏，工具会报错并使用默认值，不会覆盖。

安全

• API Key 仅保存在 credentials.json（Unix：0600 权限）
• 不会写入 config.json、MCP 宿主配置、stdout、stderr、日志或工具响应
• CLI 输出仅显示掩码 Key：BSA••••7A9
• 临时环境变量路由决不写入磁盘
• 同 Key 去重防止重复凭据

兼容性

• 旧的 providers: string[] SDK 签名完全向后兼容
• Agent 宿主适配器保持不变（仍然是 rws mcp）
• ESM + CJS 双构建
• 需要 Node 18+（使用原生 fetch）

已知限制

• 配置向导需要 TTY。非 TTY 环境应使用 rws credentials add、rws routes list 等命令。
• 凭据策略仅支持 failover。Round-robin、加权或基于健康评分的选择尚未实现。
• 无用量统计、云端账户或 Web UI。这是本地 CLI 工具。
• DuckDuckGo 是 Instant Answer API 兜底，不是全文搜索。不适合生产搜索规模。

完整变更日志

参见 CHANGELOG.md。

v0.2.0

[0.2.0] — 2026-06-19

Added

• Provider priority system — explicit priority and capabilities fields on every provider
• Structured ProviderError — providerId, code, status, retryable, shouldBreakerTrip
• AttemptRecord[] diagnostics — per-attempt provider, status, timing, error codes, HTTP status
• Result status machine — success | partial | no_results | failed | aborted
• cacheHit field — distinguishes cached from live results
• Typo suggestions — misspelled provider names throw with Levenshtein suggestions
• Provider isConfigured() gate — SearXNG requires explicit BASE_URL
• experimental capability flag — Bocha/Metaso marked until API verified
• Dual ESM/CJS build via tsup
• Smoke tests — ESM import + CJS require verified

Changed

• fallback/race/aggregate replaces sequential/parallel/best-effort
• True AbortController timeout — provider fetch aborted on timeout
• Race: Promise.allSettled + independent controllers — immutable attempts
• Breaker config passthrough — per-call config reaches instances
• Unified runProviderAttempt — shared by all three modes
• DDG empty results trigger fallback — no fake placeholder
• Registry respects priority + isConfigured()

Fixed

• Cache hits return complete shape
• lastHttpStatus from error objects
• SearXNG no localhost default
• Bocha official webPages.value schema

Docs

• README: honest DDG disclaimer, provider table with priority/status

v0.1.0

[0.1.0] — 2026-06-19

Added

• Initial release
• 8 built-in search providers: DuckDuckGo, Brave, Bocha (博查), Metaso (秘塔), Tavily, Gemini, SerpAPI, SearXNG
• Sequential fallback chain with automatic provider failover
• Circuit breaker with three states (closed / open / half-open)
• Error classification system (8 categories)
• TTL-based LRU result cache (15 min default)
• Three fallback modes: sequential, parallel, best-effort
• Zero-config auto-detection from environment variables
• Custom provider registration API
• Expressive retry with exponential backoff
• Per-provider timeout support
• Full TypeScript type definitions with strict mode
• Comprehensive test suite (105 tests, 0 failures)
• Zero runtime dependencies
• MIT license