dsh-balanced-search

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

Install / 安装

python -m venv .venv

# 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

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.