Metadata-Version: 2.4
Name: mcp-smart-searcher
Version: 0.1.1
Summary: A smart MCP server for multi-engine web search with AI-powered results
Project-URL: Homepage, https://github.com/lispking/ferris-search
Project-URL: Repository, https://github.com/lispking/ferris-search
Author: Smart Searcher Team
License: Apache-2.0
Keywords: ai,claude,mcp,search,tavily,web
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp[cli]>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# MCP Smart Searcher

一个智能的 MCP（Model Context Protocol）服务器，支持多引擎网络搜索并返回 AI 增强结果，使用 Python 编写。

## 特性

- **多引擎并发** — 一次调用，同时在多个搜索引擎上搜索
- **8 个搜索引擎** — Bing、DuckDuckGo、Brave、百度、掘金、GitHub、GitHub 代码、Tavily
- **2 个 MCP 工具** — `web_search`（搜索）和 `fetch_web_content`（内容提取）
- **AI 增强结果** — Tavily 提供 AI 生成的答案摘要和相关性评分
- **大多数引擎无需 API Key** — 仅 Brave 和 Tavily 需要
- **按引擎控制代理** — 可为特定搜索引擎单独配置代理
- **智能内容提取** — `fetch_web_content` 支持 prompt 引导的精准提取，内置重试机制

## 安装

### 从 PyPI 安装（推荐）

```bash
pip install mcp-smart-searcher
```

### 使用 uvx

```bash
uvx mcp-smart-searcher
```

## 配置

### Claude Desktop / Cursor

在 MCP 设置中添加：

```json
{
  "mcpServers": {
    "smart-searcher": {
      "command": "uvx",
      "args": ["mcp-smart-searcher"],
      "env": {
        "DEFAULT_SEARCH_ENGINE": "bing"
      }
    }
  }
}
```

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DEFAULT_SEARCH_ENGINE` | `bing` | 未指定 `engines` 参数时的默认引擎 |
| `ALLOWED_SEARCH_ENGINES` | 全部 | 逗号分隔的允许引擎列表 |
| `BRAVE_API_KEY` | — | Brave 搜索必需 |
| `TAVILY_API_KEY` | — | Tavily AI 搜索必需 |
| `GITHUB_TOKEN` | — | 可选，提高 GitHub API 调用频率限制 |
| `USE_PROXY` | `false` | 是否启用 HTTP/SOCKS5 代理 |
| `PROXY_URL` | `http://127.0.0.1:7890` | 代理地址 |
| `PROXY_ENGINES` | （全部） | 逗号分隔的需要使用代理的引擎列表。不设置则所有引擎使用代理。示例：`bing,github` |

#### 代理配置示例

```bash
# 传统模式：所有引擎都使用代理
USE_PROXY=true
PROXY_URL=http://127.0.0.1:7890

# 精准模式：仅 Bing 和 GitHub 使用代理
USE_PROXY=true
PROXY_URL=http://127.0.0.1:7890
PROXY_ENGINES=bing,github

# 完全禁用代理
USE_PROXY=false
```

## MCP 工具

### `web_search`

使用一个或多个搜索引擎同时搜索网络。

```json
{
  "query": "rust async runtime",
  "engines": ["bing", "duckduckgo"],
  "limit": 10
}
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | string | 必填 | 搜索关键词 |
| `engines` | string[] | 服务器默认 | 要使用的搜索引擎列表 |
| `limit` | number | 10 | 每个引擎的最大结果数（1–50） |

支持的引擎：`bing`、`duckduckgo`、`brave`、`baidu`、`juejin`、`github`、`github_code`、`tavily`

| 搜索引擎 | 配置名称 |
|----------|----------|
| Bing | `bing` |
| DuckDuckGo | `duckduckgo` |
| Brave | `brave` |
| 百度 | `baidu` |
| 掘金 | `juejin` |
| GitHub（仓库搜索） | `github` |
| GitHub（代码搜索） | `github_code` |
| Tavily（AI 搜索） | `tavily` |

> **Tavily** 提供 AI 生成的答案摘要和相关性评分，需要配置 `TAVILY_API_KEY`。

### `fetch_web_content`

从任意公开 URL 获取并提取文本内容。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `url` | string | 必填 | 公开的 HTTP/HTTPS URL |
| `prompt` | string | — | 可选，提取提示语（例如"仅提取代码示例"、"总结核心论点"） |
| `max_chars` | number | 30000 | 返回的最大字符数 |

**功能亮点：**
- 智能内容提取：优先查找 `<article>`、`<main>` 或 `#content` 等正文元素
- 自动去噪：移除广告、侧边栏、脚本、样式表、iframe 等干扰元素
- 自动重试：超时或网络错误时自动重试（最多 2 次）
- Prompt 引导输出：设置 `prompt` 参数后，输出会包含提取提示，方便 AI 代理聚焦目标

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 使用 MCP Inspector 调试
mcp dev src/mcp_smart_searcher/server.py
```

## 许可证

Apache-2.0

## 致谢

- 灵感来源于 [ferris-search](https://github.com/lispking/ferris-search)（Rust 版本）
- 基于 [FastMCP](https://github.com/anthropics/mcp) 和 [Model Context Protocol](https://modelcontextprotocol.io/) 构建
