# Local Search Gateway MCP

本项目是一个运行在本地的 **No-paid-API Search Gateway MCP Server**，用于给 Codex / Hermes / AI Agent / Skills / Plugins 提供统一、透明、可控的免费联网搜索入口。

## 当前初始化版本

已落地 Phase 1 的基础闭环：

- MCP stdio server
- `search_web`
- `fetch_url`
- `search_extract`
- `health`
- DuckDuckGo HTML 搜索适配器
- Bing HTML 搜索适配器
- 静态 HTML 正文抽取
- 短期内存缓存
- `NO_PAID_API=true` 强约束语义
- `SEARCH_PROXY_MODE=env` 配置语义与 health 透明输出

> 当前版本不接任何付费搜索 API，不写死代理，不自动切换代理节点。

## 安装

```bash
npm install
npm run build
```

## 本地开发

```bash
npm run dev
```

## 运行

```bash
npm run build
npm start
```

## Codex MCP 配置示例

```toml
[mcp_servers.local_search]
command = "node"
args = ["/absolute/path/to/local-search-gateway-mcp/dist/server.js"]

[mcp_servers.local_search.env]
NO_PAID_API = "true"
SEARCH_PROXY_MODE = "env"
SEARCH_ENGINE_ORDER = "duckduckgo_html,bing_html"
SEARCH_HEADLESS = "false"
```

如果用户自己需要代理，请自行在 MCP env 中传入：

```toml
[mcp_servers.local_search.env]
HTTP_PROXY = "http://127.0.0.1:7890"
HTTPS_PROXY = "http://127.0.0.1:7890"
ALL_PROXY = "socks5://127.0.0.1:7891"
```

## MCP Tools

### `search_web`

```json
{
  "query": "ceramic candle holder importer Germany",
  "limit": 5,
  "policy": "free_auto"
}
```

### `fetch_url`

```json
{
  "url": "https://example.com",
  "max_chars": 4000
}
```

### `search_extract`

```json
{
  "query": "site:example.com products",
  "limit": 3,
  "mode": "abstract"
}
```

### `health`

```json
{}
```

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---:|---|
| `NO_PAID_API` | `true` | 语义强约束，不使用付费搜索 API |
| `SEARCH_PROXY_MODE` | `env` | 只继承用户环境变量代理配置 |
| `SEARCH_ENGINE_ORDER` | `duckduckgo_html,bing_html` | 搜索源顺序 |
| `SEARCH_TIMEOUT_MS` | `15000` | 单次请求超时 |
| `SEARCH_USER_AGENT` | `Mozilla/5.0 ...` | 搜索请求 UA |
| `SEARCH_HEADLESS` | `false` | 为后续 browser fallback 预留 |

## 产品文档

完整 PRD 见：[`docs/PRD.md`](docs/PRD.md)