# Agent上网神器

一键让你的 AI Agent 拥有访问整个互联网的超能力。

## 功能

| 工具 | 功能 | 说明 |
|------|------|------|
| `web_scrape` | 网页抓取 | 抓取单个网页并返回干净的 Markdown 内容 |
| `web_crawl` | 网站爬取 | 从起始 URL 开始深度爬取整个网站 |
| `web_map` | 网站地图 | 发现并列出网站上的所有 URL 链接 |
| `web_search` | 网页搜索 | 搜索互联网并返回相关结果 |
| `structured_extract` | 结构化提取 | 使用 AI 从网页中提取结构化数据 |
| `web_interact` | 浏览器交互 | 在网页上执行浏览器自动化操作 |
| `social_read` | 社交媒体阅读 | 阅读社交媒体帖子内容（Twitter/X、Reddit 等公开页面） |

## 安装

```bash
pip install agent-web-superpower
```

开发模式安装（本地开发使用）：

```bash
git clone <your-repo-url>
cd agent-web-superpower
pip install -e .
```

## 前置条件

需要 Firecrawl API Key。免费注册即可获得 500 credits/月：

https://firecrawl.dev

## 配置 Claude Desktop

在 Claude Desktop 的配置文件中添加：

```json
{
  "mcpServers": {
    "agent-web": {
      "command": "python",
      "args": ["-m", "agent_web.server"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-your-api-key-here"
      }
    }
  }
}
```

## 配置其他 MCP 客户端

设置环境变量后直接运行：

```bash
export FIRECRAWL_API_KEY="fc-your-api-key-here"
python -m agent_web.server
```

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `FIRECRAWL_API_KEY` | 是 | - | Firecrawl API 密钥 |
| `FIRECRAWL_API_URL` | 否 | `https://api.firecrawl.dev` | Firecrawl API 地址（自部署用） |

## 工具详细说明

### web_scrape — 网页抓取

抓取单个网页并返回干净的 Markdown 内容。支持多种输出格式。

```json
{
  "url": "https://example.com/article",
  "formats": ["markdown"],
  "max_chars": 16384,
  "only_main_content": true
}
```

### web_crawl — 网站爬取

从起始 URL 开始深度爬取。适合获取整站文档、博客等。

```json
{
  "url": "https://docs.example.com",
  "max_depth": 2,
  "limit": 10
}
```

### web_map — 网站地图

快速发现网站上的所有 URL 链接。

```json
{
  "url": "https://example.com",
  "limit": 100
}
```

### web_search — 网页搜索

搜索互联网并返回相关结果。类搜索引擎体验。

```json
{
  "query": "Python asyncio tutorial",
  "limit": 5
}
```

### structured_extract — 结构化数据提取

使用 AI 从网页中提取结构化数据。只需用自然语言描述你要提取什么。

```json
{
  "urls": ["https://example.com/products"],
  "prompt": "提取所有产品的名称、价格和评分",
  "schema": {
    "type": "object",
    "properties": {
      "products": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "price": {"type": "string"},
            "rating": {"type": "number"}
          }
        }
      }
    }
  }
}
```

### web_interact — 浏览器交互

在网页上执行浏览器自动化操作（点击、输入、等待等）。需要 Firecrawl 付费计划。

```json
{
  "url": "https://example.com/login",
  "actions": "点击登录按钮，输入用户名和密码，然后提交表单",
  "timeout": 30000
}
```

### social_read — 社交媒体阅读

阅读社交媒体帖子内容。支持 Twitter/X、Reddit 等公开页面。

```json
{
  "url": "https://twitter.com/username/status/123456789",
  "max_chars": 8192
}
```

## 免费额度

Firecrawl 提供免费 tier：
- 500 credits/月
- 无需信用卡
- 注册即用：https://firecrawl.dev

## 开发

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

# 运行测试
pytest tests/ -v

# 代码格式化
ruff check src/ tests/
```

## License

MIT