内容
<div align="center">
# 搜索锻造
### 面向LLM、智能体和RAG的开源网络搜索API和MCP服务器
[](https://github.com/divyanshu-iitian/SearchForge/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
[](https://modelcontextprotocol.io)
[](https://divyanshu-iitian.github.io/SearchForge/)
[](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.divyanshu-iitian/searchforge)
**一个本地网关。四种搜索能力。干净的Markdown。REST、MCP、CLI和TypeScript。**
[网站](https://divyanshu-iitian.github.io/SearchForge/) · [快速开始](#快速开始) · [免费工具](#免费工具) · [MCP](#mcp) · [API](#rest-api) · [设计](#工作原理)
</div>
---
**搜索锻造（SearchForge）是一个免费、开源的网络搜索API和MCP服务器，适用于LLM、AI智能体和检索增强生成（RAG）管道。** 它提供了一个可预测的检索层，而无需强制每个项目集成付费搜索服务提供商。SearchForge将每个查询路由到正确的源，隔离提供商故障，去除重复URL，融合排名，并将公共页面转换为LLM-ready Markdown。
它**不**生成答案，隐藏引用，爬取公共SearXNG实例，或发送遥测数据。
## 您获得的功能
| 功能 | 默认源 | 成本/凭证 |
| ----------- | ----------------------------------- | ------------------------------ |
| `网络` | 维基百科；可选私有SearXNG | 无密钥/自托管 |
| `代码` | GitHub仓库搜索 | 无密钥；令牌可选 |
| `学术` | Crossref作品和DOI元数据 | 无密钥 |
| `社区` | Hacker News via Algolia | 无密钥，社区服务 |
| `读取网址` | Jina Reader | 无密钥，目前限速 |
SearchForge一开始启用所有无密钥适配器。GitHub令牌仅提高公共API配额，Brave仍是可选的密钥后端。通过包含的SearXNG堆栈提供广泛、独立的网络元搜索。
## 快速开始
### 零密钥本地CLI
```bash
git clone https://github.com/divyanshu-iitian/SearchForge.git
cd SearchForge
npm install
npm run build
node dist/cli.js search "开源代理框架" --category code
node dist/cli.js search "检索增强生成" --category academic
node dist/cli.js search "本地LLM工具" --category community
node dist/cli.js read "https://example.com"
node dist/cli.js doctor
```
### 使用私有SearXNG进行完整网络搜索
```bash
docker compose up --build
```
```bash
curl -s http://localhost:3000/v1/search \
-H "content-type: application/json" \
-d '{"query":"开源向量数据库","category":"web","limit":5}'
```
这会在端口`3000`上启动SearchForge，并在端口`8080`上启动私有、启用JSON的SearXNG。在公开堆栈之前，请更改SearXNG密钥，设置`SEARCHFORGE_API_KEY`，并在受信任的代理上终止TLS。
## 免费工具
### 按功能搜索
```bash
searchforge search "浏览器代理" --category code
searchforge search "语义重新排序" --category academic --json
searchforge search "Show HN搜索引擎" --category community
```
类别阻止无关提供者被查询。显式`providers`列表覆盖类别路由，这对于评估很有用。
### 将网址读取为Markdown
```bash
searchforge read "https://example.com/article"
```
`read_url`仅接受公共HTTP（S）网址。凭证、本地主机、私有IP字面量和非Web协议被拒绝。响应是大小受限、超时和缓存的。
### 诊断整个检索路径
```bash
searchforge doctor
```
医生执行真实、有界的探测，并报告每个提供者的访问层、功能、延迟和错误。失败的源产生`degraded`，而不是误导性的全有或全无状态。
## MCP
SearchForge公开了三个stdio工具：
- `web_search` — 路由、引用准备的结构化搜索
- `read_url` — 来自公共网址的干净Markdown
- `search_status` — 实时功能和延迟报告
```json
{
"mcpServers": {
"searchforge": {
"command": "node",
"args": ["/absolute/path/to/SearchForge/dist/mcp.js"],
"env": {
"SEARCHFORGE_SEARXNG_URL": "http://localhost:8080"
}
}
}
}
```
搜索和状态工具返回MCP结构化内容以及可读文本。
SearchForge也在[官方MCP注册中心](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.divyanshu-iitian/searchforge)中发布为`io.github.divyanshu-iitian/searchforge`。要直接从任何支持Docker命令的MCP客户端运行注册中心支持的OCI镜像：
```json
{
"mcpServers": {
"searchforge": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"ghcr.io/divyanshu-iitian/searchforge-mcp:0.2.0"
]
}
}
}
```
## REST API
### 搜索
```http
POST /v1/search
Content-Type: application/json
{
"query": "开源重新排序模型",
"category": "academic",
"limit": 8,
"language": "en",
"freshness": "month",
"safeSearch": "moderate"
}
```
```json
{
"schemaVersion": "1.0",
"query": "开源重新排序模型",
"category": "academic",
"results": [
{
"title": "示例作品",
"url": "https://doi.org/10.0000/example",
"snippet": "作者 · 出版商 · 期刊文章",
"source": "crossref",
"sources": ["crossref"],
"score": 0.016393
}
],
"providers": [
{
"provider": "crossref",
"ok": true,
"latencyMs": 241,
"resultCount": 8
}
],
"tookMs": 243,
"cached": false
}
```
### 读取
```http
POST /v1/read
Content-Type: application/json
{"url":"https://example.com/article"}
```
其他端点：
```text
GET /healthz 进程存活
GET /v1/providers 配置的功能和访问层
GET /v1/doctor 实时依赖健康
```
查看完整的[OpenAPI合约](openapi.yaml)。
## TypeScript SDK
```ts
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: "代理检索",
category: "academic",
limit: 10,
});
const page = await forge.read("https://example.com/research");
```
在发布npm版本之前：
```bash
npm install github:divyanshu-iitian/SearchForge
```
## 提供者详情
| 提供者 | 功能 | 访问 | 启用 |
| ------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------ | ------------------------- |
| [SearXNG](https://docs.searxng.org/) | 网络 | 自托管，无供应商费用 | `SEARCHFORGE_SEARXNG_URL` |
| 维基百科 | 网络知识备份 | 无密钥 | 始终 |
| [GitHub](https://docs.github.com/rest/search/search) | 代码仓库 | 无密钥；60个未经身份验证的REST请求/小时，搜索有更严格的限制 | 始终 |
| [Crossref](https://www.crossref.org/documentation/retrieve-metadata/rest-api/) | 学术元数据 | 无密钥；推荐`mailto` | 始终 |
| [HN Algolia](https://hn.algolia.com/api) | 社区 | 无密钥；社区运营的可用性 | 始终 |
| [Jina Reader](https://jina.ai/reader/) | 网址到Markdown | 无密钥；记录的无密钥配额目前为20 RPM | 始终 |
| [Brave Search](https://brave.com/search/api/) | 网络 | API密钥 | `BRAVE_SEARCH_API_KEY` |
SearchForge不会故意配置公共SearXNG实例。它们通常禁用JSON或限制自动化流量；Docker堆栈是稳定的免费路径。
## 工作原理
```text
智能体 / RAG / MCP客户端
|
验证 + 路由
|
+--------+---------+-----------+
| | | |
网络 代码 学术 社区 读取网址
| | | | |
SearXNG GitHub Crossref Hacker News Jina Reader
维基百科
+--------+---------+-----------+
|
标准化 -> 规范化 -> 去重 -> 互惠排名融合
|
版本化证据 + 来源 + 每源健康
```
每个独立提供者的调用都有自己的可中止超时。一次故障不会抹去健康的结果。跟踪参数在去重之前被移除，每个贡献提供者都保留在`sources`中。
这种优先考虑功能的设计灵感来自[Agent Reach](https://github.com/Panniantong/Agent-Reach)。Agent Reach帮助智能体直接操作许多上游工具；SearchForge通过为RAG应用提供一个稳定、可嵌入的检索API来补充这种方法。
## 配置
| 变量 | 默认值 | 目的 |
| ------------------------------- | ----------: | ------------------------------ |
| `SEARCHFORGE_SEARXNG_URL` | 未设置 | 私有SearXNG基准网址 |
| `GITHUB_TOKEN` | 未设置 | 可选的GitHub配额增加 |
| `CROSSREF_MAILTO` | 未设置 | Crossref礼貌池身份 |
| `BRAVE_SEARCH_API_KEY` | 未设置 | 可选的Brave后端 |
| `SEARCHFORGE_API_KEY` | 未设置 | REST承载者或`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](SECURITY.md)、[CONTRIBUTING.md](CONTRIBUTING.md)和[CHANGELOG.md](CHANGELOG.md)。
## 原则
1. 证据优于生成的答案
2. 免费和自托管路径优于供应商锁定
3. 部分结果优于完全失败
4. 诚实的能力和配额报告
5. 稳定的合同和明确的来源
6. 默认情况下无遥测
## 许可证
MIT © Divyanshu。
如果SearchForge帮助您的智能体，请标星该仓库并在[讨论](https://github.com/divyanshu-iitian/SearchForge/discussions)中分享您的集成。
