SearchForge

---

SearchForge 是一款面向大模型、AI Agent 和检索增强生成（RAG）工作流的免费开源 Web 搜索 API 和 MCP 服务。 它提供可预测的检索层，无需每个项目都集成付费搜索服务商。SearchForge 会将每个查询路由到合适的来源，隔离服务商故障，去重 URL，融合排名，并将公开网页转换为适用于大模型的 Markdown。

它不会生成答案、隐藏引用、抓取公开的 SearXNG 实例，也不会发送遥测数据。

你将获得

能力	默认来源	费用 / 凭据
auto	按意图路由的来源组合	默认无需密钥
web	Wikipedia；可选的私有 SearXNG	无需密钥 / 可自托管
code	GitHub 仓库搜索	无需密钥；令牌可选
academic	Crossref 作品和 DOI 元数据	无需密钥
community	通过 Algolia 访问 Hacker News	无需密钥，社区服务
read_url	Jina Reader	无需密钥，目前受速率限制

SearchForge 启动时会启用所有无需密钥的适配器。auto 是默认选项，会将代码、研究以及时效性 / 社区类意图路由到相关来源，同时保留 Web 回退选项。GitHub 令牌仅用于提高公共 API 配额；Brave 则是可选的密钥后端。广泛、独立的 Web 元搜索由内置的 SearXNG 堆栈提供。

快速开始

不克隆即可试用

npx --yes --package github:divyanshu-iitian/SearchForge \
  searchforge search "latest open-source agent frameworks"

首次运行时会从 GitHub 下载并构建软件包。除非选择某个类别，否则搜索会使用基于意图的 auto 路由。

零密钥本地 CLI

git clone https://github.com/divyanshu-iitian/SearchForge.git
cd SearchForge
npm install
npm run build

node dist/cli.js search "latest open-source agent frameworks"
node dist/cli.js search "retrieval augmented generation" --category academic
node dist/cli.js search "local LLM tooling" --category community
node dist/cli.js read "https://example.com"
node dist/cli.js doctor

使用私有 SearXNG 进行完整 Web 搜索

docker compose up --build

curl -s http://localhost:3000/v1/search \
  -H "content-type: application/json" \
  -d '{"query":"open source vector databases","category":"web","limit":5}'

这会在端口 3000 上启动 SearchForge，并在端口 8080 上启动一个启用了 JSON 的私有 SearXNG。在对外开放此堆栈之前，请更改 SearXNG 密钥，设置 SEARCHFORGE_API_KEY，并在受信任的代理处终止 TLS。

免费工具

按能力搜索

searchforge search "latest open-source agent frameworks"
searchforge search "browser agent" --category code
searchforge search "semantic reranking" --category academic --json
searchforge search "Show HN search engine" --category community

默认的 auto 类别会检测代码、学术和时效性 / 社区类信号，并在 Web 回退的同时查询匹配的来源类型。指定类别可避免查询无关的服务商。显式指定的 providers 列表会覆盖类别路由，适用于评估场景。

将 URL 读取为 Markdown

searchforge read "https://example.com/article"

read_url 仅接受公开的 HTTP(S) URL。凭据、localhost、私有 IP 字面量和非 Web 协议均会被拒绝。响应设有大小限制和超时，并会被缓存。

诊断完整检索路径

searchforge doctor

Doctor 会执行真实且有界的探测，并报告每个提供方的访问层级、能力、延迟和错误。某个来源失败时会返回 degraded，而不是给出误导性的非此即彼状态。

MCP

SearchForge 提供三个 stdio 工具：

• web_search — 路由式、可直接用于引用的结构化搜索
• read_url — 从公开 URL 获取整洁的 Markdown
• search_status — 实时能力和延迟报告

{
  "mcpServers": {
    "searchforge": {
      "command": "node",
      "args": ["/absolute/path/to/SearchForge/dist/mcp.js"],
      "env": {
        "SEARCHFORGE_SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}

搜索和状态工具除了返回易读文本，也会返回 MCP 结构化内容。

无需克隆，即可直接从 GitHub 运行 MCP 服务：

{
  "mcpServers": {
    "searchforge": {
      "command": "npx",
      "args": [
        "--yes",
        "--package",
        "github:divyanshu-iitian/SearchForge",
        "searchforge-mcp"
      ]
    }
  }
}

SearchForge 也已发布到 官方 MCP Registry， 名称为 io.github.divyanshu-iitian/searchforge。要通过支持 Docker 命令的任意 MCP 客户端，直接运行由 Registry 提供的 OCI 镜像：

{
  "mcpServers": {
    "searchforge": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/divyanshu-iitian/searchforge-mcp:0.2.0"
      ]
    }
  }
}

REST API

搜索

POST /v1/search
Content-Type: application/json

{
  "query": "open source reranking models",
  "category": "academic",
  "limit": 8,
  "language": "en",
  "freshness": "month",
  "safeSearch": "moderate"
}

{
  "schemaVersion": "1.0",
  "query": "open source reranking models",
  "category": "academic",
  "results": [
    {
      "title": "Example work",
      "url": "https://doi.org/10.0000/example",
      "snippet": "Authors · Publisher · journal-article",
      "source": "crossref",
      "sources": ["crossref"],
      "score": 0.016393
    }
  ],
  "providers": [
    {
      "provider": "crossref",
      "ok": true,
      "latencyMs": 241,
      "resultCount": 8
    }
  ],
  "tookMs": 243,
  "cached": false
}

读取

POST /v1/read
Content-Type: application/json

{"url":"https://example.com/article"}

其他端点：

GET /healthz       Process liveness
GET /v1/providers  Configured capabilities and access tiers
GET /v1/doctor     Live dependency health

请参阅完整的 OpenAPI 契约。

TypeScript SDK

import {
  CrossrefProvider,
  GithubProvider,
  JinaReader,
  SearchForge,
} from "searchforge-rag";

const forge = new SearchForge({
  providers: [new GithubProvider(), new CrossrefProvider()],
  reader: new JinaReader(),
  timeoutMs: 8_000,
});

const evidence = await forge.search({
  query: "agentic retrieval",
  category: "academic",
  limit: 10,
});

const page = await forge.read("https://example.com/research");

在 npm 发布版本推出之前：

npm install github:divyanshu-iitian/SearchForge

提供方详情

提供方	能力	访问	启用方式
SearXNG	网页	可自托管，无供应商费用	SEARCHFORGE_SEARXNG_URL
Wikipedia	网页知识回退	无需密钥	始终启用
GitHub	代码仓库	无需密钥；每小时 60 次未经身份验证的 REST 请求，搜索限制更严格	始终启用
Crossref	学术元数据	无需密钥；建议提供 mailto	始终启用
HN Algolia	社区	无需密钥；可用性由社区运营方保障	始终启用
Jina Reader	URL 转 Markdown	无需密钥；当前公布的免密额定配额为 20 RPM	始终启用
Brave Search	网页	API 密钥	BRAVE_SEARCH_API_KEY

SearchForge 有意不配置公共 SearXNG 实例。它们通常会禁用 JSON 或限制自动化流量；Docker 部署方案是稳定的免费路径。

工作原理

Agent / RAG / MCP client
           |
      validate + route
           |
  +--------+---------+-----------+
  |        |         |           |
 web      code    academic   community       read_url
  |        |         |           |              |
SearXNG  GitHub   Crossref   Hacker News    Jina Reader
Wikipedia
  +--------+---------+-----------+
           |
 normalize -> canonicalize -> deduplicate -> reciprocal-rank fusion
           |
 versioned evidence + provenance + per-source health

每个幂等的提供方调用都有独立的可中止超时。某个服务中断不会抹去健康来源的结果。去重前会移除跟踪参数，并且所有提供结果的提供方都会保留在 sources 中。

这种能力优先的设计受到 Agent Reach 的启发。Agent Reach 帮助 Agent 直接使用许多上游工具；SearchForge 则以稳定、可嵌入的检索 API 补充这一方案，供 RAG 应用使用。

配置

变量	默认值	用途
SEARCHFORGE_SEARXNG_URL	未设置	私有 SearXNG 基础 URL
GITHUB_TOKEN	未设置	可选的 GitHub 配额提升
CROSSREF_MAILTO	未设置	Crossref 礼貌池身份标识
BRAVE_SEARCH_API_KEY	未设置	可选的 Brave 后端
SEARCHFORGE_API_KEY	未设置	REST bearer 或 x-api-key
SEARCHFORGE_PORT	3000	REST 端口
SEARCHFORGE_HOST	127.0.0.1	绑定地址
SEARCHFORGE_TIMEOUT_MS	8000	每个依赖的超时时间
SEARCHFORGE_CACHE_TTL_MS	300000	内存缓存 TTL
SEARCHFORGE_CACHE_MAX_ENTRIES	500	缓存条目上限
SEARCHFORGE_RATE_LIMIT	60	每客户端每分钟请求数

生产环境边界

• 绑定到公共接口前，请先设置 API 密钥。
• 搜索结果和页面内容均是不可信输入；请对其进行分隔，并应用提示词注入防御措施。
• 内置缓存和速率限制器仅在进程内生效。运行多个副本时，请使用共享基础设施。
• 对外显示的错误中不包含提供商响应正文和凭据。
• healthz 用于证明进程正在运行；/v1/doctor 用于检查依赖项。

请参阅 SECURITY.md、CONTRIBUTING.md 和 CHANGELOG.md。

原则

1. 证据优先于生成的答案
2. 优先采用免费和可自托管的方案，避免厂商锁定
3. 部分结果优于彻底失败
4. 如实报告功能和配额
5. 稳定的契约和明确的来源信息
6. 默认不进行遥测

许可证

MIT © Divyanshu。

如果 SearchForge 对你的 Agent 有帮助，请为仓库点星，并在 Discussions 中分享你的集成方案。