<div align="center">

# 🔍 bing-search-cli

**双引擎(Bing + DuckDuckGo)网页搜索与正文抓取工具**

既能作为 Claude Code 插件 / MCP 服务器接入 AI Agent,也能作为独立命令行工具直接使用。

无需 API Key · 无速率限制 · 代理可选

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-43853d.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2.svg)](https://modelcontextprotocol.io)

[中文](#-简介) · [English](#-introduction)

</div>

---

## ✨ 简介

`bing-search-cli` 直接解析 **Bing** 和 **DuckDuckGo** 的公开 HTML 搜索页,解码它们的跳转链接、跨引擎去重,返回干净的结构化结果。三种用法:

- 🧩 **作为 Claude Code 插件** —— 一行命令安装,自动注册 MCP 工具,替代受限的内置 WebSearch;
- 🔌 **作为通用 MCP 服务器** —— 接入 Cline 或任意兼容 [MCP](https://modelcontextprotocol.io) 的客户端,给 Agent 配上不受限的联网搜索能力;
- 💻 **作为命令行工具** —— 在终端里直接搜索、抓取网页正文。

## 🎯 特性

| 特性 | 说明 |
| --- | --- |
| 🔀 **双引擎合并** | 一次调用可查 Bing、DuckDuckGo 或两者;`both` 模式自动按域名+标题去重 |
| 🚀 **无速率限制** | 不依赖收费搜索 API,直连公开 HTML 端点 |
| 📄 **正文提取** | `fetch_page` 抽取任意网页的可读正文(剥离脚本、导航、页脚等) |
| 🀄 **中英双语** | 中文查询自动切换 Bing 到 `zh-CN` 市场 |
| 🌐 **代理可选** | 设 `HTTPS_PROXY` / `HTTP_PROXY` 即走代理,不设则直连。**不内置任何代理地址** |
| 🔑 **零密钥** | 开箱即用,不需要注册或申请 API Key |

## 📦 环境要求

- Node.js >= 18(依赖全局 `fetch` 与 `undici`)

## 🧩 作为 Claude Code 插件安装(推荐)

最省事的方式,无需 clone、无需手动配置。在 Claude Code 中先添加本仓库为插件市场,再安装插件:

```text
/plugin marketplace add AusertDream/bing-search-cli
/plugin install bing-search@bing-search
```

安装后插件会自动注册一个走 `npx` 拉取的 MCP 服务器,首次调用时 `npx` 会自动下载并缓存依赖,之后即开即用。插件提供 `bing_search` 与 `fetch_page` 两个工具,Claude 会自动调用。

> 🇨🇳 **代理说明:** 插件通过 `npx` 启动的子进程会继承 Claude Code 的环境变量。国内用户在启动 Claude Code **之前**先设好 `HTTPS_PROXY` / `HTTP_PROXY` 即可让插件走代理(见下文[代理](#-关于代理)章节)。

### 让插件替代内置 WebSearch

注册插件后,Claude 会同时看到内置 `WebSearch` 和本插件的 `bing_search`,并不会自动停用前者。若想强制只走本工具,在 Claude Code 的 settings 里把内置工具加入 `permissions.deny`:

```json
{
  "permissions": {
    "deny": ["WebSearch"]
  }
}
```

## 🔌 手动注册为 MCP 服务器

不想走插件、或在其他 MCP 客户端里用时,可以手动注册。最干净的方式同样是 `npx` 远程拉取,无需 clone:

```bash
claude mcp add bing-search -- npx -y -p github:AusertDream/bing-search-cli bing-search-mcp
```

需要走代理时,带上环境变量:

```bash
claude mcp add bing-search -e HTTPS_PROXY=http://127.0.0.1:7890 -- npx -y -p github:AusertDream/bing-search-cli bing-search-mcp
```

在 Cline 等客户端的 `mcp.json` 里手写也可以:

```json
{
  "mcpServers": {
    "bing-search": {
      "command": "npx",
      "args": ["-y", "-p", "github:AusertDream/bing-search-cli", "bing-search-mcp"],
      "env": {
        "HTTPS_PROXY": "http://127.0.0.1:7890",
        "HTTP_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}
```

## 💻 作为命令行工具安装

全局安装,任意目录直接用 `bing-search` 命令(无需 clone):

```bash
npm install -g github:AusertDream/bing-search-cli
```

或者一次性运行,不安装:

```bash
npx -y -p github:AusertDream/bing-search-cli bing-search search "你的查询"
```

### 命令行用法

```bash
# 搜索(默认:10 条结果、lang=en、engine=both)
bing-search search "rust async runtime comparison"

# 更多结果 + 中文 + 仅用 Bing
bing-search search "开源大模型推理框架" 15 zh-CN bing

# 抓取并提取网页正文(默认上限 8000 字符)
bing-search fetch "https://example.com/article" 5000
```

**参数顺序:**

| 命令 | 位置参数 |
| --- | --- |
| `search` | `<查询词> [结果数] [语言] [引擎]` |
| `fetch` | `<网址> [最大字符数]` |

> `引擎` 可选 `bing` / `duckduckgo` / `both`,默认 `both`。

## 🛠️ 从源码安装(开发/二次开发)

```bash
git clone https://github.com/AusertDream/bing-search-cli.git
cd bing-search-cli
npm install
npm link   # 可选:把 bing-search 命令链接到全局
```

直接调用脚本而不全局链接:

```bash
node cli.mjs search "你的查询"
```

## 🧰 提供的工具

**`bing_search`** —— 网页搜索

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `query` | string | — | 查询词(中英文均可)。**必填** |
| `engine` | string | `both` | `bing` / `duckduckgo` / `both` |
| `num_results` | number | `10` | 返回结果数上限(1–20) |
| `lang` | string | `en` | 搜索语言,如 `en`、`zh-CN` |

**`fetch_page`** —— 抓取并提取网页正文

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `url` | string | — | 目标网址。**必填** |
| `max_length` | number | `8000` | 返回正文的最大字符数 |

## ⚙️ 工作原理

- **Bing**:解析 `bing.com/search` 中的 `li.b_algo` 区块,并把 base64 编码的 `ck/a?u=` 跳转链接还原成真实 URL。
- **DuckDuckGo**:解析 `html.duckduckgo.com/html/` 中的 `.result` 区块,解开 `uddg=` 跳转参数,并跳过广告结果。
- **both**:合并两个引擎的结果,再按 `域名 + 标题` 去重。

> ⚠️ 由于依赖搜索引擎的公开 HTML 结构,若它们改版,解析逻辑可能需要相应更新。

## 🌐 关于代理

代理由环境变量控制:设置 `HTTPS_PROXY` 或 `HTTP_PROXY` 即启用,不设则直连。代码中**不硬编码任何代理地址**。

> 🇨🇳 **国内用户请注意:必须配置代理。** Bing 与 DuckDuckGo 在中国大陆网络环境下通常无法直接访问(DuckDuckGo 被屏蔽,Bing 国际版亦不稳定),不挂代理会连接超时、搜不到结果。请务必先设置代理再使用:
>
> ```bash
> export HTTPS_PROXY=http://127.0.0.1:7890   # 改成你自己的代理地址端口
> export HTTP_PROXY=http://127.0.0.1:7890
> ```
>
> 作为插件或 MCP 服务器时,在启动 Claude Code 前设好上述环境变量,或把代理写进 `mcp.json` 的 `env` 块(见上文 MCP 配置示例)。

## 🤝 贡献 / Contributing

欢迎 Issue 与 PR。引擎改版导致解析失效时,修复解析器的 PR 尤其受欢迎。

## 📄 许可证

[MIT](./LICENSE) © AusertDream

<br>

---

<div align="center">

# 🔍 bing-search-cli &nbsp;(English)

</div>

## 🌟 Introduction

A dual-engine (**Bing + DuckDuckGo**) web search and page-fetch tool. It scrapes the public HTML search pages of Bing and DuckDuckGo, decodes their redirect URLs, deduplicates across engines, and returns clean structured results. Three ways to use it:

- 🧩 **As a Claude Code plugin** — install with one command, auto-registers the MCP tools, replaces the rate-limited built-in WebSearch;
- 🔌 **As a generic MCP server** — plug it into Cline or any [MCP](https://modelcontextprotocol.io)-compatible client to give your agent unrestricted web search;
- 💻 **As a standalone CLI** — run searches and extract page text right from your terminal.

No API keys required.

## 🎯 Features

| Feature | Description |
| --- | --- |
| 🔀 **Two engines, one call** | Query Bing, DuckDuckGo, or both. `both` merges and deduplicates by domain + title |
| 🚀 **No rate-limit gates** | Hits the public HTML endpoints directly instead of a paid API |
| 📄 **Page extraction** | `fetch_page` pulls the main readable text out of any URL (strips scripts, nav, footers) |
| 🀄 **CJK-aware** | Chinese queries automatically switch Bing to the `zh-CN` market |
| 🌐 **Optional proxy** | Set `HTTPS_PROXY` / `HTTP_PROXY` to use a proxy; unset for direct connections. **No proxy is hardcoded** |
| 🔑 **Zero keys** | Works out of the box, no signup |

## 📦 Requirements

- Node.js >= 18 (uses the global `fetch` and `undici`).

## 🧩 Install as a Claude Code plugin (recommended)

The easiest path — no clone, no manual config. Add this repo as a plugin marketplace, then install the plugin:

```text
/plugin marketplace add AusertDream/bing-search-cli
/plugin install bing-search@bing-search
```

The plugin auto-registers an MCP server launched via `npx`. On first call, `npx` downloads and caches the dependencies, then it just works. The plugin exposes two tools, `bing_search` and `fetch_page`, which Claude invokes automatically.

> **Proxy note:** The `npx`-launched child process inherits Claude Code's environment variables. Set `HTTPS_PROXY` / `HTTP_PROXY` **before** launching Claude Code to route the plugin through a proxy (see [Proxy](#-proxy-1)).

### Make the plugin replace the built-in WebSearch

After installing, Claude sees both the built-in `WebSearch` and this plugin's `bing_search`; it does not disable the former automatically. To force everything through this tool, add the built-in to `permissions.deny` in your Claude Code settings:

```json
{
  "permissions": {
    "deny": ["WebSearch"]
  }
}
```

## 🔌 Register manually as an MCP server

If you'd rather skip the plugin, or use it in another MCP client, register it by hand. The cleanest way is the same `npx` remote pull, no clone:

```bash
claude mcp add bing-search -- npx -y -p github:AusertDream/bing-search-cli bing-search-mcp
```

With a proxy:

```bash
claude mcp add bing-search -e HTTPS_PROXY=http://127.0.0.1:7890 -- npx -y -p github:AusertDream/bing-search-cli bing-search-mcp
```

Or hand-write it in a client's `mcp.json`:

```json
{
  "mcpServers": {
    "bing-search": {
      "command": "npx",
      "args": ["-y", "-p", "github:AusertDream/bing-search-cli", "bing-search-mcp"],
      "env": {
        "HTTPS_PROXY": "http://127.0.0.1:7890",
        "HTTP_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}
```

## 💻 Install as a CLI

Install globally to use the `bing-search` command anywhere (no clone):

```bash
npm install -g github:AusertDream/bing-search-cli
```

Or run once without installing:

```bash
npx -y -p github:AusertDream/bing-search-cli bing-search search "your query"
```

### CLI usage

```bash
# Search (defaults: 10 results, lang=en, engine=both)
bing-search search "rust async runtime comparison"

# More results, Chinese, Bing only
bing-search search "开源大模型推理框架" 15 zh-CN bing

# Fetch and extract a page's main text (default max 8000 chars)
bing-search fetch "https://example.com/article" 5000
```

**Argument order:**

| Command | Positional args |
| --- | --- |
| `search` | `<query> [num_results] [lang] [engine]` |
| `fetch` | `<url> [max_length]` |

> `engine` is one of `bing` / `duckduckgo` / `both` (default `both`).

## 🛠️ Install from source (development)

```bash
git clone https://github.com/AusertDream/bing-search-cli.git
cd bing-search-cli
npm install
npm link   # optional: link the bing-search command globally
```

Call the script directly without linking:

```bash
node cli.mjs search "your query"
```

## 🧰 Exposed tools

**`bing_search`** — search the web.

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string | — | Search query (English or Chinese). **Required** |
| `engine` | string | `both` | `bing` / `duckduckgo` / `both` |
| `num_results` | number | `10` | Max results to return (1–20) |
| `lang` | string | `en` | Search language, e.g. `en`, `zh-CN` |

**`fetch_page`** — fetch and extract readable text from a URL.

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | string | — | URL to fetch. **Required** |
| `max_length` | number | `8000` | Max characters of returned content |

## ⚙️ How it works

- **Bing**: parses `li.b_algo` blocks from `bing.com/search` and decodes the base64 `ck/a?u=` redirect wrappers back to real URLs.
- **DuckDuckGo**: parses `.result` blocks from `html.duckduckgo.com/html/` and unwraps the `uddg=` redirect params, skipping ad results.
- **both**: concatenates results from both engines, then deduplicates by `domain + title`.

> ⚠️ Because this relies on the engines' public HTML markup, result parsing may need updating if they change their page structure.

## 🌐 Proxy

Proxy is controlled entirely by environment variables. Set `HTTPS_PROXY` or `HTTP_PROXY` to enable it; leave them unset for direct connections. No proxy address is hardcoded.

> 🇨🇳 **Users in mainland China: a proxy is required.** Bing and DuckDuckGo are generally not reachable from within mainland China (DuckDuckGo is blocked, and international Bing is unstable), so without a proxy you'll hit connection timeouts and get no results. Set a proxy first:
>
> ```bash
> export HTTPS_PROXY=http://127.0.0.1:7890   # replace with your own proxy host:port
> export HTTP_PROXY=http://127.0.0.1:7890
> ```
>
> When running as a plugin or MCP server, set these before launching Claude Code, or put the proxy in the `env` block of `mcp.json` (see the MCP config example above).

## 🤝 Contributing

Issues and PRs welcome — especially parser fixes when an engine changes its markup.

## 📄 License

[MIT](./LICENSE) © AusertDream