Metadata-Version: 2.4
Name: skysearch
Version: 1.1.1
Summary: Search the web, rank results, fetch any page content.
Author: zimvir
License: MIT
Project-URL: Homepage, https://github.com/zimvir/skysearch
Project-URL: Documentation, https://github.com/zimvir/skysearch#readme
Keywords: search,fetch,bing,bm25,web-scraper,crawler,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: DrissionPage
Requires-Dist: beautifulsoup4
Requires-Dist: lxml
Requires-Dist: lxml_html_clean
Requires-Dist: readability-lxml
Requires-Dist: jieba
Requires-Dist: rank-bm25
Requires-Dist: fastmcp

# SkySearch

为 **AI Agent** 设计的搜索工具，解决"Agent 需要实时、准确获取互联网信息"的问题。

---

## 解决了什么问题

Agent（如 Claude Code）做深度研究时，需要：
1. **搜索** — 从 Bing 获取最新结果
2. **抓取** — 从结果 URL 提取完整内容（很多是 JS 动态渲染）
3. **判断** — 人工或程序判断哪些 URL 值得抓

传统方案的问题：
- `requests` / `curl` 抓不到 JS 渲染的页面（知乎、SPA、单页应用）
- `Selenium` 太重、启动慢、资源占用大
- Google Search API 要钱，Bing API 也要钱

**SkySearch = Bing 搜索 + DrissionPage 动态渲染 + BM25 排序**，轻量、免费、Agent 友好。

---

## 核心能力

| 能力 | 说明 |
|------|------|
| **搜索** | Bing 分页搜索，支持中文分词 |
| **抓取** | 自动检测动态/静态页面，动态页面自动 JS 渲染 |
| **排序** | BM25 对搜索结果按相关性排序（可选） |
| **MCP** | MCP Server 协议，Claude Code 直接调用 |

---

## 安装

```bash
pip install skysearch
```

---

## 快速开始

### Agent 工作流

```
# Step 1: 调用 search工具，获取 Bing搜索结果
search(query="浙江大学 录取 分数线", num=10)

# Step 2: Agent 人工/程序判断哪些 URL 值得抓

# Step 3: 对选中的 URL 调用 fetch 工具
fetch(url="https://example.com", output_mode="info")
```

### MCP Server

Claude Code 等 MCP 客户端可直接调用 `search` 和 `fetch` 工具：

```bash
skysearch-mcp
```

---

## API 设计理念

**`search` + `fetch` 分离**，而不是 `search_and_fetch` 自动完成：

- Agent 可以**先看搜索结果**（快），再决定抓哪些
- 抓取是**按需**的，不浪费资源在无关 URL 上
- 适合深度研究场景，不适合"搜完就完事"的简单场景

---

## 命令行

```bash
# 搜索
skysearch "关键词" -n 10

# 抓取
skysearch --url https://example.com --mode info

# 强制动态渲染
skysearch --url https://example.com --mode info --headed
```

---

## Claude Code 配置

在 `CLAUDE.md` 或项目根目录添加 MCP 服务器配置

```json
{
  "mcpServers": {
    "skysearch": {
      "command": "python",
      "args": ["-m", "skysearch.mcp"],
      "description": "Bing 搜索 + 网页抓取"
    }
  }
}
```

配置后 Claude Code 会自动连接，Agent 可直接调用 `search` 和 `fetch` 工具。

---

## 项目结构

```
skysearch/
├── __init__.py         # 导出 search, fetch, utils
├── cli.py              # Click CLI
├── core/
│   ├── search.py       # Bing 搜索 + BM25
│   ├── fetcher/        # Fetcher 类
│   │   ├── fetcher.py  # 单次 fetch 封装
│   │   ├── static_fetch.py
│   │   ├── dynamic_fetch.py
│   │   └── parse.py
│   ├── utils/          # 解析工具
│   │   ├── utils.py    # parse_bing_results, extract_real_url
│   │   └── ranker.py   # rank_documents
│   └── service.py      # API 封装
└── mcp/
    ├── server.py        # FastMCP 入口
    └── tools.py         # @mcp.tool() search/fetch
```

---

## License

MIT
