dsh-balanced-search

English: A balanced web search plugin / MCP server that round-robins across Keenable (Keen Search) / Exa / Tavily and automatically fails over to the next provider. Returns normalized titles, links, and content summaries.

中文： 均衡搜索插件 / MCP 服务器：把 Keenable（Keen Search）/ Exa / Tavily 三个搜索 API 轮流调用（round-robin），某个服务失败时自动切换下一个，统一返回标题 / 链接 / 摘要。

This repository provides two forms / 本仓库同时提供两种形态：

1. DeepSeek Harness native plugin (recommended) / dsh 原生插件（推荐） — registers balanced_search / balanced_fetch directly as dsh tools, no Python required. / 直接注册 balanced_search / balanced_fetch 两个 dsh 工具，无需 Python。
2. Generic MCP server / 通用 MCP 服务器 — exposes search / fetch over stdio via server.py for any MCP client. / 通过 server.py 以 stdio 方式暴露 search / fetch，可供任意 MCP 客户端使用。

Features / 功能

• Search the web and return titles, links, and content summaries. / 搜索网页，返回标题、链接和内容摘要。
• Fetch a URL and return clean markdown text. / 抓取指定 URL 的网页正文，返回 clean markdown。
• Round-robin across providers with automatic failover. / 三个服务轮流调用，单个服务失败时自动切换下一个。
• Configure API keys via environment variables; providers without a key are skipped. / 通过环境变量配置 API key；未配置的服务不会启用。

Environment Variables / 环境变量

Configure at least one search provider API key / 至少配置一个搜索服务的 API key：

KEENABLE_API_KEY=...
EXA_API_KEY=...
TAVILY_API_KEY=...

The dsh native plugin reads process environment variables directly. The Python MCP server also loads a .env file in the same directory. / dsh 原生插件直接读取进程环境变量；Python MCP 服务器还会自动读取同目录下的 .env 文件。

Directory Structure / 目录结构

File / 文件	Description / 说明
index.js	dsh native plugin entry; registers balanced_search / balanced_fetch / dsh 原生插件入口
cordis.patch.yml	dsh bundle config layer / dsh bundle 配置层
package.json	dsh bundle manifest / dsh bundle 声明
server.py	Generic MCP server (stdio); exposes search / fetch / 通用 MCP server
providers.py	Python providers + round-robin / failover / Python 版 API 客户端与轮换
requirements.txt	Python MCP server dependencies / Python MCP 服务器依赖
.env.example	API key template (copy to .env) / API key 配置模板
.gitignore	Excludes .env, virtualenvs, caches / 排除本地敏感与缓存文件

Install as a dsh Plugin / 安装为 dsh 插件

Requirements / 要求：DeepSeek Harness (dsh) installed, Node.js ≥ 20.

dsh plugin --profile web add github:tianmingwan/dsh-balanced-search

After restarting dsh --profile web, these tools will be available / 重启后会话中会出现两个工具：

• balanced_search
• balanced_fetch

No Python dependencies required / 无需安装 Python 依赖。

Use as a Generic MCP Server / 作为通用 MCP 服务器使用

Install / 安装

python -m venv .venv
# Windows
.venv\Scripts\python.exe -m pip install -r requirements.txt
# Linux / macOS
.venv/bin/python -m pip install -r requirements.txt

Run / 运行

# stdio mode for MCP clients / stdio 模式，供 MCP 客户端连接
python server.py
# or use the virtualenv Python / 或使用虚拟环境中的 Python
.venv\Scripts\python.exe server.py   # Windows
.venv/bin/python server.py           # Linux / macOS

MCP Client Example / MCP 客户端接入示例

{
  "mcpServers": {
    "balanced-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "KEENABLE_API_KEY": "...",
        "EXA_API_KEY": "...",
        "TAVILY_API_KEY": "..."
      }
    }
  }
}

Tool Usage / 工具用法

dsh Native Tools / dsh 原生工具

• balanced_search — parameters / 参数：query / max_results / time_range
• balanced_fetch — parameters / 参数：url / max_chars / live

MCP Tools / MCP 工具

• search — parameters / 参数：query / max_results / time_range
• fetch — parameters / 参数：url / max_chars / live

Parameter Reference / 参数说明

• query (required / 必填): Search keyword or natural language question / 搜索关键词或自然语言问题
• max_results: 1–20, default 8 / 1–20，默认 8
• time_range: day / week / month / year (native for Tavily; Exa maps to startPublishedDate; Keenable maps to published_after) / （Tavily 原生；Exa 映射为 startPublishedDate；Keenable 映射为 published_after）
• max_chars: Maximum characters to return, default 30000, max 50000 / 抓取内容最大字符数，默认 30000，上限 50000
• live: Fetch live from the source (bypass index/cache), default false / 是否实时从源站抓取（绕过索引/缓存），默认 false

Search response / 搜索返回 JSON：

{
  "provider": "keenable|exa|tavily",
  "count": 1,
  "results": [
    {"title": "...", "url": "...", "content": "...", "published_at": "...", "score": 0.5}
  ]
}

Fetch response / 抓取返回 JSON：

{
  "provider": "keenable|exa|tavily",
  "result": {"url": "...", "title": "...", "content": "..."}
}

Configuration Notes / 配置说明

• Change keys / 换 key：dsh plugin uses environment variables; MCP server uses .env or client env injection.
• Failover strategy / 轮换策略：Balancer (currently round-robin + failover; can be changed to weighted or health-aware).
• Add a provider / 新增服务：add a SearchProvider subclass in providers.py and register it in build_balancer(); or add a Provider class in index.js.

License

MIT