@jharding/mcp Server Searxng

SearXNG MCP 服务（增强错误处理分支）

这是 kevinwatt/mcp-server-searxng 的一个分支，增强了错误提示和参数验证，专为改善与 AI Agent 配合使用时的体验而设计。

此 MCP 服务实现与 SearXNG 集成，提供注重隐私的元搜索功能，并为大模型 Agent 提供改进后的反馈。

面向大模型和初学者

如何获取指定范围的结果：

• 获取结果 1-10：设置 offset=0、max_results=10
• 获取结果 11-20：设置 offset=10、max_results=10
• 获取结果 40-43：设置 offset=39、max_results=4

重要提示：

• 请勿使用 page 翻页。请使用 offset 和 max_results。
• offset 从零开始计数：offset=0 表示从第一个结果开始。
• max_results 表示要获取的结果数量（而不是最后一个结果的序号）。

常见模式表：

所需结果	offset	max_results
1-10	0	10
11-20	10	10
21-30	20	10
40-43	39	4

示例：

{ "offset": 39, "max_results": 4 }

功能

• 元搜索：合并多个搜索引擎的结果
• 注重隐私：不追踪、不分析用户画像
• 多种类别：支持综合、新闻、科学、文件、图片、视频等类别
• 语言支持：可使用指定语言或所有语言进行搜索
• 时间范围筛选：按天、周、月或年筛选结果
• 安全搜索：提供三个级别的安全搜索筛选
• 故障转移支持：提供多个 SearXNG 实例以确保可靠性
• 结构化 JSON 响应：以结构化格式提供搜索结果，便于通过程序访问

增强错误处理功能

• 改进的参数验证：清晰说明所有参数的有效格式
• 上下文相关的错误提示：详细说明提供的内容与预期内容之间的差异
• 适合大模型的描述：针对大模型理解优化的 Schema 描述
• 基于示例的反馈：错误提示中包含正确格式的示例
• 增强的调试日志：更详细地记录参数验证问题

为什么要创建此分支？

创建此分支是为了解决 AI Agent（尤其是 qwen3 等模型）与 MCP 工具交互时遇到的特定问题。主要改进包括：

1. 为大模型提供更好的错误提示：增强错误响应，清楚说明出了什么问题，让大模型更容易理解并纠正。

2. 明确格式要求：提供更详细的 Schema 定义，帮助避免使用简写日期格式（例如，用“3d”代替“day”）等常见错误。

3. 对比式错误反馈：验证失败时，错误提示会同时显示收到的内容和预期内容，帮助 Agent 从错误中学习。

4. 基于示例的学习：错误提示中包含有效值的具体示例，并明确指出应避免使用的无效格式。

5. 结构化 JSON 响应：web_search 工具以结构化 JSON 格式返回搜索结果，方便应用通过程序处理搜索结果及其元数据、评分和分类信息。

这些改动旨在减少 AI Agent 通过 MCP 协议使用此工具时遇到的阻碍，从而减少错误并改善整体用户体验。

安装

手动安装

npm install -g @jharding_npm/mcp-server-searxng

从源代码安装

git clone https://github.com/jhstatewide/mcp-server-searxng.git
cd mcp-server-searxng
npm install
npm run build

用法

直接运行

mcp-server-searxng

与 Dive Desktop 配合使用

1. 在 Dive Desktop 中点击“+ Add MCP Server”
2. 复制并粘贴以下配置：

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": [
        "-y",
        "@jharding_npm/mcp-server-searxng"
      ]
    }
  }
}

3. 点击“Save”安装 MCP 服务

使用示例

基本搜索：

# Returns structured JSON results
web_search("artificial intelligence news")

带筛选条件的高级搜索：

# Search with specific parameters
web_search("climate change", {
  "time_range": "week",
  "language": "en",
  "safesearch": 1
})

参数控制示例：

# Pagination: Get results 21-30 with custom content length
web_search("artificial intelligence", {
  "max_results": 10,
  "offset": 20,
  "content_length": 300
})

# Large batch: Get 50 results with short snippets
web_search("machine learning", {
  "max_results": 50,
  "offset": 0,
  "content_length": 100
})

工具文档

web_search

在多个引擎中执行元搜索，并返回结构化 JSON 结果。

输入：

• query（字符串，必填）：要搜索的文本
• max_results（数字，可选，默认值为 10）：要返回的最大结果数（1-100）
• offset（数字，可选，默认值为 0）：要跳过的结果数（从 0 开始计数）
• content_length（数字，可选，默认值为 200）：每条结果内容摘要的最大字符数（50-1000）
• page（数字，可选，默认值为 1）：页码（高级选项，请改用 offset/max_results）
• language（字符串，可选，默认值为 'all'）：语言代码（例如 'en'、'all'）
• time_range（字符串，可选，默认值为 'all_time'）：'all_time'、'day'、'week'、'month' 或 'year'
• safesearch（数字，可选，默认值为 1）：0 = 无，1 = 中等，2 = 严格

**输出：**采用以下格式的结构化 JSON 响应：

{
  "results": [
    {
      "title": "Title of the search result",
      "url": "https://www.example.com",
      "content": "Content of the search result (truncated to 2 sentences if long)",
      "score": 0.85,
      "category": "news",
      "engine": "google",
      "publishedDate": "2023-01-01"
    }
  ],
  "metadata": {
    "total_results": 100,
    "time_taken": 0.123,
    "query": "original search query"
  }
}

功能：

• 包含所有可用字段的独立结果对象
• 自动截断内容，便于阅读
• 包含耗时和结果数等搜索元数据
• 提供搜索引擎可用的相关性评分
• 提供每条结果的引擎和类别信息
• 支持通过 offset 和 max_results 参数进行高级分页

开发

git clone https://github.com/jhstatewide/mcp-server-searxng.git
cd mcp-server-searxng
npm install
npm run build
npm start

许可证

此 MCP 服务采用 MIT 许可证授权。详情请参阅 LICENSE 文件。

前置条件

你需要运行本地 SearXNG 实例。设置方法如下：

使用 Docker 运行 SearXNG

快速开始

# Create config directory
mkdir -p searxng

# Create config file
tee searxng/settings.yml << EOF
use_default_settings: true

server:
  bind_address: "0.0.0.0"
  secret_key: "CHANGE_THIS_TO_SOMETHING_SECURE"  # Generate a random key
  port: 8080

search:
  safe_search: 0
  formats:
    - html
    - json

engines:
  - name: google
    engine: google
    shortcut: g

  - name: duckduckgo
    engine: duckduckgo
    shortcut: d

  - name: bing
    engine: bing
    shortcut: b

server.limiter: false
EOF

# Start container
docker run -d \
  --name searxng \
  -p 8080:8080 \
  -v "$(pwd)/searxng:/etc/searxng" \
  searxng/searxng

测试搜索功能

# Test JSON API with curl
curl -v 'http://localhost:8080/search?q=test&format=json'

# Or visit in browser
http://localhost:8080/search?q=test

容器管理

# Stop container
docker stop searxng

# Remove container
docker rm searxng

# View container logs
docker logs searxng

# Enable auto-start on boot
docker update --restart always searxng

--restart always 标志可确保：

• Docker 守护进程启动时，容器会自动启动
• 容器崩溃时，会自动重启
• 除非用户显式停止容器，否则容器停止时会自动重启

自定义配置

编辑 searxng/settings.yml 以：

• 修改搜索引擎列表
• 调整安全设置
• 配置界面语言
• 更改 API 限制

有关详细的配置选项，请参阅 SearXNG 文档

环境变量

• SEARXNG_INSTANCES：以逗号分隔的 SearXNG 实例 URL 列表 默认值：http://localhost:8080

• SEARXNG_USER_AGENT：请求使用的自定义 User-Agent 标头 默认值：MCP-SearXNG/1.0

• SEARXNG_MAX_ATTEMPTS：每个实例的尝试总次数（初始请求 + 重试） 默认值：4（1 次初始尝试 + 3 次重试）

• SEARXNG_RETRY_BASE_DELAY_MS：重试的基础延迟（毫秒，采用指数退避） 默认值：300

• SEARXNG_RETRY_JITTER_MS：每次重试延迟中添加的随机抖动（毫秒） 默认值：100

• SEARXNG_REQUEST_TIMEOUT_MS：每次请求尝试的超时时间（毫秒） 默认值：10000

• SEARXNG_RETRY_SOFT_FAILURES：是否重试响应级软失败，例如结果为空、JSON 格式错误，以及检测到 CAPTCHA/挑战页面 默认值：true

• SEARXNG_RETRY_MAX_DELAY_MS：任何单次重试的最大延迟，包括服务端提供的 Retry-After 默认值：10000

• SEARXNG_RETRY_BUDGET_MS：每个 SearXNG 实例的最大重试延迟预算 默认值：30000

• SEARXNG_CACHE_TTL_MS：内存缓存中成功的原始搜索响应保持新鲜的时长 默认值：300000（5 分钟）

• SEARXNG_STALE_IF_ERROR_MS：上游不可用时，可以提供过期缓存响应的时长 默认值：3600000（1 小时）

• SEARXNG_CIRCUIT_COOLDOWN_MS：上游故障重试耗尽后，实例被暂时抑制的时长 默认值：30000（30 秒）

缓存回退响应会标记 metadata.stale: true、metadata.stale_reason 和 metadata.cached_at。挑战页面和响应格式错误会立即打开熔断器；临时 HTTP 故障则会在有界重试策略耗尽后打开熔断器。成功响应会关闭熔断器。

• NODE_TLS_REJECT_UNAUTHORIZED：设为 '0' 可绕过 SSL 证书验证（用于使用自签名证书的开发环境） 默认值：undefined（启用 SSL 验证）

包含所有选项的配置示例：

{
  "mcpServers": {
    "searxng": {
      "name": "searxng",
      "command": "npx",
      "args": [
        "-y",
        "@jharding_npm/mcp-server-searxng"
      ],
      "env": {
        "SEARXNG_INSTANCES": "http://localhost:8080,https://searx.example.com",
        "SEARXNG_USER_AGENT": "CustomBot/1.0",
        "SEARXNG_MAX_ATTEMPTS": "4",
        "SEARXNG_RETRY_BASE_DELAY_MS": "300",
        "SEARXNG_RETRY_JITTER_MS": "100",
        "SEARXNG_REQUEST_TIMEOUT_MS": "10000",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

当 NODE_ENV=test 时，重试默认值会针对快速、确定性的测试进行优化：

• SEARXNG_RETRY_BASE_DELAY_MS=1
• SEARXNG_RETRY_JITTER_MS=0
• SEARXNG_REQUEST_TIMEOUT_MS=1000

⚠️ 警告：不建议在生产环境中禁用 SSL 证书验证。

默认情况下，安全搜索为关闭状态（0），可返回最完整的结果集。建议用于研究和一般用途，因为启用安全搜索可能会过滤掉相关信息。

该工具现已通过简化架构和默认值，针对小型大模型（7b 模型）进行了优化。

维护者：构建、打包和发布流程

要向 npm 发布新版本：

1. 提升 package.json 中的版本号（例如，改为 0.5.4）：

   # Edit package.json and update the "version" field
   

2. 构建项目：

   npm run build
   # or
   yarn build
   

3. 打包项目（可选，用于验证内容）：

   npm pack
   # This creates a tarball like jharding_npm-mcp-server-searxng-0.5.4.tgz
   # You can inspect it with:
   tar -tzf jharding_npm-mcp-server-searxng-0.5.4.tgz
   

4. 在本地测试打包后的 tarball（可选）：

   npx -y ./jharding_npm-mcp-server-searxng-0.5.4.tgz --help
   # Should show CLI help and not hang
   

5. 发布到 npm：

   npm publish --access public
   

6. 验证已发布的 CLI：

   npx @jharding_npm/mcp-server-searxng@latest --help
   

**注意：**确保你拥有向 npm 发布的正确权限，并且已登录 npm 账户。

版本管理说明

发布新版本时，必须同时更新以下位置中的版本号：

• package.json
• src/index.ts（version 常量）

这样可确保 CLI 显示的版本与已发布的软件包版本一致。