Codex Brave Web Search

codex勇敢的网络搜索

用于Codex的Rust MCP服务器，具有完整的Brave网络/新闻/图像/视频报道和Codex优先的结构化响应。

• 服务器名称： brave-web-search
• 工具：

- brave_web_search - brave_web_search_help - brave_web_search_status

特性

• 严格的请求解析(deny_unknown_fields)具有结构化 INVALID_ARGUMENT 错误信封。
• Brave端点支持 web, news, images，以及 videos.
• 重试/回退策略：

- 3次重试（共4次尝试） - 具有抖动的指数退避 - 最大延迟5s - 每次尝试超时15秒 - Retry-After 支持

• 内存缓存：

- TTL 5分钟 - 按规范化请求哈希键控 - 绕过时 freshness 已明确设置

• 本地节流：2次/秒，爆裂4次。
• 输出截断默认值：120行/32KB。
• 使用有界箝位的每次调用输出覆盖：

- 最少：20行/4KB - 最大：300行/96KB

• 基于规范化URL策略进行URL重复数据消除，以实现稳定的横截面重复数据消除。
• 调试具有上限原始有效负载输出（64KB上限）的控件。

构建

cargo build --release --locked

二元的：

target/release/codex-brave-web-search

从crates.io安装（主分支发布）

每一次推动 main 通过GitHub Actions向crates.io发布新的预发布版本。 每次成功发布还会在存储库发布页面下创建一个GitHub预发布条目 带标签 v . 使用工作流摘要中发布的版本进行安装：

cargo install codex-brave-web-search --version 

在Codex注册

自动（推荐）

sh scripts/register-mcp.sh

此脚本：

• 构建发布二进制文件
• 备份任何现有 brave-web-search MCP配置
• 注册新服务器
• 打印回滚命令

卸载：

sh scripts/uninstall-mcp.sh

从备份还原：

sh scripts/restore-mcp-from-backup.sh 

手册

codex mcp add brave-web-search -- "$(pwd)/target/release/codex-brave-web-search"

检查：

codex mcp get --json brave-web-search

删除：

codex mcp remove brave-web-search

环境

实时Brave请求需要

• BRAVE_SEARCH_API_KEY （首选）
• 退路： BRAVE_API_KEY

查找顺序为 BRAVE_SEARCH_API_KEY那么 BRAVE_API_KEY.

运行时配置(CODEX_BRAVE_*)

• 输出限制：

- CODEX_BRAVE_DEFAULT_MAX_LINES - CODEX_BRAVE_DEFAULT_MAX_BYTES - CODEX_BRAVE_MIN_MAX_LINES - CODEX_BRAVE_MIN_MAX_BYTES - CODEX_BRAVE_MAX_MAX_LINES - CODEX_BRAVE_MAX_MAX_BYTES

• 缓存/节流：

- CODEX_BRAVE_CACHE_TTL_SECS - CODEX_BRAVE_THROTTLE_RATE_PER_SEC - CODEX_BRAVE_THROTTLE_BURST

• 重试/超时/正文大写：

- CODEX_BRAVE_RETRY_COUNT - CODEX_BRAVE_RETRY_BASE_DELAY_MS - CODEX_BRAVE_RETRY_MAX_DELAY_MS - CODEX_BRAVE_PER_ATTEMPT_TIMEOUT_MS - CODEX_BRAVE_MAX_RESPONSE_BYTES - CODEX_BRAVE_RAW_PAYLOAD_CAP_BYTES

• 查询上限：

- CODEX_BRAVE_MAX_QUERY_LENGTH

• 登录中：

- CODEX_BRAVE_LOG

• 端点覆盖：

- CODEX_BRAVE_ENDPOINT_WEB - CODEX_BRAVE_ENDPOINT_NEWS - CODEX_BRAVE_ENDPOINT_IMAGES - CODEX_BRAVE_ENDPOINT_VIDEOS

工具合同

1) brave_web_search

请求字段：

• 必修的： query
• 核心可选： search_type, result_filter （字符串数组）， max_results, offset, country, search_language, ui_language, safe_search, units, freshness, spellcheck, extra_snippets, text_decorations
• max_results 根据返回的章节适用；适用于具有多个 result_filter 部分，返回的总结果可能超过 max_results.
• 输出控制： max_lines, max_bytes
• 调试控件： debug, include_raw_payload, disable_cache, disable_throttle, include_request_url

验证行为：

• 未知字段：硬错误
• 空查询：硬错误
• 查询>2000个字符：截断并警告
• 无效 search_type：硬错误
• 无效的区域设置/安全/单位/新鲜度字段：警告+忽略
• result_filter 对于非网络：警告+忽略
• 无效 result_filter 令牌：

- 如果至少存在一个有效令牌：警告+忽略无效令牌 - 如果没有有效：硬错误

成功信封字段：

• 顶级： api_version, summary, sections, meta, warnings
• 可选的 debug_data 当 debug=true
• 无评分字段

错误信封字段：

• api_version
• error.code
• error.message
• 可选的 error.details
• meta.provider, meta.server_version, meta.trace_id

示例：

{ "query": "TypeScript generics" }

{ "query": "OpenAI", "search_type": "news", "max_results": 3 }

{
  "query": "Kubernetes",
  "country": "US",
  "search_language": "en",
  "ui_language": "en-US",
  "result_filter": ["web", "discussions", "not-real"]
}

{
  "query": "websocket server",
  "debug": true,
  "include_request_url": true,
  "include_raw_payload": true
}

2) brave_web_search_help

请求：

{ "topic": "params|examples|limits|errors|all" }

返回结构化的帮助部分和markdown示例。

3) brave_web_search_status

请求：

{ "probe_connectivity": false, "verbose": false, "include_limits": false }

笔记：

• 默认 probe_connectivity=false
• 启用后，使用查询探测所有四个Brave端点 mcp healthcheck
• 部分故障会导致每个端点诊断的状态下降

测试

脱机确定性路径（不需要API密钥）：

cargo test -- --skip live_

Live Brave烟雾测试（需要密钥）：

cargo test --test live_smoke

质量门 just:

just verify-offline
just verify

just verify 跑：

1. cargo fmt --all
2. cargo clippy --all-targets --all-features -- -D warnings
3. 离线测试
4. 现场测试

模糊测试

安装货物绒毛一次：

cargo install cargo-fuzz

运行目标：

cargo fuzz run parse_sections
cargo fuzz run parse_brave_error_message

Fuzz配置位于：

• fuzz/Cargo.toml
• fuzz/fuzz_targets/

可选的CI/CD发布模板

默认情况下，模板已包含但处于非活动状态：

• .github/workflow-templates/ci.template.yml
• .github/workflow-templates/release-tag.template.yml

将它们复制到 .github/workflows/ 激活。