Episkey-G/GrokSearch-rs

GrokSearch‑rs – 用于网络搜索工具的轻量级 Rust MCP 服务器

它是什么 – 一个实现 Claude 风格助手使用的 MCP（Model‑Client‑Protocol）服务器的小型、可自托管的 Rust 二进制文件。它提供一组工具（web_search、get_sources、web_fetch、web_map、doctor、可选的 x_search），让 LLM 能够检索、引用和渲染实时网络内容。服务器可以通过 stdio 在本地运行（由客户端启动），也可以作为 可流式 HTTP 端点暴露，用于移动或多设备使用。

为什么重要 – 现代 LLM 代理需要最新、可验证的信息。GrokSearch‑rs 通过以下方式提供这一点：

• 以可配置的顺序查询多个外部搜索提供商（Tavily、Exa、TinyFish、Firecrawl）。
• 使用无需 API 密钥即可工作的 GitHub、StackExchange、arXiv 和 Wikipedia 专用提取器来丰富结果。
• 保持会话缓存，以便后续调用（get_sources）无需重新搜索即可检索相同的引用。
• 尊重令牌限制：它会修剪响应以保持在可配置的字符预算内，并允许您选择简洁或详细的负载。
• 同时支持 xAI 的 Grok Responses API 和任何 OpenAI 兼容的聊天完成网关，可通过环境变量选择。

主要功能（如 README 中所列）

功能	作用
带引用的实时网络搜索	返回摘要以及顶级来源的元数据；include_content 可以嵌入提取的完整文本。
响应预算	限制内联来源文本（max_inline_sources）和总字符数（response_max_chars）。
结构化的 web_fetch	将 GitHub 问题/PR、StackExchange 线程、arXiv 论文、Wikipedia 页面解析为干净的 Markdown；对于其他 URL，回退到通用来源链。
两种传输方式	原生 xAI Responses（/v1/responses）或任何 OpenAI 兼容的 chat/completions 端点。
可选的 Grok OAuth 模式	存储本地 OAuth 令牌，以便服务器无需 API 密钥即可运行。
远程 HTTP 模式（功能 http）	多租户、可流式 HTTP 服务器；密钥通过请求头按请求发送，绝不存储在服务器上。
可插拔来源链	有序提供商（Tavily → Exa → TinyFish → Firecrawl），支持轮询密钥轮换和故障转移。
X/Twitter 搜索（x_search）	仅在 Grok Responses 传输上可用。
并发	处理最多 8 个同时的 stdio 工具调用；额外的调用排队。
doctor 工具	快速健康检查，报告连接性和脱敏配置。

安装

npm install -g grok-search-rs   # 获取预构建的原生 Rust 二进制文件

安装的 grok-search-rs 命令就是 MCP 客户端启动的命令。

运行选项

• StdIO（本地） – 默认。客户端将二进制文件作为子进程启动，并通过 stdin/stdout 通信。
• 远程 HTTP – 使用 --features http 编译（或使用提供的 Docker 镜像）。然后服务器在可配置的地址（GROK_MCP_BIND）上监听，并通过可流式 HTTP 端点提供相同的工具。

配置 – 所有设置都可以通过环境变量（stdio 模式）或 HTTP 头（远程模式）提供。一个全局 TOML 文件（~/.config/grok-search-rs/config.toml）可以保存密钥，以便多个客户端共享。

核心变量（摘录）：

GROK_SEARCH_API_KEY   – xAI/Grok 的 Bearer 令牌（OAuth 时留空）
GROK_SEARCH_URL       – Grok 网关的基本 URL（默认 https://api.x.ai）
TAVILY_API_KEY        – 通用网络搜索必需；可以是逗号分隔的列表以进行轮换
FIRECRAWL_API_KEY     – 启用 Firecrawl 回退
EXA_API_KEY, TINYFISH_API_KEY – 在链中启用这些提供商
GROK_SEARCH_MODEL     – 要发送的模型名称（例如 grok-4.20-fast）
GROK_SEARCH_RESPONSE_MAX_CHARS – 整个响应的预算（默认 45 000）

HTTP 传输的头遵循相同的命名方案，例如 X-Grok-Api-Key、X-Tavily-Api-Key。

典型工作流程

1. 搜索 – 使用查询调用 web_search。服务器返回简洁的答案以及来源列表；顶部的 max_inline_sources 可能包含提取的文本。
2. 获取详细信息 – 在任何来源 URL 上使用 web_fetch 获取干净的 Markdown（专用提取器为 GitHub、StackExchange、arXiv、Wikipedia 提供更丰富的输出）。
3. 分页来源 – 如果原始搜索产生了许多引用，get_sources 允许客户端分页浏览。
4. 诊断 – 运行 doctor 以验证所有上游 API 是否可达以及配置是否正确加载。

自托管 – 发布了适用于 Linux x86_64 和 aarch64 的预构建二进制文件，以及 Docker 镜像（ghcr.io/episkey-g/grok-search-rs）。Dockerfile 和附带的 docker‑compose.yml/Caddyfile 支持一键 HTTPS 部署。

开发 – 该仓库是一个标准的 Rust 项目。从源代码构建：

cargo build --release               # stdio 二进制文件
cargo build --profile release-http --features http   # 启用 HTTP 的二进制文件

使用标准 Rust 工具（cargo fmt、cargo clippy、cargo test）。

谁可能使用它 – 任何构建需要可靠、带引用的网络搜索功能的 LLM 驱动的助手（Claude、ChatGPT、自定义代理）的人，尤其是当他们想要完全控制密钥、缓存和响应大小时。