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，不写死代理，不自动切换代理节点。

安装

npm install
npm run build

本地开发

npm run dev

运行

npm run build
npm start

Codex MCP 配置示例

[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 中传入：

[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

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

fetch_url

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

search_extract

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

health

{}

环境变量

变量	默认值	说明
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