# 🌐 Browser MCP Server

> 用 Playwright + MCP 协议打造的浏览器自动化工具
> 任何支持 MCP 的 Agent（如 OpenClaw、Claude Desktop）都能直接用它控制浏览器 💎

---

## 功能概览

| 类别 | 工具 | 说明 |
|------|------|------|
| 🖥️ **浏览器控制** | `launch` / `close` / `status` | 启动/关闭浏览器 |
| 🧭 **页面导航** | `navigate` / `back` / `forward` / `reload` | 页面跳转 |
| 📝 **内容提取** | `get_text` / `get_links` / `get_inputs` | 提取文本/链接/表单 |
| 📸 **截图** | `screenshot` | 全页/元素截图 |
| 🖱️ **交互操作** | `click` / `fill` / `select` / `check` / `hover` | 点击/填表/选择 |
| 🔍 **搜索等待** | `search` / `wait_for_selector` / `wait_for_url` / `sleep` | 搜索/等待 |
| 📜 **滚动** | `scroll` | 按方向/元素滚动 |

---

## 快速开始

### 安装

```bash
cd ~/workspace/browser-mcp-server
npm install
npx playwright install chromium   # 首次需要安装浏览器
```

### 方式一：直接运行测试

```bash
node test.js
```

### 方式二：启动 MCP Server（供 Agent 使用）

```bash
node src/index.js
```

Server 会以 **Stdio 模式**运行，等待 JSON-RPC 请求。

---

## 工具详细说明

### 🖥️ launch
启动浏览器。

```json
{ "headless": true, "browserType": "chromium" }
```
- `headless`: `true`=后台（默认），`false`=显示 Chrome 窗口
- `browserType`: `chromium` / `firefox` / `webkit`

---

### 🧭 navigate
导航到 URL。

```json
{ "url": "https://www.google.com", "waitUntil": "domcontentloaded" }
```
- `waitUntil`: `domcontentloaded`（默认）/ `load` / `networkidle`

---

### 📝 get_text
提取页面纯文本。

```json
{ "selector": "article", "maxLength": 3000 }
```
- `selector`: CSS 选择器，不填则提取整页
- `maxLength`: 最大字符数，防止超长

---

### 📸 screenshot
截图。

```json
{ "path": "./screenshot.png", "selector": ".chart", "fullPage": true }
```
- `path`: 保存路径
- `selector`: 截取指定元素
- `fullPage`: `true`=整页滚动截图

---

### 🖱️ click
点击元素。

```json
{ "selector": "button.submit", "index": 0, "timeout": 5000 }
```
- `index`: 多个匹配时按序号（从 0 开始）

---

### ✏️ fill
向输入框填入文本。

```json
{ "selector": "input[name='q']", "text": "Hello World", "pressEnter": true }
```
- `pressEnter`: 填入后自动按回车

---

### 📜 scroll
滚动页面。

```json
{ "direction": "down", "amount": 500 }
```
- `direction`: `down` / `up` / `left` / `right`

---

## 在 OpenClaw 中使用

在 OpenClaw 的 `skills/` 目录下创建一个 skill：

```markdown
# Browser Automation MCP Skill

## 启动 MCP Server
command: node
args: ["src/index.js"]
cwd: /Users/sunxiaoxuan/workspace/browser-mcp-server
protocol: stdio
```

或者在代码中直接调用：

```python
# Python 示例（通过 subprocess 调 MCP Server）
import subprocess, json

proc = subprocess.Popen(
    ['node', 'src/index.js'],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    cwd='/Users/sunxiaoxuan/workspace/browser-mcp-server'
)

# 发送 MCP 请求
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "launch",
        "arguments": {"headless": True}
    }
}
```

---

## 与 Siri 语音控制集成

配合 macOS 的 `osascript` 可以实现 Siri 语音控制浏览器！

```applescript
# 例子："Hey Siri，打开 GitHub"
osascript -e 'tell application "System Events"
    keystroke "https://github.com" using command to activate
end tell'
```

配合 MCP Server 可以实现更复杂的语音指令：

> "打开 GitHub，搜索 OpenAI 的最新项目，截一张图"

---

## 项目结构

```
browser-mcp-server/
├── package.json
├── README.md
├── test.js              # 快速测试脚本
└── src/
    ├── index.js         # MCP Server 主程序
    └── browser.js       # Playwright 浏览器管理
```

---

## 常见问题

**Q: 报错 "Executable doesn't exist"**
```bash
npx playwright install chromium
```

**Q: 截图不完整（只截到可见区域）**
设置 `fullPage: true` 截取整页

**Q: 点击报错"元素不可见"**
用 `wait_for_selector` 先等元素出现再操作

**Q: 需要登录怎么办**
先用 `navigate` 打开登录页，`fill` 填入账号密码，`click` 点击登录

---

_庄英琪 💎 制作 | 基于 Playwright + MCP SDK_