Metadata-Version: 2.4
Name: mcp-browser-tools
Version: 0.2.2
Summary: MCP服务器提供浏览器自动化功能，帮助AI模型获取网页信息
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: lxml>=4.9.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: uvicorn>=0.24.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# MCP Browser Tools

MCP (Model Context Protocol) 浏览器自动化工具包，提供网页信息获取和浏览器操作功能，帮助AI模型与网页进行交互。

## 功能特性

- 🌐 **网页导航**：导航到任意URL并等待页面加载完成
- 📄 **内容提取**：获取页面HTML、文本内容和元信息
- 🎯 **元素操作**：点击、填写表单等页面交互操作
- ⏱️ **智能等待**：等待特定元素出现
- 🔍 **信息提取**：提取页面中的链接、图片等结构化信息
- 🔄 **双协议支持**：支持 stdio 和 SSE 两种传输协议
- ⚡ **实时通信**：通过 SSE 实现服务器推送和双向通信

## 安装

```bash
pip install mcp-browser-tools
```

## 快速开始

### 1. 安装 Playwright 浏览器

```bash
playwright install
```

### 2. 运行 MCP 服务器

#### 使用 SSE 协议（默认）
```bash
mcp-browser-tools
```

#### 使用 stdio 协议
```bash
# 设置环境变量
export MCP_TRANSPORT_MODE=stdio
mcp-browser-tools
```

或者通过配置文件：
```python
from mcp_browser_tools.config import ServerConfig

# 使用 SSE（默认）
config = ServerConfig(
    transport_mode="sse",
    sse_host="localhost",
    sse_port=8000
)

# 使用 stdio
config = ServerConfig(
    transport_mode="stdio"
)
```

### 3. 使用示例

```python
import asyncio
import json
from mcp.server.stdio import stdio_server
from mcp_browser_tools.server import main

async def main():
    # MCP服务器会自动连接到stdio
    await stdio_server(main)

if __name__ == "__main__":
    asyncio.run(main())
```

## 可用工具

### 1. navigate_to_url
导航到指定URL

```json
{
  "name": "navigate_to_url",
  "arguments": {
    "url": "https://example.com"
  }
}
```

### 2. get_page_content
获取当前页面内容

```json
{
  "name": "get_page_content",
  "arguments": {}
}
```

### 3. get_page_title
获取页面标题

```json
{
  "name": "get_page_title",
  "arguments": {}
}
```

### 4. click_element
点击页面元素

```json
{
  "name": "click_element",
  "arguments": {
    "selector": "#submit-button"
  }
}
```

### 5. fill_input
填充输入框

```json
{
  "name": "fill_input",
  "arguments": {
    "selector": "#username",
    "text": "myusername"
  }
}
```

### 6. wait_for_element
等待元素出现

```json
{
  "name": "wait_for_element",
  "arguments": {
    "selector": ".result-item",
    "timeout": 30
  }
}
```

### 7. execute_javascript
执行 JavaScript 代码

```json
{
  "name": "execute_javascript",
  "arguments": {
    "script": "return document.title"
  }
}
```

### 8. take_screenshot
截取页面截图

```json
{
  "name": "take_screenshot",
  "arguments": {
    "path": "screenshot.png"
  }
}
```

## 高级功能

### 直接使用 BrowserTools 类

```python
from mcp_browser_tools.browser_tools import BrowserTools
import asyncio

async def main():
    async with BrowserTools() as tools:
        # 导航到网站
        await tools.navigate_to_url("https://example.com")

        # 获取页面内容
        content = await tools.get_page_content()
        print(content["title"])

        # 点击按钮
        await tools.click_element("#submit")

        # 填写表单
        await tools.fill_input("#name", "John Doe")

        # 等待结果
        await tools.wait_for_element(".success-message")

asyncio.run(main())
```

### SSE 客户端连接

```python
import aiohttp
import asyncio

async def connect_sse():
    # 连接到 SSE 端点
    async with aiohttp.ClientSession() as session:
        async with session.get("http://localhost:8000/mcp-sse") as response:
            async for line in response.content:
                line = line.decode('utf-8').strip()
                if line.startswith("data: "):
                    data = json.loads(line[6:])
                    print(f"服务器事件: {data}")

asyncio.run(connect_sse())
```

### 使用 SSE 双向通信

```python
import asyncio
from sse_client_example import MCPClient

async def main():
    client = MCPClient("http://localhost:8000")

    await client.connect()

    # 获取工具列表
    await client.list_tools()

    # 调用工具
    await client.call_tool("navigate_to_url", {
        "url": "https://example.com"
    })

    await client.disconnect()

asyncio.run(main())
```

### 配置传输模式

```python
from mcp_browser_tools.config import ServerConfig

# 创建 SSE 配置
config = ServerConfig(
    transport_mode="sse",
    sse_host="0.0.0.0",
    sse_port=8000
)

# 运行 SSE 服务器
# await main()
```

### 执行 JavaScript

```python
result = await tools.execute_javascript("return window.location.href")
print(result)
```

### 截图功能

```python
await tools.take_screenshot("page.png")
```

## 配置

### 自定义浏览器启动参数

```python
from mcp_browser_tools.browser_tools import BrowserTools
from playwright.async_api import async_playwright

async with BrowserTools() as tools:
    tools.browser = await tools.playwright.chromium.launch(
        headless=True,
        args=[
            '--no-sandbox',
            '--disable-setuid-sandbox',
            '--disable-dev-shm-usage'
        ]
    )
```

### 设置用户代理

```python
tools.context = await tools.browser.new_context(
    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
)
```

## 使用场景

### 1. 网页信息爬取

```json
[
  {"name": "navigate_to_url", "arguments": {"url": "https://news.ycombinator.com"}},
  {"name": "get_page_content", "arguments": {}},
  {"name": "get_page_title", "arguments": {}}
]
```

### 2. 自动化表单填写

```json
[
  {"name": "navigate_to_url", "arguments": {"url": "https://example.com/login"}},
  {"name": "fill_input", "arguments": {"selector": "#username", "text": "user"}},
  {"name": "fill_input", "arguments": {"selector": "#password", "text": "pass"}},
  {"name": "click_element", "arguments": {"selector": "#login-button"}}
]
```

### 3. 等待动态内容

```json
[
  {"name": "navigate_to_url", "arguments": {"url": "https://dynamic-site.com"}},
  {"name": "wait_for_element", "arguments": {"selector": ".dynamic-content", "timeout": 60}},
  {"name": "get_page_content", "arguments": {}}
]
```

## 开发

### 安装开发依赖

```bash
uv add --dev pytest pytest-asyncio black isort mypy
```

### 运行测试

```bash
pytest
```

### 代码格式化

```bash
black mcp_browser_tools/
isort mcp_browser_tools/
```

### 类型检查

```bash
mypy mcp_browser_tools/
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v0.2.2
- 默认使用 SSE (Server-Sent Events) 传输协议

### v0.2.1
- 添加了 SSE (Server-Sent Events) 传输协议支持
- 实现了双协议架构：stdio 和 SSE 两种传输模式
- **默认使用 SSE 传输协议**，提供更好的实时通信体验
- 新增 SSE 服务器端点和 WebSocket 双向通信
- 提供了完整的 SSE 客户端示例
- 修复了入口点配置问题，解决了 uvx 命令的协程警告
- 更新了依赖配置，将已弃用的 `tool.uv.dev-dependencies` 替换为 `dependency-groups.dev`
- 改进了 UTF-8 编码支持，确保所有文件正确使用 UTF-8 编码

### v0.2.0
- 添加了完整的错误处理和重试机制
- 改进了页面内容提取功能，支持自定义提取规则
- 优化了浏览器性能和内存使用
- 增加了详细的日志记录和调试信息
- 完善了配置管理，支持自定义浏览器设置

### v0.1.0
- 初始版本发布
- 支持基本的浏览器操作功能
- MCP 服务器实现