Searcharvester MCP Server

这是一个自托管网页搜索与页面提取服务适配器，基于 Model Context Protocol (MCP) 运行。 你可以将自建的 Searcharvester 桥接到 Claude Code、Claude Desktop 等大模型客户端，作为它们的原生网络搜索及提取工具。

✨ 特性

• 多端同步配置：无需在多台电脑上配置复杂的绝对路径，支持通过 npx 远程拉起，免安装且配置天然同步。
• 内网优先与网络容灾：支持“内网优先 -> 外网备份”的双重备灾降级。若配置了内网并畅通，搜索秒级返回；若内网离线，无缝切换到外网代理并自动伪装 User-Agent 进行最多 3 次重试。
• 协同回退原生工具：当内外网服务全部挂掉时，工具会自动输出友好引导警示，引导 Claude 临时降级调用自带的 WebSearch 和 WebFetch 兜底。
• 自动级联分页拼接：提取超长网页时（size: "f"），MCP 服务会在后台自动请求所有切片页并拼接整合成完整的 Markdown 输出给模型，免除大模型多次调用工具拉取分页的消耗。

---

🛠️ 环境变量配置

MCP Server 在拉起时将读取以下环境变量进行寻址和鉴权：

环境变量	必须	说明	示例
SEARCHARVESTER_API_KEY	是	你的 Searcharvester 服务校验 Key	你的APIKEY
SEARCHARVESTER_INTERNAL_URL	否	自建局域网内部部署的地址	http://192.168.1.xxx:8001
SEARCHARVESTER_EXTERNAL_URL	否	自建外部公网的代理或反代节点	https://你的外部公网地址

💡 提示：SEARCHARVESTER_INTERNAL_URL 与 SEARCHARVESTER_EXTERNAL_URL 至少配置一项。

---

🚀 多端一键配置使用 (Claude Code / Claude Desktop)

由于你的代码已打包为独立仓库，在所有的设备中，你的全局配置文件（例如 ~/.claude/settings.json）只需配入以下参数。npx 会在两台电脑的后台全自动获取最新代码并跑起来，保证随时同步：

{
  "mcpServers": {
    "searcharvester": {
      "command": "npx",
      "args": ["-y", "github:MaYunFei/searcharvester-mcp"],
      "env": {
        "SEARCHARVESTER_API_KEY": "你的验证KEY",
        "SEARCHARVESTER_INTERNAL_URL": "http://内网地址:8001",
        "SEARCHARVESTER_EXTERNAL_URL": "https://你的外部公网地址"
      }
    }
  }
}

---

🧰 提供的 Tool List

一经连接，客户端将可以使用以下两个工具：

1. searcharvester_search

利用自托管的聚合搜索平台查询网络。

• 参数:
  • query (string, 必须): 查询词。
  • max_results (number): 返回条数（支持 1 - 20，默认 10）。
  • engines (string): 选填，覆盖默认的聚合引擎（如 google,duckduckgo）。
  • categories (string): 选填，分类类型（如 news|images|science）。

2. searcharvester_extract

对提取的目标链接进行 trafilatura 无噪精研提取。

• 参数:
  • url (string, 必须): 需要抓取的页面地址。
  • size (string): 限制大小。's' (约5k字符), 'm' (10k), 'l' (25k), 'f' (全部内容，自动后台拼接多页文件)。