用途
SearchForge 是面向 LLM、AI 智能体以及检索增强生成（RAG）流程的免费开源 Web 搜索 API 和 MCP 服务器。它旨在提供一个可预测的检索层，让项目不必强制集成付费搜索厂商。它不会生成答案、不会隐藏引用、不会抓取公共 SearXNG 实例，也不会发送遥测数据。
主要能力
- 按能力路由的搜索：默认的
auto类别会检测代码、学术和时事/社区信号，并查询匹配的来源家族以及 Web 回退。显式类别可避免查询不相关的提供商。显式提供providers列表会覆盖类别路由，适合评估场景。 - URL 转 Markdown：
read_url仅接受公开的 HTTP(S) URL，拒绝凭据、localhost、私有 IP 字面量和非 Web 协议。响应有大小限制、超时和缓存。 - 诊断整条检索路径：
doctor执行真实、有界的探测，报告每个提供商的访问层级、能力、延迟和错误。某个来源失败时会产生degraded状态，而不是误导性的全有或全无状态。 - 覆盖的来源：GitHub、Crossref、Hacker News、Wikipedia 以及私有 SearXNG。GitHub token 仅用于提升公共 API 配额，Brave 是可选的需要密钥的后端。广泛、独立的 Web 元搜索由随附的 SearXNG 栈提供。
- 免费与自托管优先：所有零密钥适配器默认启用。
使用方式
无需克隆即可试用：首次运行会从 GitHub 下载并构建包。除非选择类别，搜索默认使用意图感知的 auto 路由。
零密钥本地 CLI：可进行完整 Web 搜索，配合私有 SearXNG。该方式会在端口 3000 启动 SearchForge，并在端口 8080 启动一个支持 JSON 的私有 SearXNG。在对外暴露该栈之前，需要更改 SearXNG 密钥、设置 SEARCHFORGE_API_KEY，并在受信任的代理处终止 TLS。
MCP 服务器：可直接从 GitHub 运行，无需克隆。SearchForge 已在官方 MCP Registry 中发布为 io.github.divyanshu-iitian/searchforge。对于支持 Docker 命令的 MCP 客户端，可直接运行由注册表支持的 OCI 镜像。
MCP 工具：SearchForge 暴露三个 stdio 工具：
web_search— 已路由、可直接引用的结构化搜索read_url— 从公开 URL 获取干净的 Markdownsearch_status— 实时能力与延迟报告
搜索和状态工具会同时返回 MCP 结构化内容和可读文本。
REST 接口：提供 OpenAPI 契约。其他端点请参阅完整 OpenAPI 契约。npm 发布前需要使用替代方式。
适用场景
- 为 LLM 或 AI 智能体提供可控的 Web 检索能力
- RAG 流水线中的检索层
- 需要避免供应商锁定、偏好免费或自托管路径的项目
- 需要按代码、学术、时事/社区等意图分流的搜索评估
- 将公开网页内容转为 LLM 可用的 Markdown
限制
- SearchForge 有意不配置公共 SearXNG 实例，因为它们常禁用 JSON 或限制自动化流量；Docker 栈是稳定的免费路径。
- 搜索结果的页面内容属于不可信输入，需要分隔并应用提示注入防御。
- 内置缓存和速率限制是进程本地的；多副本部署应使用共享基础设施。
- 提供商响应体和凭据不会出现在报错中。
healthz仅证明进程存活；/v1/doctor用于检查依赖。- 生产环境在绑定公网接口前必须设置 API key。
- 每个幂等的提供商调用都有独立的可中止超时；单个故障不会抹掉健康结果。跟踪参数会在去重前移除，每个有贡献的提供商都会保留在
sources中。
设计原则
- 证据优先于生成答案
- 免费和自托管路径优先于供应商锁定
- 部分结果优于完全失败
- 诚实报告能力和配额
- 稳定契约和明确来源
- 默认不发送遥测
项目采用 MIT 许可证，版权归 Divyanshu 所有。
